Public Key Objects

Public key objects (object class CKO_PUBLIC_KEY) hold public keys. This version of Cryptoki recognizes four types of public keys: RSA, DSA, Diffie-Hellman and Elliptic Curve. The following table defines the attributes common to all public 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 Public Key Attributes
Attribute	Data Type	Meaning
`CKA_SUBJECT`⁸	Byte array	DER-encoding of the key subject name (default empty)
`CKA_SUBJECT_STR`¹⁰	Byte array	Printable version of CKA_SUBJECT
`CKA_ENCRYPT`⁸	`CK_BBOOL`	TRUE if key supports encryption 9
`CKA_VERIFY`⁸	`CK_BBOOL`	TRUE if key supports verification where the signature is an appendix to the data 9
`CKA_VERIFY_RECOVER`⁸	`CK_BBOOL`	TRUE if key supports verification where the data is recovered from the signature 9
`CKA_WRAP`⁸	`CK_BBOOL`	TRUE if key supports wrapping (that is, can be used to wrap other keys)9
`CKA_EXPORT`¹⁰	`CK_BBOOL`	TRUE if the key may be used to export Exportable keys.

Table 2: Common footnotes for key attribute tables

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

To map between ISO/IEC 9594-8 (X.509) key usage flags for public keys and the PKCS #11 attributes for public keys, use the following table. ProtectToolkit-C does not enforce these usage flags. When a certificate object is created, it may have any of the standard Cryptoki usage attributes, which is enforced.

Table 2: Mapping of X.509 key usage flags to Cryptoki attributes for public keys
Key Usage Flags for Public Keys in X.509 Public Key Certificates	Corresponding Cryptoki Attributes for Public Keys
dataEncipherment	`CKA_ENCRYPT`
digitalSignature, keyCertSign, cRLSign	`CKA_VERIFY`
digitalSignature, keyCertSign, cRLSign	`CKA_VERIFY_RECOVER`
keyAgreement	`CKA_DERIVE`
keyEncipherment	`CKA_WRAP`
nonRepudiation	`CKA_VERIFY`
nonRepudiation	`CKA_VERIFY_RECOVER`

RSA Public Key Objects

RSA public key objects (object class CKO_PUBLIC_KEY, key type CKK_RSA) hold RSA public keys. The following table defines the RSA public 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 Public Key Attributes:

Table 3: RSA Public Key Object Attributes
Attribute	Data Type	Meaning
`CKA_MODULUS`^1,4,6	Big integer	Modulus n
`CKA_MODULUS_BITS`^2,3,6	`CK_ULONG`	Length in bits of modulus n
`CKA_PUBLIC_EXPONENT`^1,3,6	Big integer	Public exponent e

Table 2: Common footnotes for key attribute tables

Depending on the token, there may be limits on the length of key components. See PKCS #1 for more information on RSA keys.

DSA Public Key Objects

DSA public key objects (object class CKO_PUBLIC_KEY, key type CKK_DSA) hold DSA public keys. The following table defines the DSA public key object attributes, in addition to the common attributes listed in Common Attributes, Storage Objects, Key Objects, and Common Public Key Attributes:

Table 4: DSA Public Key Attributes
Attribute	Data Type	Meaning
`CKA_PRIME`^1,3,6	Big integer	Prime p (512 to 1024 bits, in steps of 64 bits)
`CKA_SUBPRIME`^1,3,6	Big integer	Subprime q (160 bits)
`CKA_BASE`^1,3,6	Big integer	Base g
`CKA_VALUE`^1,4,6	Big integer	Public value y

Table 2: Common footnotes for key attribute tables

The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are, collectively, the “DSA parameters”.

Diffie-Hellman Public Key Objects

Diffie-Hellman public key objects (object class CKO_PUBLIC_KEY, key type CKK_DH) hold Diffie-Hellman public keys. The following table defines the Diffie-Hellman public 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 Public Key Attributes:

Table 5: Diffie-Hellman Public Key Object Attributes
Attribute	Data Type	Meaning
`CKA_PRIME`^1,3,6	Big integer	Prime p
`CKA_BASE`^1,3,6	Big integer	Base g
`CKA_VALUE`^1,4,6	Big integer	Public value y

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.

Elliptic Curve Public Key Objects

EC (also related to ECDSA) public key objects (object class CKO_PUBLIC_KEY, key type CKK_EC or CKK_EDWARDS in PKCS#11 v2.20) hold EC public keys. The following table defines the EC public 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 Public Key Attributes:

Table 6: Elliptic Curve Public Key Object Attributes
Attribute	Data Type	Meaning
`CKA_EC_PARAMS`^1,3 (`CKA_ECDSA_PARAMS`)	Byte Array	DER-encoding of an ANSI X9.62 Parameters value
`CKA_POINT`^1,4	Byte Array	DER-encoding of an ANSI X9.62 ECPoint value Q

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 ecParameters. The choice implicitlyCA must not be used in Cryptoki.

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

BIP32 Public Key Objects

BIP32 public key objects (object class CKO_PUBLIC_KEY, key type CKK_BIP32) hold EC public keys with a set of additional attributes. The following table defines the BIP32 public 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 Public Key Attributes, and Elliptic Curve Public Key Object Attributes:

Table 7: BIP32 Public 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.