PKCS#11
|
| Cryptographic Token Interface Standard |
PKCS#11 |
Sections | |
| RSA private key objects | |
| DSA private key objects | |
| ECDSA private key objects | |
| Diffie-Hellman private key objects | |
| KEA private key objects | |
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 |