SkillAgentSearch skills...

WolfPKCS11

wolfSSL PKCS#11

GenerateConvertImprove

Install / Use

/learn @wolfSSL/WolfPKCS11
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

wolfPKCS11

PKCS#11 library that implements cryptographic algorithms using wolfSSL.

Project Features

Building

Build wolfSSL:

git clone https://github.com/wolfSSL/wolfssl.git
cd wolfssl
./autogen.sh
./configure --enable-aescfb --enable-rsapss --enable-keygen --enable-pwdbased --enable-scrypt C_EXTRA_FLAGS="-DWOLFSSL_PUBLIC_MP -DWC_RSA_DIRECT -DHAVE_AES_ECB -DHAVE_AES_KEYWRAP"
make
make check
sudo make install
sudo ldconfig

autogen.sh requires: automake and libtool: sudo apt-get install automake libtool

Build wolfPKCS11:

git clone https://github.com/wolfSSL/wolfPKCS11.git
cd wolfPKCS11
./autogen.sh
./configure
make
make check

TPM support with wolfTPM

Enables using a TPM for cryptography and keystore. Tested using ./configure --enable-singlethreaded --enable-wolftpm --disable-dh CFLAGS="-DWOLFPKCS11_TPM_STORE" && make.

Note: The TPM does not support DH, so only RSA and ECC are supported.

Optional: AES-CCM Support

To have AES-CCM support in wolfPKCS11, configure both wolfSSL and wolfPKCS11 with the addition of --enable-aesccm.

Optional: AES-ECB Support

To have AES-ECB support in wolfPKCS11, configure wolfSSL with the C macro HAVE_AES_ECB defined. For example, CFLAGS="-DHAVE_AES_ECB". Then enable it in wolfPKCS11 with the addition of --enable-aesecb during the configure step.

WARNING: ECB (Electronic Code Book) mode AES is generally considered to be insecure. Please consider using a different mode of AES.

Optional: PQC ML-DSA Support

To have ML-DSA support in wolfPKCS11, configure wolfSSL with ML-DSA (Dilithium) support enabled, either by adding --enable-mldsa to ./configure or by setting WOLFSSL_DILITHIUM to yes in CMake.

As ML-DSA is a feature of PKCS#11 version 3.2, support for that is required, too. Hence, to enable all in wolfPKCS11, add --enable-pkcs11v32 --enable-mldsa during the configure step.

Build options and defines

Define WOLFPKCS11_TPM_STORE

Use WOLFPKCS11_TPM_STORE storing objects in TPM NV.

Define WOLFPKCS11_NO_STORE

Disables storage of tokens.

Define WOLFPKCS11_DEBUG_STORE

Enables debugging printf's for store.

Define WOLFPKCS11_CUSTOM_STORE

Removes default implementation of storage functions. See wolfpkcs11/store.h for prototypes of functions to implement.

Define WOLFPKCS11_KEYPAIR_GEN_COMMON_LABEL

Sets the private key's label against the public key when generating key pairs.

Analog Devices, Inc. MAXQ10xx Secure Elements (MAXQ1065/MAXQ1080)

Support has been added to use the MAXQ10xx hardware for cryptographic operations and storage of certificate.

Before usage:

  1. Make sure the maxq10xx-sdk is installed and it has installed the proper header files into the source code for wolfPKCS11.
  2. Edit examples/maxq10xx_init.sh to ensure it is pointing to the correct location.
  3. Execute examples/maxq10xx_init.sh to ensure it is properly initialized.

NOTE: In the code, we have embedded a test key. This must be changed for production environments!! Please contact Analog Devices to learn how to obtain and use a production key.

Building with CMake

wolfPKCS11 uses out-of-source builds. It also requires CMake 3.16 or later (3.22+ recommended).

Building wolfSSL with CMake

wolfPKCS11 depends on wolfSSL. Build and install wolfSSL with CMake first:

git clone https://github.com/wolfSSL/wolfssl.git
cd wolfssl
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr/local \
    -DWOLFSSL_AES=yes -DWOLFSSL_AESCBC=yes -DWOLFSSL_AESCCM=yes \
    -DWOLFSSL_AESCFB=yes -DWOLFSSL_AESECB=yes -DWOLFSSL_AESCTR=yes \
    -DWOLFSSL_AESGCM=yes -DWOLFSSL_AESKEYWRAP=yes -DWOLFSSL_AESOFB=yes \
    -DWOLFSSL_AESCTS=yes -DWOLFSSL_DH=yes -DWOLFSSL_DH_DEFAULT_PARAMS=yes \
    -DWOLFSSL_ECC=yes -DWOLFSSL_HKDF=yes -DWOLFSSL_KEYGEN=yes \
    -DWOLFSSL_MD5=yes -DWOLFSSL_RSA=yes -DWOLFSSL_RSA_PSS=yes \
    -DWOLFSSL_SHA=yes -DWOLFSSL_SHA224=yes -DWOLFSSL_SHA3=yes \
    -DWOLFSSL_SHA384=yes -DWOLFSSL_SHA512=yes \
    -DWOLFSSL_SP_MATH_ALL=yes -DWOLFSSL_PUBLIC_MP=yes \
    -DWOLFSSL_WC_RSA_DIRECT=yes -DWOLFSSL_DILITHIUM=yes \
    -DCMAKE_BUILD_TYPE=Release \
    ..
cmake --build .
sudo cmake --install .

To install to a non-system directory instead, set -DCMAKE_INSTALL_PREFIX=<path> and pass the same path as -DCMAKE_PREFIX_PATH=<path> when building wolfPKCS11 below.

Building wolfPKCS11 with CMake

cd wolfPKCS11
mkdir build && cd build
cmake ..
cmake --build .
ctest

To enable additional features, pass options during the configure step:

cmake -DWOLFPKCS11_DEBUG=yes \
    -DWOLFPKCS11_AESKEYWRAP=yes \
    -DWOLFPKCS11_AESCTR=yes \
    -DWOLFPKCS11_AESCCM=yes \
    -DWOLFPKCS11_AESECB=yes \
    -DWOLFPKCS11_AESCTS=yes \
    -DWOLFPKCS11_AESCMAC=yes \
    -DWOLFPKCS11_PBKDF2=yes \
    -DWOLFPKCS11_PKCS11_V3_2=yes \
    -DWOLFPKCS11_MLDSA=yes \
    ..
cmake --build .
ctest

If wolfSSL was installed to a non-system prefix, point CMake to it:

cmake -DCMAKE_PREFIX_PATH=/path/to/wolfssl/install ..

CMake Build Options

| Option | Default | Description | |--------|---------|-------------| | WOLFPKCS11_DEBUG | no | Enable debug logging | | WOLFPKCS11_SINGLE_THREADED | no | Single-threaded mode | | WOLFPKCS11_RSA | yes | RSA support | | WOLFPKCS11_OAEP | yes | RSA OAEP support | | WOLFPKCS11_RSA_PSS | yes | RSA-PSS support | | WOLFPKCS11_KEYGEN | yes | Key generation support | | WOLFPKCS11_ECC | yes | ECC support | | WOLFPKCS11_DH | yes | DH support | | WOLFPKCS11_AES | yes | AES support | | WOLFPKCS11_AESCBC | yes | AES-CBC support | | WOLFPKCS11_AESGCM | yes | AES-GCM support | | WOLFPKCS11_AESKEYWRAP | no | AES Key Wrap support | | WOLFPKCS11_AESCTR | no | AES-CTR support | | WOLFPKCS11_AESCCM | no | AES-CCM support | | WOLFPKCS11_AESECB | no | AES-ECB support | | WOLFPKCS11_AESCTS | no | AES-CTS support | | WOLFPKCS11_AESCMAC | no | AES-CMAC support | | WOLFPKCS11_HMAC | yes | HMAC support | | WOLFPKCS11_HKDF | yes | HKDF support | | WOLFPKCS11_PBKDF2 | no | PBKDF2 for PIN hashing | | PBKDF2_ITERATIONS | 600000 | PBKDF2 iteration count (used when WOLFPKCS11_PBKDF2=yes) | | WOLFPKCS11_MD5 | yes | MD5 support | | WOLFPKCS11_SHA1 | yes | SHA-1 support | | WOLFPKCS11_SHA224 | yes | SHA-224 support | | WOLFPKCS11_SHA256 | yes | SHA-256 support | | WOLFPKCS11_SHA384 | yes | SHA-384 support | | WOLFPKCS11_SHA512 | yes | SHA-512 support | | WOLFPKCS11_SHA3 | yes | SHA-3 support | | WOLFPKCS11_TPM | no | wolfTPM keystore support | | WOLFPKCS11_NSS | no | NSS-specific modifications | | WOLFPKCS11_PKCS11_V3_0 | yes | PKCS#11 v3.0 support | | WOLFPKCS11_PKCS11_V3_2 | no | PKCS#11 v3.2 support | | WOLFPKCS11_MLDSA | no| ML-DSA support | | WOLFPKCS11_EXAMPLES | yes | Build examples | | WOLFPKCS11_TESTS | yes | Build and register tests | | WOLFPKCS11_COVERAGE | no | Code coverage support | | WOLFPKCS11_INSTALL | yes | Create install targets | | WOLFPKCS11_DEFAULT_TOKEN_PATH | "" | Default token storage path compiled into library | | WOLFPKCS11_BUILD_OUT_OF_TREE | yes | Generate build artifacts outside source tree | | BUILD_SHARED_LIBS | ON | Build shared (ON) or static (OFF) library |

Note: wolfSSL must be built with the corresponding features enabled for the options above to work (e.g. enabling WOLFPKCS11_AESCCM requires wolfSSL built with -DWOLFSSL_AESCCM=yes).

Environment variables

WOLFPKCS11_TOKEN_PATH

Path into which files are stored that contain token data. If unset, wolfPKCS11 tries, in order, the directory specified by WOLFPKCS11_TOKEN_PATH, any store directory configured by NSS, the user's home directory (~/.wolfPKCS11 on POSIX or %APPDIR%\wolfPKCS11 on Windows), and finally the optional WOLFPKCS11_DEFAULT_TOKEN_PATH build-time setting. There is no fallback to /tmp; deployments must provide a secure storage location explicitly.

WOLFPKCS11_NO_STORE

Set to any value to stop storage of token data.

Release Notes

wolfPKCS11 Release 2.0 (August 26, 2025)

Summary

This release contains many new features so that it can be the PKCS11 backend for NSS. It also includes many bug fixes.

Detail

  • New examples added
  • Added certificate storage for wolfPKCS11
  • Added new AES algorithms:
    • AES-CCM
    • AES-ECB
    • AES-CTS
    • AES-CTR
  • Compiler fixes
  • Large improvements to TPM storage
  • Reduced memory usage for objects
  • Added support for MAXQ1065
  • Fixed RSA with no public exponent provided
  • Fixed CKA_CERTIFICATE_TYPE search for CKC_X_509
  • Fixed RSA with no modulus provided
  • Fixed bad memory access with C_FindObjects on a certificate object
  • Added new functionality:
    • C_Digest*
    • C_SignEncryptUpdate
    • C_DecryptVerifyUpdate
    • C_GetOperationState and C_SetOperationState (Digest only)
    • C_SignRecoverInit and C_VerifyRecover
    • wolfPKCS11_Debugging_On and wolfPKCS11_Debugging_Off
  • Added new mechanisms:
    • CKM_ECDSA_SHA*
    • CKM_SHA*_RSA*
    • CKM_AES_CMAC_GENERAL
    • CKM_AES_CMAC
    • CKM_AES_CBC_ENCRYPT_DATA
    • CKM_HKDF_DATA
    • CKM_HKDF_KEY_GEN
    • CKM_TLS12_KEY_AND_MAC_DERIVE
    • CKM_TLS12_MASTER_KEY_DERIVE
    • CKM_TLS12_MASTER_KEY_DERIVE_DH
    • CKM_NSS_TLS_EXTENDED_MASTER_KEY_DERIVE (NSS builds only)
    • CKM_NSS_TLS_EXTENDED_MASTER_KEY_DERIVE_DH (NSS builds only)
    • CKM_NSS_TLS_PRF_GENERAL_SHA256 (NSS builds only)
    • CKM_TLS_MAC
    • CKM_SHA1_RSA_PKCS
    • CKM_SHA1_RSA_PKCS_PSS
    • CKM_SHA3*
    • CKM_MD5
    • CKM_NSS_PKCS12_PBE_SHA*_HMAC_KEY_GEN (NSS builds only)
    • CKM_PKCS5_PBKD2
  • Added new types:
    • CKO_DATA
    • CKO_NSS_TRUST (NSS builds only)
  • Added new attributes:
    • CKA_CERTIFICATE_TYPE
    • CKA_CERTIFICATE_CATEGORY
    • CKA_ID
    • CKA_ISSUER
    • CKA_SERIAL_NUMBER
    • `CKA_PUBLIC_

wolfSSL

View profile

View on GitHub
GitHub Stars18
CategoryDevelopment
Updated3d ago
Forks23
wolfSSL/wolfPKCS11

Languages

C

Security Score

75/100

Audited on Mar 26, 2026

No findings