NVIDIA cuPQC SDK

https://docs.nvidia.com/cuda/cupqc/
Admin
NVIDIA cuPQC SDK is a high-performance GPU library for post-quantum cryptography and cryptographic...
Tokens:23,758
Snippets:79
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Integrating cuPQC with CMake

Source: https://docs.nvidia.com/cuda/cupqc/installation

Configuration files are provided to simplify the use of cuPQC libraries in CMake projects. This shows how to find the package and link the libraries.

```cmake
find_package(cupqc)
target_link_libraries(YourProgram cupqc)
```

```cmake
find_package(cuhash)
target_link_libraries(YourProgram cuhash)
```

--------------------------------

### Using cuPQC SDK in Your Project

Source: https://docs.nvidia.com/cuda/cupqc/installation

Instructions for including cuPQC SDK header files and commondx in your compilation commands. Requires NVCC 12.4 or newer and LTO flags.

```c++
=c++17=sm_XY
```

--------------------------------

### cuPQC Host Functions API

Source: https://docs.nvidia.com/cuda/cupqc/api/cupqc/functions

This section details the host functions available in the cuPQC API. These functions are designed to be called from the host (CPU) and interact with the cuPQC library. The documentation includes function signatures, parameter descriptions, and usage examples.

```APIDOC
cuPQC Host Functions:

This section provides documentation for functions that can be called from the host (CPU) to interact with the cuPQC library.

Example Function Signature:
`cudaError_t cupqcHostFunction(param1_type param1, param2_type param2, ...)`

Parameters:
- `param1`: Description of the first parameter, including its type and constraints.
- `param2`: Description of the second parameter, including its type and constraints.

Return Value:
- `cudaError_t`: Returns a CUDA error code indicating success or the type of error encountered.

Usage:
Demonstrates how to call the host function with example arguments and how to check the return status for errors.

Related Functions:
- Links to other relevant host functions or device methods within the cuPQC API.
```

--------------------------------

### cuPQC Host Code for ML-KEM Key Generation

Source: https://docs.nvidia.com/cuda/cupqc/cupqc_usage

Host function to launch the cuPQC key generation kernel. It allocates device memory for keys, workspace, and entropy, launches the kernel, and transfers results back to the host.

```C++
voidml_kem_keygen(std::vector<uint8_t>public_keys,std::vector<uint8_t>secret_keys,constunsignedintbatch)
{
/*
     * Set up for utilizing cuPQC ML-KEM Keygen.
     * Allocates device workspace for computing
     */
autolength_public_key=MLKEM512Key::public_key_size;
autolength_secret_key=MLKEM512Key::secret_key_size;

autoworkspace=make_workspace<MLKEM512Key>(batch);
autorandombytes=get_entropy<MLKEM512Key>(batch);
/*
     * Allocate device memory for public and secret keys
     */
uint8_t*d_public_key=nullptr;
uint8_t*d_secret_key=nullptr;

cudaMalloc(&d_public_key,length_public_key*batch);//These are uint8_t so length and batch are in bytes
cudaMalloc(&d_secret_key,length_secret_key*batch);

keygen_kernel<<<batch,MLKEM512Key::BlockDim>>>(d_public_key,d_secret_key,workspace,randombytes);

/*
     * Transfer generated keys to the host for communication or storage
     */
cudaMemcpy(public_keys.data(),d_public_key,length_public_key*batch,cudaMemcpyDeviceToHost);
cudaMemcpy(secret_keys.data(),d_secret_key,length_secret_key*batch,cudaMemcpyDeviceToHost);

/*
     * Delete device memory associated with the cryptographic process.
     */
cudaFree(d_public_key);
cudaFree(d_secret_key);
destroy_workspace(workspace);
release_entropy(randombytes);
}
```

--------------------------------

### Merkle Tree Aliases

Source: https://docs.nvidia.com/cuda/cupqc/api/cuhash/operators

Provides convenient aliases for Merkle Trees with supported sizes and precisions in the format MERKLE_<PRECISION>_<SIZE>. <PRECISION> can be BYTE (uint8_t) or FIELD (uint32_t), and <SIZE> is the raw number. For example, MERKLE_BYTE_2048 is an alias for decltype(Algorithm<algorithm::MERKLE>()+MerkleSize<2048>()+Precision<uint8_t>()+Function<function::Merkle>()+Block()).

```C++
MERKLE_<PRECISION>_<SIZE>
```

--------------------------------

### cuHash API Overview

Source: https://docs.nvidia.com/cuda/cupqc/api/cuhash_api

Provides an overview of the cuHash API, linking to detailed sections for operators, traits, and device methods.

```APIDOC
cuHash:
  Operators: Links to documentation for cuHash operators.
  Traits: Links to documentation for cuHash traits.
  Device Methods: Links to documentation for cuHash device methods.
```

--------------------------------

### cuPQC API Documentation

Source: https://docs.nvidia.com/cuda/cupqc/license

API documentation for the cuPQC library, covering operators, traits, device methods, and host functions.

```APIDOC
cuPQC API Reference:

Operators:
  - Description: Details on operators available in the cuPQC library.
  - Link: https://docs.nvidia.com/cuda/cupqc/api/cupqc/operators.html

Traits:
  - Description: Information on traits used within the cuPQC library.
  - Link: https://docs.nvidia.com/cuda/cupqc/api/cupqc/traits.html

Device Methods:
  - Description: Documentation for methods executable on the device.
  - Link: https://docs.nvidia.com/cuda/cupqc/api/cupqc/methods.html

Host Functions:
  - Description: Documentation for functions executable on the host.
  - Link: https://docs.nvidia.com/cuda/cupqc/api/cupqc/functions.html
```

--------------------------------

### cuPQC API Reference

Source: https://docs.nvidia.com/cuda/cupqc/api/cupqc_api

This section provides the API reference for the cuPQC library, covering its core components like operators, traits, device methods, and host functions. It serves as a central point for developers to understand and utilize the library's capabilities.

```APIDOC
cuPQC API Reference:
  Operators: Documentation for cuPQC operators.
  Traits: Documentation for cuPQC traits.
  Device Methods: Documentation for cuPQC device methods.
  Host Functions: Documentation for cuPQC host functions.
```

--------------------------------

### cuPQC SDK Release Notes Summary

Source: https://docs.nvidia.com/cuda/cupqc/release_notes

Summary of changes and new features in the cuPQC SDK releases. Highlights include new hash functions, APIs, and performance enhancements.

```APIDOC
Release Notes:
  - Version 0.4.0:
    - Added Poseidon2 hash function to cuHash.
    - Introduced Merkle Tree API using cuHash functions.
  - Version 0.3.0:
    - Introduced cuPQC Software Development Kit (SDK) as a single package.
    - cuPQC SDK includes cuPQC library and cuHash library.
    - cuHash library provides GPU accelerated SHA-2, SHA-3, SHAKE hashing algorithms.
    - Performance improvements for cuPQC's ML-KEM and ML-DSA algorithms.
```

--------------------------------

### NVIDIA SDK Authorized Users and Pre-Release Terms

Source: https://docs.nvidia.com/cuda/cupqc/license

This section defines who can access and use the NVIDIA SDK, including employees, contractors, and academic users. It also outlines the terms and risks associated with using pre-release (alpha, beta, preview) SDK versions, emphasizing they are not for production use.

```APIDOC
1.3 Authorized Users
You may allow employees and contractors of your entity or of your subsidiary(ies) to access and use the SDK from your secure network to perform work on your behalf.
If you are an academic institution you may allow users enrolled or employed by the academic institution to access and use the SDK from your secure network.
You are responsible for the compliance with the terms of this Agreement by your authorized users. If you become aware that your authorized users didn’t follow the terms of this Agreement, you agree to take reasonable steps to resolve the non-compliance and prevent new occurrences.

1.4 Pre-Release SDK
The SDK versions identified as alpha, beta, preview or otherwise as pre-release, may not be fully functional, may contain errors or design flaws, and may have reduced or different security, privacy, accessibility, availability, and reliability standards relative to commercial versions of NVIDIA software and materials. Use of a pre-release SDK may result in unexpected results, loss of data, project delays or other unpredictable damage or loss. You may use a pre-release SDK at your own risk, understanding that pre-release SDKs are not intended for use in production or business-critical systems. NVIDIA may choose not to make available a commercial version of any pre-release SDK. NVIDIA may also choose to abandon development and terminate the availability of a pre-release SDK at any time without liability.
```

--------------------------------

### cuHash Merkle Tree Device Methods

Source: https://docs.nvidia.com/cuda/cupqc/api/cuhash/methods

Contains device-level methods for managing and verifying Merkle trees. This includes creating leaves, generating the entire tree, generating proofs for specific leaves, and verifying the integrity of a proof.

```APIDOC
create_leaf<HASH, Precision>(leaf_data: Precision*, hash_output: HASH&, leaf_index: size_t)
  Creates a leaf node for the Merkle tree.
  Parameters:
    leaf_data: Pointer to the data for the leaf.
    hash_output: Reference to the HASH object to store the leaf's hash.
    leaf_index: The index of the leaf.

generate_tree<HASH, Precision>(tree_data: Precision*, root_hash: HASH&, tree_structure: tree<N, HASH, Precision>&)
  Generates the Merkle tree from leaf data.
  Parameters:
    tree_data: Pointer to the array of leaf data.
    root_hash: Reference to the HASH object to store the root hash.
    tree_structure: Reference to the tree object to store the tree structure.

generate_proof<HASH, Precision>(proof_object: proof<N, HASH, Precision>&, leaf_data: Precision*, leaf_index: uint32_t, tree_structure: tree<N, HASH, Precision>&)
  Generates a Merkle proof for a given leaf.
  Parameters:
    proof_object: Reference to the proof object to store the generated proof.
    leaf_data: Pointer to the data of the leaf for which the proof is generated.
    leaf_index: The index of the leaf.
    tree_structure: Reference to the tree object.

verify_proof<HASH, Precision>(proof_: proof<N, HASH, Precision>&, leaf: Precision*, leaf_index: uint32_t, root: Precision*, hash_output: HASH&)
  Verifies a Merkle proof for a leaf against a given root.
  Parameters:
    proof_: The proof object to verify.
    leaf: The leaf data to verify.
    leaf_index: The index of the leaf.
    root: The expected root hash.
    hash_output: Reference to the HASH object to store the computed hash during verification.
```

--------------------------------

### cuPQC Library Overview

Source: https://docs.nvidia.com/cuda/cupqc/introduction

The cuPQC library leverages NVIDIA GPUs for high-performance, batched, and secure implementations of post-quantum cryptographic algorithms. It includes NIST standardized algorithms ML-KEM and ML-DSA.

```APIDOC
cuPQC Library:
  Purpose: High-performance, batched, secure implementations of post-quantum cryptographic algorithms on NVIDIA GPUs.
  Algorithms: ML-KEM, ML-DSA (NIST standardized).
  Usage: Refer to cuPQC Library documentation for detailed instructions.
```

--------------------------------

### cuHash API Documentation

Source: https://docs.nvidia.com/cuda/cupqc/license

API documentation for the cuHash library, covering operators, traits, and device methods.

```APIDOC
cuHash API Reference:

Operators:
  - Description: Details on operators available in the cuHash library.
  - Link: https://docs.nvidia.com/cuda/cupqc/api/cuhash/operators.html

Traits:
  - Description: Information on traits used within the cuHash library.
  - Link: https://docs.nvidia.com/cuda/cupqc/api/cuhash/traits.html

Device Methods:
  - Description: Documentation for methods executable on the device.
  - Link: https://docs.nvidia.com/cuda/cupqc/api/cuhash/methods.html
```

--------------------------------

### cuPQC SDK Requirements

Source: https://docs.nvidia.com/cuda/cupqc/requirements

Lists the essential software and hardware components needed to utilize the cuPQC SDK, including CUDA Toolkit, compilers, and specific NVIDIA GPU architectures.

```APIDOC
Requirements:
  - CUDA Toolkit 12.4 or newer
  - Supported CUDA compiler
  - Supported host compiler (C++17 required)
  - (Optionally) CMake (version 3.20 or greater)
  - x86_64 or Arm64 CPU
  - NVIDIA GPU with architectures: 70, 75, 80, 86, 87, 89, 90
```

--------------------------------

### NVIDIA SDK License Grant and Distribution Terms

Source: https://docs.nvidia.com/cuda/cupqc/license

This section details the non-exclusive, non-transferable license granted for using and distributing NVIDIA SDK components. It specifies requirements for applications incorporating SDK elements, including additional functionality, proper attribution, and adherence to license terms.

```APIDOC
1. License.

1.1 Grant
Subject to the terms of this Agreement, NVIDIA hereby grants you a non-exclusive, non-transferable license, without the right to sublicense (except as expressly provided in this Agreement) to:
  1. Install and use the SDK, and
  2. Distribute the binary files, files identified as samples, and headers as incorporated into a software application that meets the distribution requirements indicated in this Agreement.

1.2 Distribution Requirements
These are the distribution requirements for you to exercise the distribution grant:
  1. Your application must have material additional functionality, beyond the included portions of the SDK.
  2. The distributable portions of the SDK shall only be accessed by your application.
  3. The following notice shall be included in modifications and derivative works of sample source code distributed: “This software contains source code provided by NVIDIA Corporation.”
  4. Unless a developer tool is identified in this Agreement as distributable, it is delivered for your internal use only.
  5. The terms under which you distribute your application must be consistent with the terms of this Agreement, including (without limitation) terms relating to the license grant and license restrictions and protection of NVIDIA’s intellectual property rights. Additionally, you agree that you will protect the privacy, security and legal rights of your application users.
  6. You agree to notify NVIDIA in writing of any known or suspected distribution or use of the SDK not in compliance with the requirements of this Agreement, and to enforce the terms of your agreements with respect to distributed SDK.
```

--------------------------------

### cuHash API Reference

Source: https://docs.nvidia.com/cuda/cupqc/api/cupqc_api

This section provides the API reference for the cuHash library, detailing its operators, traits, and device methods. It is a companion to the cuPQC documentation.

```APIDOC
cuHash API Reference:
  Operators: Documentation for cuHash operators.
  Traits: Documentation for cuHash traits.
  Device Methods: Documentation for cuHash device methods.
```

--------------------------------

### cuHash Hashing Device Methods

Source: https://docs.nvidia.com/cuda/cupqc/api/cuhash/methods

Provides an overview of the device methods for cuHash, a hashing library within cuPQC. It details the 'reset', 'update', and 'finalize' operations essential for cryptographic hashing on CUDA devices.

```APIDOC
HASH::reset()
  Resets the hash state to the initial state. Should be called before the first call to update().

HASH::update(const uint8_t* message_, const size_t message_length_)
  Appends a message into the hash state for non-Poseidon2 hash functions. Can be called multiple times.
  Parameters:
    message: Buffer containing the message.
    message_length: Length of the message buffer.

HASH::update(const uint32_t* message_, const size_t message_length_)
  Appends a message into the hash state for Poseidon2 hash functions. Can be called multiple times.
  Parameters:
    message: Buffer containing the message.
    message_length: Length of the message buffer.

HASH::finalize()
  Finalizes the hash state. Should be called after the last update() and before digest().
```

--------------------------------

### Define ML-KEM-512 Key Generation Descriptor

Source: https://docs.nvidia.com/cuda/cupqc/cupqc_usage

Constructs a cuPQC descriptor for ML-KEM-512 key generation using 128 threads. This involves combining the ML_KEM_512 operator, Function<function::Keygen>(), Block(), and BlockDim<128>().

```C++
//cuPQC header

#include<cupqc.hpp>

//cuPQC descriptor
//ML KEM 512 Key Generation with 128 threads

usingMLKEM512Key=decltype(ML_KEM_512()
+Function<function::Keygen>()
+Block()
+BlockDim<128>());

```

--------------------------------

### Poseidon2-BabyBear Security Notes (cuPQC 0.4.0)

Source: https://docs.nvidia.com/cuda/cupqc/security_notes

Details the introduction of Poseidon2-BabyBear with 16 and 24 state widths. It highlights the impact of diffusion matrix and round constant selection on algorithm security, noting the use of Plonky3 values. The document advises caution regarding the security of this newly proposed algorithm and its parameters, urging users to evaluate its suitability for their applications.

```APIDOC
Poseidon2-BabyBear (cuPQC 0.4.0):
  Variants: 16 and 24 state widths
  Implementation Details:
    - Diffusion matrix and round constants selected with various generation methods.
    - Values from Plonky3 used in this release.
  Security Considerations:
    - Security depends significantly on selected parameters.
    - Newly proposed cryptographic algorithm.
    - Users should remain aware of potential risks and evaluate suitability for specific use cases.
```

--------------------------------

### Launch SHA3 Kernel with cuHash

Source: https://docs.nvidia.com/cuda/cupqc/cuhash_usage

Launches a SHA3 hashing kernel using the cuHash API. It takes a message buffer and outputs a digest buffer, with hashing performed on each thread block. It's recommended to use blocks of 32 threads for optimal performance.

```C++
void hash_sha3(std::vector<uint8_t>& digest, std::vector<uint8_t>& msg)
{
uint8_t* d_msg;
uint8_t* d_digest;
cudaMalloc(reinterpret_cast<void**>(&d_msg), msg.size());
cudaMalloc(reinterpret_cast<void**>(&d_digest), digest.size());

cudaMemcpy(d_msg, msg.data(), msg.size(), cudaMemcpyHostToDevice);

hash_sha3_kernel<<<1,32>>>(d_digest, d_msg, msg.size());

cudaMemcpy(digest.data(), d_digest, digest.size(), cudaMemcpyDeviceToHost);

cudaFree(d_msg);
cudaFree(d_digest);
}
```

--------------------------------

### CUDA CUPQC Poseidon2 Configuration Options

Source: https://docs.nvidia.com/cuda/cupqc/api/cuhash/operators

This table outlines the supported configurations for the Poseidon2 hash function, detailing the relationship between Width, Capacity, and the resulting alias. It specifies the number of full and partial rounds, and the S-box used for each configuration.

```APIDOC
Name | Width | Capacity | Full Round | Partial Round | Sbox | Alias
---|---|---|---|---|---|---
Poseidon2-8-16 | 16 | 8 | 8 | 13 | x7 | POSEIDON2_8_16()
Poseidon2-8-24 | 24 | 8 | 8 | 21 | x7 | POSEIDON2_8_24()
```

--------------------------------

### cuHash Merkle Tree Proof Object

Source: https://docs.nvidia.com/cuda/cupqc/api/cuhash/methods

Defines the structure and members of a Proof object generated from a Merkle Tree, used for verifying leaves. It includes proof size, digest size, node pointers, and indices. Also lists host functions for memory allocation and deallocation.

```APIDOC
template<>
class proof<N, HASH, Precision>
  // A Proof object generated from a Merkle Tree, used to verify a leaf in the Merkle Tree. This object is a convenience container for the Proof Data.
  // Parameters:
  //   N: The number of leaves in the base of the tree.
  //   HASH: The hash function used to generate the Merkle Tree. This is the same as the hash function used to generate the Merkle Tree Data.
  //   Precision: The data type of the leaves of the Merkle Tree. This is the same as the data type of the leaves of the Merkle Tree Data.
  // Members:
  //   size: The size of the Merkle Tree Data. This is log2(N) where N is the number of leaves in the base of the tree.
  //   digest_size: The digest size of the hash function used to generate the Merkle Tree. This is the length of the Precision array that each node is.
  //   nodes: A pointer to the Merkle Tree Proof Data. This is a global memory array containing log2(N) nodes, where N is the number of leaves in the base of the tree that the proof is generated from. Each node is of type Precision, with length digest_size.
  //   indices: A global memory array of 32-bit unsigned integers containing log2(N) indices, these indices are the locations of the proof nodes in the original tree.
  // Functions:
  //   allocate_proof: Allocates the Proof Data to global memory. (Host function)
  //   free_proof: Frees the Proof Data from global memory. (Host function)
```

--------------------------------

### CUPQC Merkle Tree generate_proof

Source: https://docs.nvidia.com/cuda/cupqc/api/cuhash/methods

Generates a Merkle proof for a specific leaf in the Merkle Tree. This function requires the proof object, the leaf data, the leaf's index, and the Merkle tree structure.

```C++
template<>
__device__ void MERKLE::generate_proof<HASH, Precision>(
     cupqc::MERKLE::generate_proof<HASH, Precision>::proof<N, HASH, Precision>&proof_,
     const Precision*leaf_,
     const uint32_t leaf_index_,
     const cupqc::tree<N, HASH, Precision>&merkle_tree_ )
```

--------------------------------

### cuPQC Library Functionality

Source: https://docs.nvidia.com/cuda/cupqc/requirements

Highlights the capabilities of the cuPQC library, emphasizing its role in post-quantum cryptography and its design as a device extension library for CUDA kernels.

```APIDOC
cuPQC Functionality:
  - Implements cryptographic algorithms resistant to quantum computers.
  - Optimized for NVIDIA GPUs for performance gains.
  - Designed with side-channel security measures.
  - Acts as a Device Extensions library for use within CUDA kernels.
  - Includes sample kernels demonstrating library usage.
```

--------------------------------

### cuHash Merkle Tree Objects

Source: https://docs.nvidia.com/cuda/cupqc/api/cuhash/methods

Defines the data structures used for Merkle trees and proofs within the cuHash library. This includes the 'tree' object for representing the Merkle tree and the 'proof' object for storing proof data.

```APIDOC
tree<N, HASH, Precision>
  Represents a Merkle tree structure.

proof<N, HASH, Precision>
  Represents a Merkle proof for a specific leaf.
```

--------------------------------

### Supported Compilers for cuPQC SDK

Source: https://docs.nvidia.com/cuda/cupqc/requirements

Specifies the compatible CUDA and host C++ compilers required for developing with the cuPQC SDK.

```APIDOC
Supported Compilers:
  CUDA Compilers:
    - NVCC 12.4+ (CUDA Toolkit 12.4 or newer)
  Host C++ Compilers:
    - GCC 7+
    - Clang 9+
    - Aarch64-GCC 7+
```

--------------------------------

### cuHash Hashing Device Methods

Source: https://docs.nvidia.com/cuda/cupqc/api/cuhash/methods

Provides device-level methods for hashing operations using the cuHash library. Includes functions for resetting the hash state, updating the hash with data, finalizing the hash computation, and retrieving the digest.

```APIDOC
reset()
  Resets the internal state of the hash object.

update(data: const uint8_t*, size: size_t)
  Updates the hash with a block of data.
  Parameters:
    data: Pointer to the data buffer.
    size: The size of the data buffer.

update(data: const uint32_t*, size: size_t)
  Updates the hash with a block of 32-bit unsigned integers.
  Parameters:
    data: Pointer to the data buffer.
    size: The number of uint32_t elements.

finalize()
  Finalizes the hash computation and returns the hash digest.

digest(output: uint8_t*, size: size_t)
  Retrieves the computed hash digest.
  Parameters:
    output: Buffer to store the digest.
    size: The size of the output buffer.

digest(output: uint32_t*, size: size_t)
  Retrieves the computed hash digest as an array of uint32_t.
  Parameters:
    output: Buffer to store the digest.
    size: The number of uint32_t elements.
```

--------------------------------

### cuPQC Library - Post-Quantum Cryptography

Source: https://docs.nvidia.com/cuda/cupqc/index

The cuPQC library provides ML-KEM and ML-DSA Post-Quantum Cryptography algorithm functions designed for direct embedding into CUDA kernels. It offers high performance, tunability for thread operations (BlockDim), and the ability to fuse PQC operations with other computations, minimizing data movement.

```APIDOC
cuPQC Library:
  - ML-KEM and ML-DSA PQC algorithm functions
  - Designed for embedding into CUDA kernels
  - High performance, minimal global memory data movement
  - Tunable thread operations (BlockDim)
  - Supports fusion with other operations
```

--------------------------------

### PQC Encapsulation

Source: https://docs.nvidia.com/cuda/cupqc/api/cupqc/methods

Performs encapsulation by generating a shared secret and encrypting it as a ciphertext using the provided public key. Requires specific buffer lengths and alignment for ciphertext, shared secret, and public key.

```APIDOC
__device__ void PQC::execute(_uint8_t *ciphertext_, _uint8_t *shared_secret_, _const uint8_t*public_key_, _uint8_t *entropy_, _uint8_t *workspace_, _uint8_t *smem_workspace_ );

Parameters:
  * ciphertext: Buffer for ciphertext (PQC::ciphertext_size, 8-byte aligned).
  * shared_secret: Buffer for shared secret (PQC::shared_secret_size, 8-byte aligned).
  * public_key: Buffer containing public key (PQC::public_key_size, 8-byte aligned).
```

--------------------------------

### cuHash Library Overview

Source: https://docs.nvidia.com/cuda/cupqc/introduction

The cuHash library provides GPU-optimized cryptographic hash functions including SHA-2, SHA-3, SHAKE, and Poseidon2. It also offers a Merkle Tree API compatible with all cuHash functions.

```APIDOC
cuHash Library:
  Purpose: GPU-optimized cryptographic hash functions and Merkle Tree API.
  Hash Functions: SHA-2, SHA-3, SHAKE, Poseidon2.
  Features: Merkle Tree API.
  Usage: Refer to cuHash Library documentation for detailed instructions.
```

--------------------------------

### cuHash Merkle Tree Object

Source: https://docs.nvidia.com/cuda/cupqc/api/cuhash/methods

Defines the structure and members of a Merkle Tree object, which serves as a container for Merkle Tree data. It includes details on tree size, digest size, node pointers, and root pointers. Also lists host functions for memory allocation and deallocation.

```APIDOC
template<>
class tree<N, HASH, Precision>
  // A Merkle Tree object. This object is a convenience container for the Merkle Tree Data.
  // Parameters:
  //   N: The number of leaves in the base of the tree.
  //   HASH: The hash function used to generate the Merkle Tree. This will be a cuHash hash object.
  //   Precision: The data type of the leaves of the Merkle Tree.
  // Members:
  //   size: The size of the Merkle Tree Data. This is 2*N-1 where N is the number of leaves in the base of the tree.
  //   digest_size: The digest size of the hash function used to generate the Merkle Tree. This is the length of the Precision array that each node is.
  //   nodes: A pointer to the Merkle Tree Data. This is a global memory array containing 2*N-1 nodes, where N is the number of leaves in the base of the tree. Each node is of type Precision, with length digest_size.
  //   root: A pointer to the root of the Merkle Tree. This is a global memory array of type Precision, with length digest_size.
  // Functions:
  //   allocate_tree: Allocates the Merkle Tree Data to global memory. (Host function)
  //   free_tree: Frees the Merkle Tree Data from global memory. (Host function)
```

--------------------------------

### ML-KEM (FIPS-203) Operations in cuPQC

Source: https://docs.nvidia.com/cuda/cupqc/requirements

Details the specific Module-Lattice-Based Key Encapsulation Mechanism (ML-KEM) operations supported by the cuPQC library, including key generation, encapsulation, and decapsulation, along with supported parameter sets.

```APIDOC
ML-KEM (FIPS-203) Operations:
  - Key Generation: Efficiently generates cryptographic key pairs.
  - Encapsulation: Securely encapsulates a shared secret.
  - Decapsulation: Recovers the shared secret from encapsulated data.

  Supported Parameter Sets:
  - ML-KEM-512
  - ML-KEM-768
  - ML-KEM-1024
```

--------------------------------

### cuPQC Execute Function (Key Generation)

Source: https://docs.nvidia.com/cuda/cupqc/api/cupqc/methods

The `execute` method of a cuPQC descriptor object is used for cryptographic operations. For key generation, it takes public key, secret key, entropy, and workspace buffers as input. The sizes of these buffers are determined by the PQC descriptor's traits.

```APIDOC
PQC::execute(_..._)

A descriptor objects defines an `execute` method, the signature of which depends on the [`Function`](https://docs.nvidia.com/cuda/cupqc/api/cupqc/operators.html#_CPPv4I_8functionEN5cupqc8FunctionEv "cupqc::Function") operator. Common arguments:

Parameters:
    
  * **entropy** – Source of cryptographic entropy of length [`PQC::entropy_size`](https://docs.nvidia.com/cuda/cupqc/api/cupqc/traits.html#_CPPv4N5cupqc3PQC12entropy_sizeE "cupqc::PQC::entropy_size"), and 8-byte aligned. Should be created by [`get_entropy`](https://docs.nvidia.com/cuda/cupqc/api/cupqc/functions.html#_CPPv4I0EN5cupqc11get_entropyEP7uint8_t6size_t12cudaStream_t "cupqc::get_entropy").
  * **workspace** – Global memory workspace of length [`PQC::workspace_size`](https://docs.nvidia.com/cuda/cupqc/api/cupqc/traits.html#_CPPv4N5cupqc3PQC14workspace_sizeE "cupqc::PQC::workspace_size"), and 8-byte aligned.. Can be allocated by [`make_workspace`](https://docs.nvidia.com/cuda/cupqc/api/cupqc/functions.html#_CPPv4I0EN5cupqc14make_workspaceEP7uint8_t6size_t12cudaStream_t "cupqc::make_workspace").
  * **smem_workspace** – 
Shared memory workspace of length [`PQC::shared_memory_size`](https://docs.nvidia.com/cuda/cupqc/api/cupqc/traits.html#_CPPv4N5cupqc3PQC18shared_memory_sizeE "cupqc::PQC::shared_memory_size"), and 8-byte aligned. Typically allocated by :
```
__shared__uint8_tsmem_workspace[PQC::shared_memory_size];

```

Keygen

__device__voidPQC::execute( 
     _uint8_t *public_key_,      _uint8_t *secret_key_,      _uint8_t *entropy_,      _uint8_t *workspace_,     _uint8_t *smem_workspace_ );
    
Generate public and secret key pair. 

Parameters: 
    
  * **public_key** – Buffer to which the public key will be written. Must be of length [`PQC::public_key_size`](https://docs.nvidia.com/cuda/cupqc/api/cupqc/traits.html#_CPPv4N5cupqc3PQC15public_key_sizeE "cupqc::PQC::public_key_size"), and 8-byte aligned.
  * **secret_key** – Buffer to which the secret key will be written. Must be of length [`PQC::secret_key_size`](https://docs.nvidia.com/cuda/cupqc/api/cupqc/traits.html#_CPPv4N5cupqc3PQC15secret_key_sizeE "cupqc::PQC::secret_key_size"), and 8-byte aligned.
```

--------------------------------

### CUDA CUPQC Entropy Buffer Management

Source: https://docs.nvidia.com/cuda/cupqc/api/cupqc/functions

Allocates, fills, and releases entropy buffers using cryptographically secure randomness for CUPQC algorithms. These functions operate with CUDA streams and handle memory allocation errors by throwing runtime exceptions.

```C++
template<classPQC>
uint8_t*get_entropy( _size_t batch_, _cudaStream_t stream=0_ );
// Allocate and fill the entropy buffer using cryptographically secure randomness for the algorithm described by `PQC`, sufficient for `batch` batches.

voidrelease_entropy(_uint8_t *workspace_, _cudaStream_t stream=0_);
// Release the global memory allocated by [`get_entropy`](https://docs.nvidia.com/cuda/cupqc/api/cupqc/functions.html#_CPPv4I0EN5cupqc11get_entropyEP7uint8_t6size_t12cudaStream_t "cupqc::get_entropy").
```

--------------------------------

### PQC Signing

Source: https://docs.nvidia.com/cuda/cupqc/api/cupqc/methods

Signs a message using the provided secret key. Requires specific buffer lengths and alignment for the signature and secret key. Note that for ML_DSA, signature size may not be a multiple of 8, potentially requiring padding for aligned operations.

```APIDOC
__device__ void PQC::execute(_uint8_t *signature_, _const uint8_t*message_, _const size_t message_length_, _const uint8_t*secret_key_, _uint8_t *entropy_, _uint8_t *workspace_, _uint8_t *smem_workspace_);

Parameters:
  * signature: Buffer for signature (PQC::signature_size, 8-byte aligned).
  * message: Buffer containing the message.
  * message_length: Length of the message buffer.
  * secret_key: Buffer containing secret key (PQC::secret_key_size, 8-byte aligned).

Note: For algorithm::ML_DSA, PQC::signature_size is not a multiple of 8. Padding may be required for aligned operations in batch processing.
```

--------------------------------

### C++ Compilation Flags for cuPQC

Source: https://docs.nvidia.com/cuda/cupqc/cupqc_usage

Specifies the C++ standard and target architecture for compiling programs using cuPQC. The `=c++17` flag indicates C++17 standard support, and `sm_80` specifies the target compute capability for NVIDIA GPUs.

```C++
=c++17=sm_80
```

--------------------------------

### cuHash Library - Cryptographic Hash Functions

Source: https://docs.nvidia.com/cuda/cupqc/index

The cuHash library provides SHA-2, SHA-3, SHAKE, and Poseidon2 hash functions optimized for execution within CUDA kernels. It includes a Merkle Tree API leveraging these hash functions, offering high performance and throughput. The library also supports fusing hashing operations with other computations.

```APIDOC
cuHash Library:
  - SHA-2, SHA-3, SHAKE, and Poseidon2 hash functions
  - Designed for embedding into CUDA kernels
  - Merkle Tree API utilizing provided hash functions
  - High performance and throughput hashing
  - Supports fusion with other operations
```

--------------------------------

### CUDA CUPQC Workspace Management

Source: https://docs.nvidia.com/cuda/cupqc/api/cupqc/functions

Allocates and releases global memory workspaces for CUPQC algorithms. These functions follow CUDA stream semantics and throw runtime errors on allocation failure.

```C++
template<classPQC>
uint8_t*make_workspace( _size_t batch_, _cudaStream_t stream=0_ );
// Allocate the global memory workspace for the algorithm described by `PQC` sufficient for `batch` batches.

voiddestroy_workspace(_uint8_t *workspace_, _cudaStream_t stream=0_);
// Release the global memory allocated by [`make_workspace`](https://docs.nvidia.com/cuda/cupqc/api/cupqc/functions.html#_CPPv4I0EN5cupqc14make_workspaceEP7uint8_t6size_t12cudaStream_t "cupqc::make_workspace").
```

--------------------------------

### cuPQC ML-KEM 512 Key Generation Kernel

Source: https://docs.nvidia.com/cuda/cupqc/cupqc_usage

CUDA kernel for batched ML-KEM 512 key generation using cuPQC. Each thread block computes one public and secret key, utilizing shared memory for efficiency.

```C++
#include<cupqc.hpp>

//cuPQC descriptor
// ML KEM 512 Key Generation with 128 threads
usingMLKEM512Key=decltype(ML_KEM_512()
+Function<function::Keygen>()
+Block()
+BlockDim<128>()));

__global__voidkeygen_kernel(uint8_t*public_keys,uint8_t*secret_keys,uint8_t*workspace,uint8_t*randombytes)
{
// These functions require a fixed amount of shared memory, for which the API provides a trait
__shared__uint8_tsmem_ptr[MLKEM512Key::shared_memory_size];
intblock=blockIdx.x;
autopublic_key=public_keys+block*MLKEM512Key::public_key_size;
autosecret_key=secret_keys+block*MLKEM512Key::secret_key_size;
autoentropy=randombytes+block*MLKEM512Key::entropy_size;
autowork=workspace+block*MLKEM512Key::workspace_size;

MLKEM512Key().execute(public_key,secret_key,entropy,work,smem_ptr);
}
```

--------------------------------

### NVIDIA SDK Updates

Source: https://docs.nvidia.com/cuda/cupqc/license

This clause addresses NVIDIA's right to provide updates, patches, or workarounds for the SDK. Unless separate terms are provided, these updates are considered part of the SDK licensed under the main agreement.

```APIDOC
1.5 Updates
NVIDIA may, at its option, make available patches, workarounds or other updates to this SDK. Unless the updates are provided with their separate governing terms, they are deemed part of the SDK licensed to you as provided in this Agreement.
```

--------------------------------

### cuHash Functionality

Source: https://docs.nvidia.com/cuda/cupqc/requirements

The cuHash library offers optimized implementations of various hash functions, including SHA-2, SHA-3, SHAKE, and Poseidon2. It also provides a Merkle Tree API and can be used as a device extension for single-kernel implementations.

```APIDOC
cuHash Functionality:
  Supported Hash Functions:
    - SHA-2: SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224, SHA-512/256
    - SHA-3: SHA3-224, SHA3-256, SHA3-384, SHA3-512
    - SHAKE: SHAKE128, SHAKE256
    - Poseidon2: Poseidon2-BabyBear
  Merkle Tree API: Utilizes the above hash functions.

  Device Extension: Allows single kernel implementations with hashing algorithms.
  See Device Methods for detailed descriptions of each descriptor’s execution and arguments.
```

--------------------------------

### ML-DSA Operations

Source: https://docs.nvidia.com/cuda/cupqc/requirements

The cuPQC library provides optimized implementations for ML-DSA (Module-Lattice-Based Digital Signature Algorithm) operations, including key generation, signing, and verification. It supports various parameter sets like ML-DSA-44, ML-DSA-65, and ML-DSA-87.

```APIDOC
ML-DSA Operations:
  Key Generation: Generates cryptographic key pairs for digital signatures.
  Signing: Produces a digital signature for a given message.
  Verification: Validates the authenticity of a digital signature.

  Supported Parameter Sets:
    - ML-DSA-44
    - ML-DSA-65
    - ML-DSA-87
```

--------------------------------

### CUPQC Merkle Tree create_leaf

Source: https://docs.nvidia.com/cuda/cupqc/api/cuhash/methods

Creates a leaf node within a Merkle Tree. This function is a template that requires HASH and Precision types to be specified.

```C++
template<>
__device__ void MERKLE::create_leaf<HASH, Precision>(
     Precision *leaf_,
     const Precision*data_,
     HASH &hash_,
     const size_t inbuf_len_ )
```

--------------------------------

### Define SHA-3 256 Hash Descriptor with Warp Configuration

Source: https://docs.nvidia.com/cuda/cupqc/cuhash_usage

This snippet shows how to define a cuHash descriptor for SHA-3 256 hashing using a warp configuration. It includes the necessary cuHash header and namespace usage.

```cpp
//cuHash header

#include<cuhash.hpp>

//We use the cuPQC SDK namespace.

usingnamespacecupqc;

//cuHash descriptor

usingSHA3_256_WARP=decltype(SHA3_256()+Warp());

```

--------------------------------

### Execute SHA-3 Hashing in a CUDA Kernel using cuHash

Source: https://docs.nvidia.com/cuda/cupqc/cuhash_usage

This code demonstrates a CUDA kernel that utilizes a cuHash descriptor (SHA3_256_WARP) to compute a hash. It shows the usage of reset, update, finalize, and digest methods for hashing input data.

```cpp
//cuHash header

#include<cuhash.hpp>

//We use the cuPQC SDK namespace.

usingnamespacecupqc;

//cuHash descriptor

usingSHA3_256_WARP=decltype(SHA3_256()+Warp());

__global__voidhash_sha3_kernel(uint8_t*digest,constuint8_t*msg,size_tinbuf_len)
{
SHA3_256_WARPhash{};
hash.reset();
hash.update(msg,inbuf_len);
hash.finalize();
hash.digest(digest,SHA3_256_WARP::digest_size);
}

```

--------------------------------

### CUPQC Merkle Tree generate_tree

Source: https://docs.nvidia.com/cuda/cupqc/api/cuhash/methods

Generates a Merkle Tree from a collection of leaves. This function should be called after all updates and before the digest operation. It requires the tree buffer, its length, and the tree structure itself.

```C++
template<>
__device__ void MERKLE::generate_tree<HASH, Precision>(
     Precision *leaves_,
     HASH &hash_,
     cupqc::tree<N, HASH, Precision>& merkle_tree_ )
```

--------------------------------

### Poseidon2-BabyBear Internal Diagonal Constants (Width 16)

Source: https://docs.nvidia.com/cuda/cupqc/api/cuhash/poseidon2_babybear_constants

Internal diagonal constants for the Poseidon2-BabyBear algorithm with a width of 16. These constants are part of the internal state update mechanism.

```C++
__constant__ uint32_t internal_diag_array_16[16] = {
  174271892, 1840666551, 1459346590, 86719882,
  863261185, 1543704716, 199992187, 629943947,
  302161721, 1766394318, 1831016228, 566473250,
  1007223973, 30846170, 661675139, 1378994178
};

```

--------------------------------

### cuPQC PQC::execute for Signature Verification

Source: https://docs.nvidia.com/cuda/cupqc/api/cupqc/methods

Verifies the signature of a message using a provided public key. Requires message, signature, public key buffers, and workspace memory. Returns true if the signature is valid, false otherwise. Note potential alignment requirements for specific algorithms like ML-DSA.

```APIDOC
__device__ bool PQC::execute(_const uint8_t* message_, _const size_t message_length_, _const uint8_t* signature_, _const uint8_t* public_key_, _uint8_t *workspace_, _uint8_t *smem_workspace_)
    Verifies the signature of a message using the public key.
    Parameters:
      message: Buffer containing the message.
      message_length: Length of the message buffer.
      signature: Buffer containing the signature. Must be of length PQC::signature_size, and 8-byte aligned.
      public_key: Buffer containing the public key. Must be of length PQC::public_key_size, and 8-byte aligned.
    Returns:
      true if the signature is valid for the given message and public key, false otherwise.
    Note:
      For algorithm::ML_DSA, PQC::signature_size is not a multiple of 8. If performing batches of operations, padding may be required to ensure the signature argument is correctly aligned.
```

--------------------------------

### CUDA CUPQC Algorithm and Security Category Mapping

Source: https://docs.nvidia.com/cuda/cupqc/api/cuhash/operators

This table maps various SHA algorithms to their corresponding CUPQC algorithm types and security categories. It also provides aliases for easier use.

```APIDOC
Name | Algorithm | SecurityCategory | Alias
---|---|---|---
SHA2-224 | algorithm::SHA2_32 | 1 | SHA2_224()
SHA2-256 | algorithm::SHA2_32 | 2 | SHA2_256()
SHA2-384 | algorithm::SHA2_64 | 4 | SHA2_384()
SHA2-512 | algorithm::SHA2_64 | 5 | SHA2_512()
SHA2-512/224 | algorithm::SHA2_64 | 1 | SHA2_512_224()
SHA2-512/256 | algorithm::SHA2_64 | 2 | SHA2_512_256()
SHA3-224 | algorithm::SHA3 | 1 | SHA3_224()
SHA3-256 | algorithm::SHA3 | 2 | SHA3_256()
SHA3-384 | algorithm::SHA3 | 4 | SHA3_384()
SHA3-512 | algorithm::SHA3 | 5 | SHA3_512()
SHAKE-128 | algorithm::SHAKE | 1 | SHAKE_128()
SHAKE-256 | algorithm::SHAKE | 2 | SHAKE_256()
```
Tokens:
Raw