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 (bytes) 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