PKCS#11 library that implements cryptographic algorithms using wolfSSL.

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

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.

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

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.

To have ML-DSA support in wolfPKCS11, configure wolfSSL with ML-DSA support enabled, either by adding --enable-mldsa to ./configure or by setting WOLFSSL_MLDSA to yes in CMake. wolfPKCS11 uses the canonical wc_MlDsaKey API and WC_MLDSA_* sizing macros (FIPS 204 spelling) and therefore requires a wolfSSL build that incorporate these.

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.

To have ML-KEM support in wolfPKCS11, configure wolfSSL with ML-KEM (FIPS 203) support enabled, either by adding --enable-mlkem to ./configure or by setting WOLFPKCS11_MLKEM to yes in CMake.

As ML-KEM 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-mlkem during the configure step.

Use WOLFPKCS11_TPM_STORE storing objects in TPM NV.

Disables storage of tokens.

Enables debugging printf's for store.

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

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

Restores the pre-fix behavior where C_GetAttributeValue(CKA_COPYABLE) always reports CK_FALSE, regardless of whether the attribute was explicitly set. The default (without this flag) reports CK_TRUE for new objects and reflects the stored value for objects whose CKA_COPYABLE was explicitly set, matching the PKCS#11 specification. Define this only if your application or stored tokens depend on the old read-back behavior. The C_CopyObject enforcement consults the stored copyable flag directly via WP11_Object_IsCopyable, so this macro does not change which objects can be copied; objects created with CKA_COPYABLE=CK_TRUE (the default) remain copyable, and objects created with CKA_COPYABLE=CK_FALSE are still rejected by C_CopyObject with CKR_ACTION_PROHIBITED.

Several pre-existing gaps were closed; applications upgrading from earlier versions may need to update templates or error-handling:

• C_DeriveKey now enforces CKA_DERIVE on the base key. Keys that do not set CKA_DERIVE=CK_TRUE at creation are rejected with CKR_KEY_TYPE_INCONSISTENT. RSA, EC, and ML-DSA private keys default CKA_DERIVE to CK_FALSE, so applications doing ECDH or other key derivation must now set CKA_DERIVE=CK_TRUE explicitly in the key template. The check is skipped on --enable-nss builds because NSS generates ephemeral ECDHE keys without setting CKA_DERIVE and relies on the historic permissive behavior; non-NSS builds get the spec-compliant enforcement.
• C_CopyObject enforces CKA_COPYABLE (returns CKR_ACTION_PROHIBITED on CK_FALSE).
• C_DestroyObject enforces CKA_DESTROYABLE (returns CKR_ACTION_PROHIBITED on CK_FALSE).
• C_EncapsulateKey/C_DecapsulateKey enforce CKA_ENCAPSULATE / CKA_DECAPSULATE and return CKR_KEY_FUNCTION_NOT_PERMITTED when the flag is CK_FALSE.
• C_SetAttributeValue rejects flipping CKA_COPYABLE or CKA_DESTROYABLE from CK_FALSE back to CK_TRUE, returning CKR_ATTRIBUTE_READ_ONLY per spec section 4.4.1.
• C_Login(CKU_SO, ...) against a token whose SO PIN has not been set now returns CKR_USER_PIN_NOT_INITIALIZED regardless of the PIN length, closing an empty-PIN bypass where the zero-length constant compare against the unset stored PIN returned equal. NSS builds (--enable-nss) keep the empty-PIN probe accepted on uninitialized tokens because PK11_InitPin bootstraps an empty-password NSS database that way; non-empty PINs are still rejected.
• On --enable-nss builds WP11_MIN_PIN_LEN defaults to 0, permitting a zero-length user PIN. An empty user PIN intentionally disables PIN-based authentication: C_GetTokenInfo clears CKF_LOGIN_REQUIRED and all private/token objects are decoded and accessible at token load without C_Login. This is required for NSS tools (certutil, PK11_InitPin) that bootstrap empty-password databases. Integrators who require an enforced minimum can opt in at build time with C_EXTRA_FLAGS="-DWP11_MIN_PIN_LEN=N" (N>0); non-NSS builds already default to 4.

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.

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

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.

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 ..

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).

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.

Set to any value to stop storage of token data.

Summary

This release adds post-quantum cryptography support (ML-DSA and ML-KEM), CMake build support, and Doxygen API documentation. It also closes a large number of PKCS#11 specification compliance gaps and bugs found through static and negative analysis, hardens memory safety in response to external security reports, and improves CI and interoperability testing.

Compatibility with 2.0 behavior

Several PKCS#11 attribute defaults were corrected to match the specification. These changes can affect applications and stored tokens created with 2.0. The following build defines restore the pre-2.1 (2.0) behavior if needed:

• WOLFPKCS11_LEGACY_COPYABLE_FALSE_DEFAULT - restore the old behavior where an unset CKA_COPYABLE reads back as CK_FALSE (the PKCS#11 default is CK_TRUE).
• WOLFPKCS11_LEGACY_PRIVATE_FALSE_DEFAULT - restore the old behavior where an unset CKA_PRIVATE reads back as CK_FALSE for CKO_PRIVATE_KEY / CKO_SECRET_KEY (the PKCS#11 default is CK_TRUE). Also disables the matching login-state check on object creation.
• WOLFPKCS11_LEGACY_WRAP_TRUE_DEFAULT - restore the old behavior where an unset CKA_WRAP / CKA_UNWRAP defaults to CK_TRUE (the PKCS#11 default is CK_FALSE).

See the "Behavior changes for PKCS#11 spec compliance" section above for the related C_DeriveKey, C_CopyObject, C_DestroyObject, encapsulation and C_Login enforcement changes.

Detail

• Added ML-DSA (Dilithium) support, including CKA_SEED private key import. (PR #161)
• Added ML-KEM support. (PR #175)
• Added preparation work for post-quantum cryptography support. (PR #157)
• Renamed ML-DSA mechanisms/identifiers to the final naming. (PR #188)
• Added CMake build support. (PR #156)
• Added PKCS#11 Doxygen API documentation. (PR #144)
• Added support for CKR_OPERATION_ACTIVE. (PR #176)
• Use the DHUK to wrap/unwrap the seed value used for the token. (PR #159)
• Added file storage safety to wolfPKCS11. (PR #150)
• Fixed empty PIN handling for FIPS. (PR #143)
• Fixed loading a token with an empty PIN. (PR #158)
• Fixed SHA-512 truncated forms (SHA-512/224 and SHA-512/256). (PR #147)
• Fixed C_WrapKey not checking CKA_EXTRACTABLE on the key being wrapped. (PR #165)
• Fixed falseVal initialized to CK_TRUE instead of CK_FALSE. (PR #162)
• Fixed a read-only lock not being released on an early return. (PR #163)
• Added a missing NULL check. (PR #166)
• Fixed a typo in an #ifndef macro. (PR #167)
• Fixed a typo in configure.ac. (PR #164)
• Fixed resource leaks and ensured secure buffer erasing. (PR #172)
• Fixed numerous PKCS#11 compliance and static analysis findings from Fenrir. (PR #168, PR #169, PR #171, PR #173, PR #178, PR #185, PR #186, PR #187, PR #189, PR #194, PR #196, PR #197, PR #198)
• Hardened memory safety across several operations in response to external security reports: bounded the RSA verify-recover output length and validated the mechanism and key type before use, bounded secret-key length handling and the HKDF derive output length, guarded against length underflow when decoding stored symmetric keys, clamped key zeroization, and dropped the active object reference on C_DestroyObject so completing an operation can no longer read freed memory. (PR #201)
• Added negative testing and validation for wolfPKCS11. (PR #179)
• Added Fenrir findings fixes and test additions. (PR #177)
• Added a multi-call HMAC regression test. (PR #181)
• Added a C_VerifyRecover test and fixed test attributes. (PR #184)
• Fixed ML-KEM templates in tests. (PR #183)
• Fixed a couple of failing tests. (PR #145)
• Added an interoperability test against wolfSSL master. (PR #148)
• Added a wolfBoot integration test to intercept regressions. (PR #170)
• Reduced the wolfBoot integration test flow (unstable emulator). (PR #174)
• Removed --enable-cryptocb usage. (PR #149)
• Fixed CI failures from upstream dependency drift. (PR #180)
• Fixed CI issues. (PR #182)
• Fixed the Firefox Dockerfile. (PR #160)
• Fixed Debian rules for the documentation. (PR #153)
• Fixed CK_ULONG length truncation in C_GenerateRandom and C_SeedRandom. (PR #199)
• Fixed the wolfSSL interoperability build by defining WOLFPKCS11_USER_SETTINGS. (PR #200)
• Updated copyright years and fixed the configure.ac start year. (PR #191)
• Shipped the CMake package configuration in the Debian -dev package. (PR #192)
• Used FIPS-compliant length user PINs across the test suite. (PR #193)
• Added per-job timeouts to all CI workflows. (PR #195)
• Added CI coverage for C++ builds. (PR #190)
• Thanks to Denis Mingulov for contributing the C_GenerateRandom / C_SeedRandom length-truncation fix (PR #199) and for reporting several of the memory-safety issues fixed in PR #201 (oversized CKA_VALUE_LEN handling, the RSA verify-recover output-length type-punning, and the use-after-free of an active object on C_DestroyObject).

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_KEY_INFO
  • CKA_URL
  • CKA_HASH_OF_SUBJECT_PUBLIC_KEY
  • CKA_HASH_OF_ISSUER_PUBLIC_KEY
  • CKA_NAME_HASH_ALGORITHM
  • CKA_CHECK_VALUE
  • CKA_CERT_SHA1_HASH (NSS builds only)
  • CKA_CERT_MD5_HASH (NSS builds only)
  • CKA_TRUST_SERVER_AUTH (NSS builds only)
  • CKA_TRUST_CLIENT_AUTH (NSS builds only)
  • CKA_TRUST_EMAIL_PROTECTION (NSS builds only)
  • CKA_TRUST_CODE_SIGNING (NSS builds only)
  • CKA_TRUST_STEP_UP_APPROVED (NSS builds only)
  • CKA_NSS_EMAIL (NSS builds only)
  • CKA_NSS_DB (NSS builds only, not stored)
• Added SHA3 support for digest and HMAC
• Added AES key gen and key wrap
• Added --enable-nss for NSS specific PKCS11 quirks
• Fixed ECC derive key curve error
• Fixed object boolean attributes and permissions
• Fixed C_SetAttributeValue sometimes erasing keys
• Fixed wolfCrypt FIPSv5 and FIPSv6 support
• Fixed token erasure on load error
• Fixed various memory leaks
• Complete re-write of file based token path handling
• Added debugging output
• Fixed visibility issues
• Fixed x963 usage for ECC keys
• Added support for older wolfSSL versions
• Fixed token overwriting previous objects
• Fixed token load error handling
• Improved error handling for C_Login
• Improved Debian packaging
• Fixed build issues with wolfBoot
• Fixed malloc(0) code path
• Fixed C_CopyObject not doing a deep copy
• Added CKM_RSA_PKCS to wrap / unwrap
• Fixed ECC curve lookup for FIPSv5
• Fixed default attributes for keys
• C_DestroyObject now deletes files instead of leaving truncated files
• Added support for STM32U5 DHUK wrapping
• Added PBKDF2 support for pins
  • Enabled by default for FIPS
  • Enabled using --enable-pbkdf2 or defining WOLFPKCS11_PBKDF2
• Added --pbkdf2-iterations and PBKDF2_ITERATIONS to set the number of PBKDF2 iterations for pin handling (default 600,000).

Summary

Added Visual Studio support for wolfPKCS11. Fixes for cast warnings and portability.

Detail

• Fixed C_GetAttributeValue incorrectly erroring with CKR_ATTRIBUTE_VALUE_INVALID when data == NULL. The C_GetAttributeValue should set length if data field is NULL. (PR #27)
• Fixed several cast warnings and possible use of uninitialized. (PR #28)
• Fixed portability issues with WOLFPKCS11_USER_SETTINGS. (PR #28)
• Added Visual Studio support for wolfPKCS11. (PR #28)
  • This includes wolfTPM support with Windows TBS interface
• Reworked shared library versioning. (PR #29)

Summary

Adds backend support for TPM 2.0 using wolfTPM. Adds AES CBC key wrap / unwrap support. Portability improvements. Improved testing with GitHub Actions.

Detail

• Cleanups for minor cast warning, spelling and ignore for generated test files (PR #14)
• Added support for wrap/unwrap RSA with aes_cbc_pad. (PR #15)
• Fixed setting of label for public key after creation (init ECC objects before decoding) (PR #16)
• Flush writes in key store. (PR #17)
• Added build options for embedded use (PR #18)
  • WOLFSSL_USER_SETTINGS to avoid including wolfssl/options.h
  • WOLFPKCS11_USER_SETTINGS to avoid including wolfPKCS11/options.h
  • WOLFPKCS11_NO_TIME to make wc_GetTime() optional (it disables brute-force protections on token login)
• Reset failed login counter only with WOLFPKCS11_NO_TIME (PR #18)
• Fixed argument passing in SetMPI/GetMPIData (PR #19)
• Fixed NO_DH ifdef gate when freeing PKCS11 object (PR #20)
• Added GitHub CI action (PR #21)
• Fixed warnings from ./autogen.sh. Updated m4 macros. (PR #21)
• Added additional GitHub CI action tests. (PR #22)
• Added wolfPKCS11 support for using TPM 2.0 module as backend. Uses wolfTPM and supports RSA and ECC. Requires wolfSSL/wolfTPM#311 (PR #23)
• Added CI testing for wolfPKCS11 with wolfTPM backend and single threaded. (PR #23)
• Added PKCS11 TPM NV store (enabled with WOLFPKCS11_TPM_STORE). Allow WOLFPKCS11_NO_STORE for TPM use case. (PR #23)
• Fixed compiler warnings from mingw. (PR #23)
• Added portability macro WOLFPKCS11_NO_ENV when setenv/getenv are not available. (PR #23)
• Fix to only require -ldl for non-static builds. (PR #23)
• Portability fixes. Added NO_MAIN_DRIVER. Support for SINGLE_THREADED. Add static to some globals. (PR #24)
• Fixes for portability where XREALLOC is not available. (PR #25)
• Added support for custom setenv/get env using WOLFPKCS11_USER_ENV. (PR #25)
• Fix for final not being called after init in edge case pin failure. (PR #25)
• Added support for hashing PIN with SHA2-256.
  • PKS11 uses scrypt, which uses multiple MB of memory and is not practical for embedded systems. (PR #25)

• Added support for CKM_AES_CBC_PAD
• Added support for storage of token data.
• Added support encrypted private keys.
• Added CKF_LOGIN_REQUIRED to the slot flags.
• Added RSA X_509 support for signing/verifying
• Added missing CK_INVALID_SESSION.
• Added some missing PKCS11 types.
• Fixed building with FIPS 140-2 (fipsv2).
• Fixed WP11_API visibility.
• Fixed test pin to be at least 14-characters as required by FIPS HMAC.
• Fixed getting a boolean for the operations flags.
• Fixed misleading indentation fixes.
• Improve the curve_oid lookup with FIPS.
• Removed config.h from the public pkcs11.h header.
• Convert repository to GPLv3.

• Initial PKCS11 support