Wrapping/unwrapping private keys (RSA, Diffie-Hellman, and DSA)

Cryptoki Versions 2.01 and up allow 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 required algorithm identifiers are as follows:

rsaEncryption OBJECT IDENTIFIER ::= { pkcs-1 1 }
dhKeyAgreement OBJECT IDENTIFIER ::= { pkcs-3 1 }
id-dsa OBJECT IDENTIFIER ::= {
iso(1) member-body(2) us(840) x9-57(10040) x9cm(4) 1 }

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 parameters for the algorithm identifiers have the following types, respectively:

NULL
DHParameter ::= SEQUENCE {
prime INTEGER, -- p
base INTEGER, -- g
privateValueLength INTEGER OPTIONAL
}
Dss-Parms ::= SEQUENCE {
p INTEGER,
q INTEGER,
g INTEGER
}

Within the PrivateKeyInfo type:

RSA private keys are BER-encoded according to PKCS #1's RSAPrivateKey ASN.1 type. This type requires values to be present for all the attributes specific to Cryptoki's RSA private key objects. In other words, if a Cryptoki library does not have values for an RSA private key's CKA_MODULUS, CKA_PUBLIC_EXPONENT, CKA_PRIVATE_EXPONENT, CKA_PRIME_1, CKA_PRIME_2, CKA_EXPONENT_1, CKA_EXPONENT2, and CKA_COEFFICIENT values, it cannot create an RSAPrivateKey BER-encoding of the key, and so it cannot prepare it for wrapping.

* Diffie-Hellman private keys are represented as BER-encoded ASN.1 type INTEGER.
* DSA private keys are represented as BER-encoded ASN.1 type INTEGER.

Once a private key has been BER-encoded as a PrivateKeyInfo type, the resulting string of bytes is 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.

Earlier drafts of PKCS #11 Version 2.0 and Version 2.01 used the object identifier

DSA OBJECT IDENTIFIER ::= { algorithm 12 }
algorithm OBJECT IDENTIFIER ::= {
iso(1) identifier-organization(3) oiw(14) secsig(3) algorithm(2) }

with associated parameters

DSAParameters ::= SEQUENCE {
prime1 INTEGER, -- modulus p
prime2 INTEGER, -- modulus q
base INTEGER -- base g
}

for wrapping DSA private keys. Note that although the two structures for holding DSA parameters appear identical when instances of them are encoded, the two corresponding object identifiers are different.

RSA Security Inc. Public-Key Cryptography Standards - PKCS#11 - v210