CKM_PKCS12_PBE_IMPORT

Supported Operations

Encrypt and Decrypt	No
Sign and Verify	No
SignRecover and VerifyRecover	No
Digest	No
Generate Key/Key-Pair	No
Wrap and Unwrap	Unwrap only
Derive	No
Available in FIPS Mode	No

Key Size Range and Parameters

Minimum	0
Maximum	None
Parameter	CK_PBE_PARAMS

Description

The PKCS#12 import mechanism, denoted CKM_PKCS12_PBE_IMPORT is a mechanism for unwrapping a private key and certificate(s). This mechanism shall return the user a handle to a private key and handle(s) to certificate(s). Note that multiple certificate handles could be returned depending on the contents of the PKCS#12 file.

NOTE   This mechanism does not import optional PKCS#12 bag attributes and PKCS#8 private-key attributes. These components are discarded during import.

The mechanism has a parameter, a CK_PKCS12_PBE_IMPORT_PARAMS structure.  This mechanism does not require an unwrapping key and supports RSA, DH, DSA and EC Private Keys and certificates. 

CK_PKCS12_PBE_IMPORT_PARAMS is a structure that provides parameters to the CKM_PKCS12_PBE_IMPORT mechanism. This structure is defined as follows:

typedef struct CK_PKCS12_PBE_IMPORT_PARAMS
{ 
/** AuthenticatedSafe password */
CK_CHAR_PTR passwordAuthSafe; 
/** Size of AuthenticatedSafe password */
CK_SIZE passwordAuthSafeLen; 
/** HMAC password */
CK_CHAR_PTR passwordHMAC; 
/** Size of HMAC password */
CK_SIZE passwordHMACLen; 
/** Certificate attributes */
CK_ATTRIBUTE_PTR certAttr; 
/** Number of certificate attributes */
CK_COUNT certAttrCount; 
/** Handle to returned certificate(s) */
CK_OBJECT_HANDLE_PTR hCert; 
/** Number of returned certificate handle(s) */
CK_COUNT_PTR hCertCount; 
}CK_PKCS12_PBE_IMPORT_PARAMS;

The fields of the structure have the following meanings:

passwordAuthSafe	This is the password to the authenticated safe container.
passwordAuthSafeLen	This is the length of password.
passwordHMAC	This is the password to HMAC.
certAttr	These are the attributes assigned to certificate.
certAttrCount	This is the number of entries in certAttr.
hCert	This is the returned certificate handle(s).
hCertCount	This is the number of handles allocated for hCert or the number of certificates found in PKCS#12 file. See below.

Length Prediction

The PKCS#12 file may contain more than one certificate, as such, the user would need to allocate sufficient buffer to hold the returned handles. The user needs to specify NULL as a parameter to the returned certificate handle (hCert), the import mechanism shall then return a count (hCertCount) of the certificate found the in the PKCS#12 file. Using the value of hCertCount, the user then allocates the required buffer to hold the returned certificate handles for the next C_UnwrapKey function call.

Returning Multiple Ceritificates

Assuming the user has allocated sufficient buffer to hold the certificate handles and there is multiple certificate in the PKCS#12 files, the import mechanism shall populate buffer hCert with the allocated certificate handles. The returned hCertCount shall match the specified value.

Reporting Remaining Certificates

In the event of the user not reserving sufficient buffer in hCert and there are more certificates to be unwrapped, the import mechanism shall unwrap up to a maximum of cerficate handles allocated by the user and return the total count of the certificates found in the PKCS#12 file. For example, if the user initially allocated one handle (hCertCount=1) and the PKCS#12 contains 2 certificates, the import mechanism shall extract the first certificate it encounters and return hCertCount=2.  In this case, the returned hCertCount shall always be larger than the specified value.

PKCS#12 Import Return Code

The following vendor specific return code may be returned in the event of errors: 

CKR_PKCS12_DECODE	This error code is returned when there is an error decoding the PKCS#12 file.
CKR_PKCS12_UNSUPPORTED_SAFEBAG_TYPE	This error code is returned when unsupported SafeBag is found. The import mechanism for this release only supports keyBag, pkcs8ShroudedKeyBag, and certBag.
CKR_PKCS12_UNSUPPORTED_PRIVACY_MODE	This error code is returned when a PKCS#12 file with unsupported privacy mode is encountered. The import mechanism for this release only supports password privacy mode.
CKR_PKCS12_UNSUPPORTED_INTEGRITY_MODE	This error code is returned when a PKCS#12 file with unsupported integrity mode is encountered. The import mechanism for this release only supports password integrity mode.

Return to SafeNet ProtectToolkit-C Mechanisms