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 ProtectToolkit-C Mechanisms
