Wrapping/unwrapping private keys

Cryptoki Versions 2.01 and up allow the use of secret keys for wrapping and unwrapping RSA private keys, Diffie-Hellman private keys, X9.42 Diffie-Hellman private keys, EC (also related to ECDSA) 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 private key. The object identifiers for the required algorithm identifiers are as follows:

rsaEncryption OBJECT IDENTIFIER ::= { pkcs-1 1 }
dhKeyAgreement OBJECT IDENTIFIER ::= { pkcs-3 1 }
dhpublicnumber OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) ansi-x942(10046) number-type(2) 1 }
id-ecPublicKey OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) ansi-x9-62(10045) publicKeyType(2) 1 }
id-dsa OBJECT IDENTIFIER ::= {
iso(1) member-body(2) us(840) x9-57(10040) x9cm(4) 1 }

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 {
primeINTEGER, -- p
baseINTEGER, -- g
privateValueLengthINTEGER OPTIONAL
}
DomainParameters ::= SEQUENCE {
primeINTEGER, -- p
baseINTEGER, -- g
subprimeINTEGER, -- q
cofactorINTEGER OPTIONAL, -- j
validationParmsValidationParms OPTIONAL
}
ValidationParms ::= SEQUENCE {
SeedBIT STRING, -- seed
PGenCounterINTEGER -- parameter verification
}
Parameters ::= CHOICE {
ecParametersECParameters,
namedCurveCURVES.&id({CurveNames}),
implicitlyCANULL
}
Dss-Parms ::= SEQUENCE {
p INTEGER,
q INTEGER,
g INTEGER
}

For the X9.42 Diffie-Hellman domain parameters, the cofactor and the validationParms optional fields should not be used when wrapping or unwrapping X9.42 Diffie-Hellman private keys since their values are not stored within the token.

For the EC domain parameters, the use of namedCurve is recommended over the choice ecParameters. The choice implicitlyCA must not be used in Cryptoki.

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

ECPrivateKey ::= SEQUENCE {
VersionINTEGER { ecPrivkeyVer1(1) } (ecPrivkeyVer1),
privateKeyOCTET STRING,
parameters[0] Parameters OPTIONAL,
publicKey[1] BIT STRING OPTIONAL
}

Since the EC domain parameters are placed in the PKCS #8's privateKeyAlgorithm field, the optional parameters field in an ECPrivateKey must be omitted. A Cryptoki application must be able to unwrap an ECPrivateKey that contains the optional publicKey field; however, what is done with this publicKey field is outside the scope of Cryptoki.

* 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) }

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 domain parameters appear identical when instances of them are encoded, the two corresponding object identifiers are different.