Getting Started#

The cuPQC SDK provides device-side libraries for integrating cryptographic operations directly into your CUDA kernels. This guide will help you get started with the SDK in just a few steps.

Download and Installation#

  1. Download the SDK

    Download the cuPQC SDK from the NVIDIA cuPQC SDK website:

    wget https://developer.download.nvidia.com/compute/cupqc/redist/cupqc/cupqc-sdk-<version>.tar.gz

  2. Extract the Package

    Extract the tarball to your desired location:

    tar -xzf cupqc-sdk-<version>.tar.gz -C <your_directory>

    After extraction, the SDK structure will be:

    • <your_directory>/include/cupqc/ - SDK header files (pk.hpp, hash.hpp, etc.)

    • <your_directory>/include/commondx/ - CommonDx headers (required dependency)

    • <your_directory>/lib/ - Static libraries (libcupqc-pk.a, libcupqc-hash.a)

    • <your_directory>/cmake/ - CMake configuration files

    • <your_directory>/examples/ - Example programs

  3. Verify Installation

    Check that the headers are accessible:

    ls <your_directory>/include/cupqc/
# You should see: pk.hpp, hash.hpp, database.hpp, operators.hpp, etc.

Understanding the Libraries#

The SDK provides two libraries that can be used together or independently:

cuPQC-PK (Post-Quantum Cryptography)

  • ML-KEM (key encapsulation)

  • ML-DSA (digital signatures)

  • NIST-standardized post-quantum algorithms

cuPQC-Hash (Cryptographic Hash Functions)

  • SHA-2, SHA-3, SHAKE and Poseidon2 hash functions

  • Merkle Tree API

Both libraries are device-side extensions that integrate directly into your CUDA kernels.

Basic Workflow#

1. Include the Library Headers#

In your CUDA source file:

#include <pk.hpp>  // For cuPQC-PK
#include <hash.hpp> // For cuPQC-Hash

2. Define Your Descriptors#

Use operators to describe your cryptographic operations:

// Example: ML-KEM-512 Key Generation with 128 threads
using MLKEM512Key = decltype(ML_KEM_512()
                           + Function<function::Keygen>()
                           + Block()
                           + BlockDim<128>());

// Example: SHA3-256 with thread-based execution
using SHA3_256_Thread = decltype(SHA3_256() + Thread());

3. Write Your CUDA Kernel#

Call library functions directly in your kernel:

__global__ void my_crypto_kernel(/* parameters */) {
    MLKEM512Key().execute(/* arguments */);
    // Fuse with other GPU operations
}

4. Compile Your Application#

The cuPQC SDK uses Link-Time Optimization (LTO). Compile with these flags:

Using nvcc directly:

nvcc -std=c++17 -dlto -arch=sm_XY \\
     -I<your_directory>/include \\
     -L<your_directory>/lib -lcupqc-<lib> \\
     your_program.cu -o your_program

Replace sm_XY with your GPU architecture (sm_70, sm_75, sm_80, sm_86, sm_89, sm_90). Replace <lib> with the library you are using (pk, hash).

5. Run and Verify#

Execute your compiled program:

./your_program

Check the example programs in <your_directory>/examples/ for complete working code.

Using cuPQC with CMake#

The cuPQC SDK provides configuration files that simplify integration into CMake projects. The config files are located in <your_directory>/cmake/.

Find the cupqc package:

find_package(cupqc REQUIRED)

Link with the cuPQC-PK library:

target_link_libraries(YourProgram PRIVATE cupqc-pk_static)

Link with the cuPQC-Hash library:

target_link_libraries(YourProgram PRIVATE cupqc-hash_static)

Link with both libraries:

target_link_libraries(YourProgram PRIVATE cupqc-pk_static cupqc-hash_static)

Build your project by setting the CMAKE_PREFIX_PATH to your SDK directory:

cmake -DCMAKE_PREFIX_PATH=<your_directory>/cmake ..
make

Next Steps#

Detailed Implementation Guides:

API Reference: