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_SUBJECT`⁸	Byte array	DER-encoding of certificate subject name (default empty)
`CKA_SUBJECT_STR`¹⁰	Byte array	Printable version of `CKA_SUBJECT` (default empty)
`CKA_SENSITIVE`⁸ (see below)	`CK_BBOOL`	`TRUE` if key is sensitive⁹
`CKA_SECONDARY_AUTH`	`CK_BBOOL`	This is not supported.
`CKA_AUTH_PIN_FLAGS`^2,4,6	`CK_FLAGS`	This is not supported.
`CKA_DECRYPT`⁸	`CK_BBOOL`	`TRUE` if key supports decryption⁹
`CKA_SIGN`⁸	`CK_BBOOL`	`TRUE` if key supports signatures where the signature is an appendix to the data⁹
`CKA_SIGN_RECOVER`⁸	`CK_BBOOL`	`TRUE` if key supports signatures where the data can be recovered from the signature⁹
`CKA_UNWRAP`⁸	`CK_BBOOL`	`TRUE` if key supports unwrapping (that is, can be used to unwrap other keys)⁹
`CKA_EXTRACTABLE`⁸ (see below)	`CK_BBOOL`	`TRUE` if key is extractable⁹
`CKA_ALWAYS_SENSITIVE`^2,4,6	`CK_BBOOL`	`TRUE` if key has always had the `CKA_SENSITIVE` attribute set to `TRUE`
`CKA_NEVER_EXTRACTABLE`^2,4,6	`CK_BBOOL`	`TRUE` if key has never had the `CKA_EXTRACTABLE` attribute set to `TRUE`
`CKA_USAGE_COUNT`¹⁰	`CK_ULONG`	This optional field will hold a usage counter. The numeric value is incremented each time the key is used.
`CKA_EXPORTABLE`¹⁰	`CK_BBOOL`	`TRUE` if key may be wrapped with a key that has the `CKA_EXPORT` attribute set.
`CKA_IMPORT`¹⁰	`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_MODULUS`^1,4,6	Big integer	Modulus n
`CKA_PUBLIC_EXPONENT`^4,6	Big integer	Public exponent e
`CKA_PRIVATE_EXPONENT`^1,4,6,7	Big integer	Private exponent d
`CKA_PRIME_1`^4,6,7	Big integer	Prime p
`CKA_PRIME_2`^4,6,7	Big integer	Prime q
`CKA_EXPONENT_1`^4,6,7	Big integer	Private exponent d modulo p-1
`CKA_EXPONENT_2`^4,6,7	Big integer	Private exponent d modulo q-1
`CKA_COEFFICIENT`^4,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_PRIME`^1,4,6	Big integer	Prime p (512 to 1024 bits, in steps of 64 bits)
`CKA_SUBPRIME`^1,4,6	Big integer	Subprime q (160 bits)
`CKA_BASE`^1,4,6	Big integer	Base g
`CKA_VALUE`^1,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_PRIME`^1,4,6	Big integer	Prime p
`CKA_BASE`^1,4,6	Big integer	Base g
`CKA_VALUE`^1,4,6,7	Big integer	Private value x
`CKA_VALUE_BITS`^2,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_PARAMS`^1,4,6 (`CKA_ECDSA_PARAMS`)	Byte Array	DER-encoding of an ANSI X9.62 Parameters value
`CKA_POINT`^1,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.