NAME

CSSM_UnwrapKey

SYNOPSIS

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

DESCRIPTION

This function unwraps the wrapped key using the context. The wrapped key can be a symmetric key or a private key. If the key is a symmetric key, then a symmetric context must be provide describing the unwrapping algorithm. If the key is a private key, then an asymmetric context must be provide describing the unwrapping algorithm. Depending on the persistent object mode of the CSP and the storage mode specified by the key attribute value in the wrapped key header, the unwrapped key can be securely stored by the CSP and locked by the new passphrase. If the unwrapping algorithm is NULL and the wrapped key is actually a raw key (as indicated by its key attributes), then the key is imported into the CSP. Support for a NULL unwrapping algorithm, is at the option of the CSP. The unwrapped key is restored to its original pre-wrap state based on the key attributes recorded by the wrapped key during the wrap operation. These attributes must not be modified by the caller.

PARAMETERS

CCHandle (input)

The handle that describes the context of this cryptographic operation.

PassPhrase (input/optional)

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 PassPhrase is used to control access to the private key after it is unwrapped. If a symmetric key is being unwrapped, then this parameter is optional.

PublicKey (input/optional)

The public key corresponding to the private key being unwrapped. If a symmetric key is being unwrapped, then this parameter must be NULL.

WrappedKey (input)

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.

KeyUsage (input/optional)

A bit mask indicating all permitted uses for the imported key. If no value is specified, the CSP defines the usage mask for the imported key.

KeyAttr (input)

A bit mask defining attribute values to be associated with the unwrapped key.

KeyLabel (input/optional)

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

UnwrappedKey (output)

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

DescriptiveData (output)

A pointer to a CSSM_DATA structure that returns any additional descriptive data that was associated with the key during the wrapping operation. It is assumed that the caller incorporated knowledge of the structure of this data. If no additional data is associated with the imported key, this output value is NULL.

RETURN VALUE

A CSSM return value. This function returns CSSM_OK if successful, and returns an error code if an error has occurred.

ERRORS

CSSM_CSP_INVALID_CONTEXT_HANDLE

Invalid context handle.

CSSM_CSP_INVALID_CONTEXT

Context type and operation do not match.

CSSM_CSP_INVALID_DATA_POINTER

Invalid output CSSM_DATA pointer.

CSSM_CSP_INVALID_DATA

Invalid output CSSM_DATA buffer.

CSSM_CSP_INVALID_ALGORITHM

Unknown algorithm.

CSSM_CSP_OPERATION_UNSUPPORTED

Unwrap key service not supported.

CSSM_CSP_OPERATION_FAILED

Cryptographic operation failed.

CSSM_CSP_INVALID_KEYATTR

Specified key attribute is incorrect or unsupported.

CSSM_CSP_INVALID_KEY_POINTER

Invalid CSSM_KEY or CSSM_WRAP_KEYpointers.

CSSM_INVALID_SUBJECT_KEY

Invalid subject key (key to be unwrapped).

CSSM_CSP_INVALID_CRYPTO_DATA_POINTER

Invalid or missing passphrase (parameter required if the subject key is a private key).

CSSM_CSP_CALLBACK_FAILED

Passphrase callback function failed for subject private key or for private key in the asymmetric context.

CSSM_CSP_PRIKEY_NOT_FOUND

Cannot find the corresponding private key for either the subject private key or the private key in the asymmetric context.

CSSM_CSP_PASSPHRASE_INVALID

Passphrase length error or passphrase badly formed for either the passphrase parameter or passphrase in the asymmetric context.

CSSM_CSP_PRIKEY_ERROR

Error in getting the raw private key or private key storage error for either the subject private key or the private key in the asymmetric context.

CSSM_CSP_INVALID_KEY

Invalid or missing key data in the context attribute.

CSSM_CSP_INVALID_KEYCLASS

Key class is not private or public key class for asymmetric context or is not session key class for symmetric context.

CSSM_CSP_KEY_ALGID_MISMATCH

The key in the context (key to be used for unwrapping) does not match the operation.

CSSM_CSP_KEY_KEYHEADER_INCONSISTENT

Key header and key data (for the unwrapping key) is inconsistent.

CSSM_CSP_KEY_USAGE_INCORRECT

Key usage mask (for the unwrapping key) does not allow unwrap.

CSSM_CSP_KEY_FORMAT_INCORRECT

Unknown key format (for the unwrapping key).

CSSM_CSP_INVALID_KEY_SIZE_IN_BITS

Key size in bits unsupported (for the unwrapping key).

CSSM_CSP_INVALID_PADDING

Unknown padding.

CSSM_CSP_INVALID_MODE

Unknown algorithm mode for symmetric context.

CSSM_CSP_INVALID_ATTR_PASSPHRASE

Invalid or missing passphrase attribute in the asymmetric context.

CSSM_CSP_INVALID_ATTR_INIT_VECTOR

Init vector attribute data or length error for symmetric context.

CSSM_CSP_INVALID_KEYATTR

Specified key attribute is incorrect or unsupported.

Comments

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.

SEE ALSO

CSSM_WrapKey