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 Common Object Attributes, Common Storage Object Attributes, and Common Key Attributes:

Table 1: Common Public Key Attributes

Attribute

Data Type

Meaning

CKA_SUBJECT8

Byte array

DER-encoding of the key subject name (default empty)

CKA_SUBJECT_STR10

Byte array

Printable version of CKA_SUBJECT

CKA_ENCRYPT8

CK_BBOOL

TRUE if key supports encryption 9

CKA_VERIFY8

CK_BBOOL

TRUE if key supports verification where the signature is an appendix to the data 9

CKA_VERIFY_RECOVER8

CK_BBOOL

TRUE if key supports verification where the data is recovered from the signature 9

CKA_WRAP8

CK_BBOOL

TRUE if key supports wrapping (that is, can be used to wrap other keys)9

CKA_EXPORT10

CK_BBOOL

TRUE if the key may be used to export Exportable keys.

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. SafeNet 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 Common Object Attributes, Common Storage Object Attributes, Common Key Attributes, and Common Public Key Attributes:

Table 3: RSA Public Key Object Attributes

Attribute

Data Type

Meaning

CKA_MODULUS1,4,6

Big integer

Modulus n

CKA_MODULUS_BITS2,3,6

CK_ULONG

Length in bits of modulus n

CKA_PUBLIC_EXPONENT1,3,6

Big integer

Public exponent e

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_PRIME1,3,6

Big integer

Prime p (512 to 1024 bits, in steps of 64 bits)

CKA_SUBPRIME1,3,6

Big integer

Subprime q (160 bits)

CKA_BASE1,3,6

Big integer

Base g

CKA_VALUE1,4,6

Big integer

Public value y

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 Common Object Attributes, Common Storage Object Attributes, Common Key Attributes, and Common Public Key Attributes:

Table 5: Diffie-Hellman Public Key Object Attributes

Attribute

Data Type

Meaning

CKA_PRIME1,3,6

Big integer

Prime p

CKA_BASE1,3,6

Big integer

Base g

CKA_VALUE1,4,6

Big integer

Public value y

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_ECDSA 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 Common Object Attributes, Common Storage Object Attributes, Common Key Attributes, and Common Public Key Attributes:

Table 6: Elliptic Curve Public Key Object Attributes

Attribute

Data Type

Meaning

CKA_EC_PARAMS1,3

(CKA_ECDSA_PARAMS)

Byte Array

DER-encoding of an ANSI X9.62 Parameters value

CKA_POINT1,4

Byte Array

DER-encoding of an ANSI X9.62 ECPoint value Q

Common footnotes for key attribute tables

The CKA_EC_PARAMS or 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 SafeNet 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 Common Object Attributes, Common Storage Object Attributes, 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.

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.