NAME

CSSM_WrapKey

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_WrapKey
    (CSSM_CC_HANDLE CCHandle,
    const CSSM_CRYPTO_DATA_PTR PassPhrase,
    CSSM_KEY_PTR Key,
    CSSM_DATA_PTR DescriptiveData,
    CSSM_WRAP_KEY_PTR WrappedKey)

DESCRIPTION

This function wraps the supplied key using the context. The key can be a symmetric key or a reference to a private key. If the key is a symmetric key, then a symmetric context must be provided describing the wrapping algorithm. If the key is a private key, then an asymmetric context describing the wrapping algorithm, and a passphrase to unlock the referenced private key must be provided. If the specified wrapping algorithm is NULL, then the key is returned in raw format, if permitted and supported by the CSP. All significant key attributes are incorporated into the wrapped key, such that the state of the key can be fully restored by the unwrap process.

PARAMETERS

CCHandle (input)

The handle to the context that describes this cryptographic operation.

PassPhrase (input)

The passphrase or a callback function to be used to obtain the passphrase that can be used by the CSP to unlock the private key before it is wrapped. This input is ignored when wrapping a symmetric, secret key.

Key (input)

A pointer to the target key to be wrapped. If a private key is to be wrapped, this is a reference to the private key. If a symmetric key is to be wrapped, the target key is that symmetric key.

DescriptiveData (input/optional)

A pointer to a CSSM_DATA structure containing additional descriptive data to be associated and included with the key during the wrapping operation. The caller and the wrapping algorithm incorporate knowledge of the structure of the descriptive data. If the wrapping algorithm does not accept additional descriptive data, then this parameter must be NULL. If the wrapping algorithm accepts descriptive data, the corresponding unwrapping algorithm can be used to extract the descriptive data and the key.

WrappedKey (output)

A pointer to a CSSM_WRAP_KEY structure that returns the wrapped key.

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. The context has to be either symmetric context or asymmetric context.

CSSM_CSP_INVALID_ALGORITHM

Unknown algorithm.

CSSM_CSP_MEMORY_ERROR

Not enough memory to allocate.

CSSM_CSP_OPERATION_UNSUPPORTED

Wrap key service not supported.

CSSM_CSP_OPERATION_FAILED

Cryptographic operation failed.

CSSM_CSP_INVALID_KEY_POINTER

Invalid CSSM_KEY or CSSM_WRAP_KEYpointers.

CSSM_INVALID_SUBJECT_KEY

Invalid wrapping subject key (key to be wrapped).

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 wrapping key in the asymmetric context.

CSSM_CSP_PRIKEY_NOT_FOUND

Cannot find the subject private key.

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 subject private key or subject private key storage error.

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 wrapping) does not match the operation.

CSSM_CSP_KEY_KEYHEADER_INCONSISTENT

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

CSSM_CSP_KEY_USAGE_INCORRECT

Key usage mask (for the wrapping key) does not allow wrap.

CSSM_CSP_KEY_FORMAT_INCORRECT

Unknown key format (for the wrapping key).

CSSM_CSP_INVALID_KEY_SIZE_IN_BITS

Key size in bits unsupported (for the wrapping 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.

SEE ALSO

CSSM_UnwrapKey