PKCS#11
|
| Cryptographic Token Interface Standard |
PKCS#11 |
Data Fields | |
| CK_BBOOL | isSender |
| Option for generating the key (called a TEK). More... | |
| CK_ULONG | ulRandomLen |
| size of random Ra and Rb, in bytes. More... | |
| CK_BYTE_PTR | pRandomA |
| pointer to Ra data. More... | |
| CK_BYTE_PTR | pRandomB |
| pointer to Rb data. More... | |
| CK_ULONG | ulPublicDataLen |
| other party's MAYFLY public key size. More... | |
| CK_BYTE_PTR | pPublicData |
| pointer to other party's MAYFLY public key value. More... | |
| isSender | Option for generating the key (called a TEK). The value is TRUE if the sender (originator) generates the TEK, FALSE if the recipient is regenerating the TEK. |
| ulRandomLen | size of random Ra and Rb, in bytes |
| pRandomA | pointer to Ra data |
| pRandomB | pointer to Rb data |
| ulPublicDataLen | other party's MAYFLY public key size |
| pPublicData | pointer to other party's MAYFLY public key value CK_MAYFLY_DERIVE_PARAMS_PTR |
CK_MAYFLY_DERIVE_PARAMS_PTR points to a CK_MAYFLY_DERIVE_PARAMS structure. It is implementation-dependent.
MAYFLY mechanisms
MAYFLY key pair generation
The MAYFLY key pair generation mechanism, called CKM_KEA_KEY_PAIR_GEN, is a key pair generation mechanism for the MAYFLY key exchange key pair.
It does not have a parameter.
The mechanism generates MAYFLY public/private key pairs with a particular prime, subprime and base, as specified in the CKA_PRIME, CKA_SUBPRIME, and CKA_BASE attributes of the template for the public key. Note that this version of Cryptoki does not include a mechanism for generating these MAYFLY parameters.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_SUBPRIME, CKA_BASE, and CKA_VALUE attributes to the new private key. Other attributes supported by the MAYFLY public and private key types (specifically, the flags indicating which functions the keys support) may also be specified in the templates for the keys or else are assigned default initial values.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of MAYFLY prime sizes, in bits.
MAYFLY key derivation
The MAYFLY key derivation mechanism, denoted CKM_MAYFLY_DERIVE, is a mechanism for key derivation based on MAYFLY.
It has a parameter, a CK_MAYFLY_DERIVE_PARAMS structure.
This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template.
The derived key inherits the values of the CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, CKA_EXTRACTABLE, and CKA_NEVER_EXTRACTABLE attributes from the base key. The values of the CKA_SENSITIVE and CKA_EXTRACTABLE attributes may be overridden in the template for the derived key, however. Of course, if the base key has the CKA_ALWAYS_SENSITIVE attribute set to TRUE, then the template may not specify that the derived key should have the CKA_SENSITIVE attribute set to FALSE; similarly, if the base key has the CKA_NEVER_EXTRACTABLE attribute set to TRUE, then the template may not specify that the derived key should have the CKA_EXTRACTABLE attribute set to TRUE.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of MAYFLY prime sizes, in bits.
Generic secret key mechanisms
Generic secret key generation
The generic secret key generation mechanism, denoted CKM_GENERIC_SECRET_KEY_GEN, is used to generate generic secret keys. The generated keys take on any attributes provided in the template passed to the C_GenerateKey call, and the CKA_VALUE_LEN attribute specifies the length of the key to be generated.
It does not have a parameter.
The template supplied must specify a value for the CKA_VALUE_LEN attribute. If the template specifies an object type and a class, they must have the following values:
CK_OBJECT_CLASS = CKO_SECRET_KEY; CK_KEY_TYPE = CKK_GENERIC_SECRET;
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of key sizes, in bits.
Wrapping/unwrapping private keys (RSA, Diffie-Hellman, and DSA)
Cryptoki v2.0 allows the use of secret keys for wrapping and unwrapping RSA private keys, Diffie-Hellman private keys, and DSA private keys. For wrapping, a private key is BER-encoded according to PKCS #8's PrivateKeyInfo ASN.1 type. PKCS #8 requires an algorithm identifier for the type of the secret key. The object identifiers for the needed algorithm identifiers are as follows:
rsaEncryption OBJECT IDENTIFIER ::= { pkcs-1 1 }
dhKeyAgreement OBJECT IDENTIFIER ::= { pkcs-3 1}
DSA OBJECT IDENTIFIER ::= { iso(1) identifier-organization(3) oiw(14) secsig(3) algorithm(2) 12 }
where
pkcs-1 OBJECT IDENTIFIER ::= { iso(1) member-body(2) US(840) rsadsi(113549) pkcs(1) 1 }
pkcs-3 OBJECT IDENTIFIER ::= { iso(1) member-body(2) US(840) rsadsi(113549) pkcs(1) 3 }
These object identifiers have the following parameters, respectively:
NULL
DHParameter ::= SEQUENCE {
prime INTEGER, -- p
base INTEGER, -- g
privateValueLength INTEGER OPTIONAL
}
DSAParameters ::= SEQUENCE {
modulusLength INTEGER, -- length of p in bits
prime1 INTEGER, -- modulus p
prime2 INTEGER, -- modulus q
base INTEGER -- base g
}
Within the PrivateKeyInfo type:
* Diffie-Hellman private keys are encoded by expressing the private value as a sequence of bytes, most-significant byte first, and then BER-encoding that sequence of bytes as an OCTET STRING. * DSA private keys are encoded by expressing the private value as a sequence of of bytes, most-significant byte first, and then BER-encoding that sequence of bytes as an OCTET STRING.
Once a private key has been BER-encoded as a PrivateKeyInfo type, the resulting string of bytes can be encrypted with the secret key. This encryption must be done in CBC mode with PKCS padding.
Unwrapping a wrapped private key undoes the above procedure. The CBC-encrypted ciphertext is decrypted, and the PKCS padding is removed. The data thereby obtained are parsed as a PrivateKeyInfo type, and the wrapped key is produced. An error will result if the original wrapped key does not decrypt properly, or if the decrypted unpadded data does not parse properly, or its type does not match the key type specified in the template for the new key. The unwrapping mechanism contributes only those attributes specified in the PrivateKeyInfo type to the newly-unwrapped key; other attributes must be specified in the template, or will take their default values.
The RC2 cipher
RC2 is a proprietary block cipher which is trademarked by RSA Data Security. It has a variable keysize and an additional parameter, the "effective number of bits in the RC2 search space", which can take on values in the range 1-1024, inclusive.
RC2 mechanism parameters
typdef CK_ULONG CK_RC2_PARAMS;
|
|
Option for generating the key (called a TEK). The value is TRUE if the sender (originator) generates the TEK, FALSE if the recipient is regenerating the TEK. |
|
|
size of random Ra and Rb, in bytes. |
|
|
pointer to Ra data. |
|
|
pointer to Rb data. |
|
|
other party's MAYFLY public key size. |
|
|
pointer to other party's MAYFLY public key value. |