Private Key Objects

Private key objects (object class CKO_PRIVATE_KEY) hold private keys.  This version of ProtectToolkit-C recognizes four types of private key: RSA, DSA, Diffie-Hellman and Elliptic Curve.  The following table defines the attributes common to all private keys, in addition to the common attributes listed in Table 1: Common Object Attributes, Table 1: Common Storage Object Attributes, and Table 3: Common Key Attributes:

Table 1: Common Private Key Attributes
Attribute Data Type Meaning
CKA_SUBJECT8 Byte array DER-encoding of certificate subject name (default empty)
CKA_SUBJECT_STR10 Byte array Printable version of CKA_SUBJECT (default empty)
CKA_SENSITIVE8 (see below) CK_BBOOL TRUE if key is sensitive9
CKA_SECONDARY_AUTH CK_BBOOL This is not supported.
CKA_AUTH_PIN_FLAGS2,4,6 CK_FLAGS This is not supported.
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 (that is, 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
CKA_USAGE_COUNT10 CK_ULONG This optional field will hold a usage counter. The numeric value is incremented each time the key is used.
CKA_EXPORTABLE10 CK_BBOOL TRUE if key may be wrapped with a key that has the CKA_EXPORT attribute set.
CKA_IMPORT10 CK_BBOOL If TRUE and CKA_UNWRAP is FALSE supports unwrapping only using CKM_WRAPKEY_DES3_CBC.

Table 2: Common footnotes for key attribute tables

RSA Private Key Objects

RSA private key objects (object class CKO_PRIVATE_KEY, key type CKK_RSA) hold RSA private keys.  The following table defines the RSA private key object attributes, in addition to the common attributes listed in Table 1: Common Object Attributes, Table 1: Common Storage Object Attributes, Table 3: Common Key Attributes, and Common Private Key Attributes:

Table 2: RSA Private Key Object Attributes
Attribute Data Type Meaning
CKA_MODULUS1,4,6 Big integer Modulus n
CKA_PUBLIC_EXPONENT4,6 Big integer Public exponent e
CKA_PRIVATE_EXPONENT1,4,6,7 Big integer Private exponent d
CKA_PRIME_14,6,7 Big integer Prime p
CKA_PRIME_24,6,7 Big integer Prime q
CKA_EXPONENT_14,6,7 Big integer Private exponent d modulo p-1
CKA_EXPONENT_24,6,7 Big integer Private exponent d modulo q-1
CKA_COEFFICIENT4,6,7 Big integer CRT coefficient q-1 mod p

Table 2: Common footnotes for key attribute tables

RSA modulus size may range from 512 to 4096 bits. RSA private keys can include all CRT components or just the modulus and exponent. Performance is greatly enhanced by providing all CRT components so this is advised. Any RSA keys generated locally will always include all components.

NOTE   When generating an RSA private key, there is no CKA_MODULUS_BITS attribute specified. This is because RSA private keys are only generated as part of an RSA key pair, and the CKA_MODULUS_BITS attribute for the pair is specified in the template for the public key.

DSA Private Key Objects

DSA private key objects (object class CKO_PRIVATE_KEY, key type CKK_DSA) hold DSA private keys.  The following table defines the DSA private key object attributes, in addition to the common attributes listed in Table 1: Common Object Attributes, Table 1: Common Storage Object Attributes, Table 3: Common Key Attributes, and Common Private Key Attributes:

Table 3: DSA Private Key Object Attributes
Attribute Data Type Meaning
CKA_PRIME1,4,6 Big integer Prime p (512 to 1024 bits, in steps of 64 bits)
CKA_SUBPRIME1,4,6 Big integer Subprime q (160 bits)
CKA_BASE1,4,6 Big integer Base g
CKA_VALUE1,4,6,7 Big integer Private value x

Table 2: Common footnotes for key attribute tables

The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the “DSA parameters”. See FIPS PUB 186 for more information on DSA keys.

NOTE   When generating a DSA private key, the DSA parameters are not specified in the key’s template.  This is because DSA private keys are only generated as part of a DSA key pair, and the DSA parameters for the pair are specified in the template for the public key.  If they are present in the private key template they are ignored.

Diffie-Hellman Private Key Objects

Diffie-Hellman private key objects (object class CKO_PRIVATE_KEY, key type CKK_DH) hold Diffie-Hellman private keys.  The following table defines the Diffie-Hellman private key object attributes, in addition to the common attributes listed in Table 1: Common Object Attributes, Table 1: Common Storage Object Attributes, Table 3: Common Key Attributes, and Common Private Key Attributes:

Table 4: Diffie-Hellman Private Key Object Attributes
Attribute Data Type Meaning
CKA_PRIME1,4,6 Big integer Prime p
CKA_BASE1,4,6 Big integer Base g
CKA_VALUE1,4,6,7 Big integer Private value x
CKA_VALUE_BITS2,6 CK_ULONG Length in bits of private value x

Table 2: Common footnotes for key attribute tables

The CKA_PRIME and CKA_BASE attribute values are collectively the “Diffie-Hellman parameters”. Depending on the token, there may be limits on the length of the key components. See PKCS #3 for more information on Diffie-Hellman keys.

NOTE   When generating a Diffie-Hellman private key, the Diffie-Hellman parameters are not specified in the key’s template. This is because Diffie-Hellman private keys are only generated as part of a Diffie-Hellman key pair, and the Diffie-Hellman parameters for the pair are specified in the template for the public key. If they are present in the private key template, they are ignored.

Elliptic Curve Private Key Objects

EC (also related to ECDSA) private key objects (object class CKO_PRIVATE_KEY, key type CKK_EC or CKK_EDWARDS in PKCS#11 v2.20) hold EC private keys. The following table defines the EC private key object attributes, in addition to the common attributes listed in Table 1: Common Object Attributes, Table 1: Common Storage Object Attributes, Table 3: Common Key Attributes, and Common Private Key Attributes:

Table 5: Elliptic Curve Private Key Object Attributes
Attribute Data Type Meaning
CKA_EC_PARAMS1,4,6 (CKA_ECDSA_PARAMS) Byte Array DER-encoding of an ANSI X9.62 Parameters value
CKA_POINT1,4,6,7 Byte Array ANSI X9.62 private value d

Table 2: Common footnotes for key attribute tables

The CKA_EC_PARAMS (CKA_ECDSA_PARAMS) attribute value is known as the “EC domain parameters” and is defined in ANSI X9.62 as a choice of three parameter representation methods with the following syntax:

Parameters ::= CHOICE {
ecParameters ECParameters,
namedCurve CURVES.&id({CurveNames}),
implicitlyCA NULL
}

This allows detailed specification of all required values using choice ecParameters, the use of a namedCurve as an object identifier substitute for a particular set of elliptic curve domain parameters, or implicitlyCA to indicate that the domain parameters are explicitly defined elsewhere. The use of a namedCurve is recommended over the choice ecParameters. The choice implicitlyCA must not be used in Cryptoki.

Both the ecParameters and the namedCurve method are supported in ProtectToolkit-C. See CKM_EC_KEY_PAIR_GEN for details.

NOTE   When generating an EC private key, the EC domain parameters are not specified in the key’s template. This is because EC private keys are generated only as part of an EC key pair, and the EC domain parameters for the pair are specified in the template for the public key.

BIP32 Private Key Objects

BIP32 private key objects (object class CKO_PRIVATE_KEY, key type CKK_BIP32) hold EC private keys with a set of additional attributes. The following table defines the BIP32 private key attributes, in addition to the common attributes listed in Table 1: Common Object Attributes, Table 1: Common Storage Object Attributes, Table 3: Common Key Attributes, Common Private Key Attributes, and Elliptic Curve Private Key Object Attributes:

Table 6: BIP32 Private Key Object Attributes
Attribute Data Type Meaning
CKA_BIP32_CHAINCODE Byte Array 32 byte numeric value produced during key derivation. Part of the extended key. Read-only.
CKA_BIP32_VERSION_BYTES CK_ULONG 32 bit numeric value that is used by client applications to determine the network the key should be used in. By default, it is set to the main-net values.
CKA_BIP32_CHILD_INDEX CK_ULONG 32 bit numeric value that defines the child number. Values over 0x80000000 are considered hardened keys. The Master key node value is always 0. Read-only.
CKA_BIP32_CHILD_DEPTH CK_ULONG 8 bit numeric value that defines the depth of the child. The Master key node depth is always 0. Read-only.
CKA_BIP32_ID Byte Array Unique identifier for the key pair. Generated by calculating the HASH160 of the public key. Read-only.
CKA_BIP32_FINGERPRINT Byte Array The first 32 bits of the CKA_BIP32_ID. Read-only.
CKA_BIP32_PARENT_FINGERPRINT Byte Array The first 32 bits of the parent node’s CKA_BIP32_ID. For master keys the value is always 0. Read-only.

Table 2: Common footnotes for key attribute tables

The chain code and index play an important role in the key derivation mechanism, so they need to be stored alongside the key value. The other fields (version bytes, child depth, ID and fingerprints) are generated during derivation and are kept as a courtesy for the client applications, which might have a use for them.

See CKM_BIP32_MASTER_DERIVE and CKM_BIP32_CHILD_DERIVE for details on the mechanisms used to create BIP32 objects.