Cryptographic Token Interface Standard

PKCS#11


Private key objects


Sections

RSA private key objects
DSA private key objects
ECDSA private key objects
Diffie-Hellman private key objects
KEA private key objects

Detailed Description

Private key objects (object class CKO_PRIVATE_KEY) hold private keys. This version of Cryptoki recognizes five types of private key: RSA, DSA, ECDSA, Diffie-Hellman, and KEA. The following table defines the attributes common to all private keys, in addition to the common attributes listed in Table 14 , Table 18 and Table 24 :

Table 32, Common Private Key Attributes
Attribute Data type Meaning
CKA_SUBJECT8 Byte array DER-encoding of certificate subject name (default empty)
CKA_SENSITIVE8 (see below) CK_BBOOL TRUE if key is sensitive9
CKA_SECONDARY_AUTH CK_BBOOL TRUE is the key requires a secondary authentication to take place before its use it allowed. (default FALSE)
CKA_AUTH_PIN_FLAGS2,4,6 CK_FLAGS Mask indicating the current state of the secondary authentication PIN. If CKA_SECONDARY_AUTH is FALSE, then this attribute is zero.
CKA_DECRYPT8 CK_BBOOL TRUE if key supports decryption9
CKA_SIGN8 CK_BBOOL TRUE if key supports signatures where the signature is an appendix to the data9
CKA_SIGN_RECOVER8 CK_BBOOL TRUE if key supports signatures where the data can be recovered from the signature9
CKA_UNWRAP8 CK_BBOOL TRUE if key supports unwrapping (i.e., can be used to unwrap other keys)9
CKA_EXTRACTABLE8 (see below) CK_BBOOL TRUE if key is extractable9
CKA_ALWAYS_SENSITIVE2,4,6 CK_BBOOL TRUE if key has always had the CKA_SENSITIVE attribute set to TRUE
CKA_NEVER_EXTRACTABLE2,4,6 CK_BBOOL TRUE if key has never had the CKA_EXTRACTABLE attribute set to TRUE

After an object is created, the CKA_SENSITIVE attribute may be changed, but only to the value TRUE. Similarly, after an object is created, the CKA_EXTRACTABLE attribute may be changed, but only to the value FALSE. Attempts to make other changes to the values of these attributes should return the error code CKR_ATTRIBUTE_READ_ONLY.

If the CKA_SENSITIVE attribute is TRUE, or if the CKA_EXTRACTABLE attribute is FALSE, then certain attributes of the private key cannot be revealed in plaintext outside the token. Which attributes these are is specified for each type of private key in the attribute table in the section describing that type of key.

If the CKA_EXTRACTABLE attribute is FALSE, then the key cannot be wrapped.

It is intended in the interests of interoperability that the subject name and key identifier for a private key will be the same as those for the corresponding certificate and public key. However, this is not enforced by Cryptoki, and it is not required that the certificate and public key also be stored on the token.

If the CKA_SECONDARY_AUTH attribute is TRUE, then the Cryptoki implementation will associate the new private key object with a PIN that is gathered using a mechanism that is transparent to the Cryptoki client. The new PIN must be presented to the token each time the key is used for a cryptographic operation. See section 6.7 for the complete usage model. If CKA_SECONDARY_AUTH is TRUE, then CKA_EXTRACTABLE must be FALSE and CKA_PRIVATE must be TRUE. Attempts to copy private keys with CKA_SECONDARY_AUTH set to TRUE in a manner that would violate the above conditions must fail. An application can determine whether the setting the CKA_SECONDARY_AUTH attribute to TRUE is supported by checking to see if the CKF_SECONDARY_AUTHENTICATION flag is set in the CK_TOKEN_INFO flags.

The CKA_AUTH_PIN_FLAGS attribute indicates the current state of the secondary authentication PIN. This value is only valid if the CKA_SECONDARY_AUTH attribute is TRUE. The valid flags for this attribute are CKF_USER_PIN_COUNT_LOW, CKF_USER_PIN_FINAL_TRY, CKF_USER_PIN_LOCKED, and CKF_USER_PIN_TO_BE_CHANGED defined in Table 10 for the CK_TOKEN_INFO flags field. CKF_USER_PIN_COUNT_LOW and CKF_USER_PIN_FINAL_TRY may always be set to FALSE if the token does not support the functionality or will not reveal the information because of its security policy. The CKF_USER_PIN_TO_BE_CHANGED flag may always be FALSE if the token does not support the functionality.

To map between ISO/IEC 9594-8 (X.509) keyUsage flags for public keys and the PKCS #11 attributes for public keys, use the following table.

Table 33, Mapping of X.509 key usage flags to cryptoki attributes for private keys
'''Key usage flags for public keys in X.509 public key certificates''' Corresponding cryptoki attributes for private keys.
dataEncipherment CKA_DECRYPT
digitalSignature, keyCertSign, cRLSign CKA_SIGN
digitalSignature, keyCertSign, cRLSign CKA_SIGN_RECOVER
keyAgreement CKA_DERIVE
keyEncipherment CKA_UNWRAP
nonRepudiation CKA_SIGN
nonRepudiation CKA_SIGN_RECOVER


RSA Security Inc. Public-Key Cryptography Standards - PKCS#11 - v210