CSSM_UnwrapKey

Purpose

This function unwraps the data using the context. When working with U.S. exportable versions of the OCSF, the caller may be required to possess specific exemptions or privileges in order to allow this call to complete successfully.

Format

CSSM_RETURN CSSMAPI CSSM_UnwrapKey
              (CSSM_CC_HANDLE CCHandle,
              const CSSM_CRYPTO_DATA_PTR NewPassPhrase,
              const CSSM_WRAP_KEY_PTR WrappedKey,
              uint32 KeyAttr,
              const CSSM_DATA_PTR KeyLabel,
              CSSM_KEY_PTR UnwrappedKey)

Parameters

Input

CCHandle: The handle that describes the context of this cryptographic operation.
NewPassPhrase: The passphrase or a callback function to be used to obtain the passphrase. If the unwrapped key is a private key and the persistent object mode is true, then the private key is unwrapped and securely stored by the CSP. The NewPassPhrase is used to secure the private key after it is unwrapped. It is assumed that a known public key is associated with the private key.
WrappedKey: A pointer to the wrapped key. The wrapped key may be a symmetric key or the private key of a public/private key pair. The unwrapping method is specified as meta-data within the wrapped key and is not specified outside of the wrapped key.
KeyAttr: Attribute the unwrapped key will assume.

Output

UnwrappedKey: A pointer to a CSSM_KEY structure that returns the unwrapped key.

Input/optional

KeyLabel: Pointer to a byte string that will be used as the label for the unwrapped key.

Return Value

CSSM_OK if the function was successful. CSSM_FAIL if an error occurred. Use CSSM_GetError to determine the exact error.

Notes

The KeyData field of the CSSM_KEY structure is not required to be allocated. In this case, the memory required to represent the key is allocated by the CSP. The application is required to free this memory. The CSP will only allocate memory if the Data field of KeyData is NULL and the Length field is zero.

Related Information

CSSM_WrapKey
CSSM_RequestCssmExemption