NAME

CSP_UnwrapKey

SYNOPSIS

CSSM_RETURN CSSMSPI CSP_UnwrapKey
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT_PTR Context,
    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 CSP must recover the complete state of the unwrapped key based on the key attributes stored in the wrapped key.

PARAMETERS

CSPHandle (input)

The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

CCHandle (input)

The handle that describes the context of this cryptographic operation.

Context (input)

Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

PassPhrase (input)

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 secure the private key after it is unwrapped. It is assumed that a known public key is associated with the private key.

PublicKey (input)

The public key corresponding to the private key being unwrapped.

WrappedKey (input)

A pointer to the wrapped key. The wrapped key may be a symmetric key or the private key of a public/private keypair. 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 specifying how the unwrapped key can be used.

KeyAttr (input/optional)

A bit mask specifying other attributes 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_CSP_HANDLE

Invalid CSP handle.

CSSM_CSP_INVALID_CONTEXT_HANDLE

Invalid context handle.

CSSM_CSP_INVALID_CONTEXT_POINTER

Invalid CSSM_CONTEXT pointer.

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.

SEE ALSO

CSP_WrapKey