Common PKCS #11 Implementation Problems

Newsgroup: mozilla.dev.tech.crypto
Technical contact: Bob Relyea
Yell at the manager: Bob Lord

General pointers for getting PKCS #11 drivers working with Netscape software can be found in Implementing PKCS #11 for the Netscape Security Library and the PKCS #11 FAQ.

Netscape requires that PKCS #11 implementations comply with version 2.01 or later of the specification.

The following problems have been encountered by PKCS #11 implementors getting their code to work with Netscape software:

  • The most common problems have involved the key usage attributes (CKA_ENCRYPT, CKA_SIGN, etc.). In general, PKCS #11 implementation vendors have treated these attributes more strictly than the Netscape library. Specific problems are:
    • When unwrapping a private key, none of the operation attributes (CKA_ENCRYPT, CKA_DECRYPT, CKA_UNWRAP, etc.) is specified, but the library later tries to use the key for these operations.
    • When a symmetric key is generated, only the CKA_ENCRYPT operation is enabled. The key may nevertheless subsequently be used for decryption.
  • The mutex locks supplied by Netscape and passed into C_Initialize are not re-entrant. That is, if CK_LOCKMUTEX is called on a mutex that is already locked by the caller, the behavior is undefined (and will probably cause a crash). This behaviour is defined in section 8.7 of the spec.
  • There is a bug in the Netscape security library whereby the CKA_KEY_TYPE attribute is not always specified when unwrapping or generating a key.
  • The Netscape library attempts to set the CKA_LABEL and CKA_SUBJECT attributes on private keys after they have been generated, even though the spec does not require that these attributes be modifiable.
  • The function list returned by C_GetFunctionList must not contain any NULL entries. If a function is not supported, a stub function must be supplied which returns CKR_FUNCTION_NOT_SUPPORTED. This behavior is dictated by the 2.01 spec.
  • In order to support key wrapping and unwrapping, the token must support padded mechanisms, such as CKM_DES3_CBC_PAD.
  • If a token is running in FIPS-compliant mode, it may fail some tests that try to copy a key to the token using C_CreateObject.
  • PKCS #11 section 7.1 specifies that structs are to be packed to occupy as little space as possible, meaning they should be packed with 1-byte alignment. If the module implementation is compiled with some other alignment (such as 4-byte), it will not correctly interpret structures passed from Netscape software. If the module implementation accesses memory beyond the proper bounds of the struct, memory faults or other unpredictable behavior will result.