WrapKey

NAME

CSSM_WrapKey, CSP_WrapKey — Wrap a key using the context (CDSA)

SYNOPSIS

# include <cssm.h>

API:
CSSM_RETURN CSSMAPI CSSM_WrapKey
(CSSM_CC_HANDLE CCHandle,
const CSSM_ACCESS_CREDENTIALS *AccessCred,
const CSSM_KEY *Key,
const CSSM_DATA *DescriptiveData,
CSSM_WRAP_KEY_PTR WrappedKey)
SPI:
CSSM_RETURN CSSMCSPI CSP_WrapKey
(CSSM_CSP_HANDLE CSPHandle,
CSSM_CC_HANDLE CCHandle,
const CSSM_CONTEXT *Context,
const CSSM_ACCESS_CREDENTIALS *AccessCred,
const CSSM_KEY *Key,
const CSSM_DATA *DescriptiveData,
CSSM_WRAP_KEY_PTR WrappedKey,
CSSM_PRIVILEGE Privilege)

LIBRARY

Common Security Services Manager library (cdsa$incssm300_shr.exe)

API PARAMETERS

`CCHandle` (`input`)		The handle to the context that describes this cryptographic operation.
`AccessCred` (`input`)
		A pointer to the set of one or more credentials required to access the private or secret key to be exported from the CSP. The credentials structure can contain an immediate value for the credential, such as a passphrase, or the caller can specify a callback function the CSP can use to obtain one or more credentials.
`Key` (`input`)		A pointer to the key to be wrapped.
`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.

SPI 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.
`Context` (`input`)		Pointer to CSSM_CONTEXT structure that describes the attributes with this context.
`Privilege` (`input`)
		The export privilege to be applied during the cryptographic operation. This parameter is forwarded to the CSP after CSSM verifies the caller and service provider privilege set includes the specified PRIVILEGE.

DESCRIPTION

This function wraps the supplied key using the context. It allows a key to be exported from a CSP. Four types of wrapping exist:

Wrap a symmetric key with a symmetric key.
Wrap a symmetric key with an asymmetric public key.
Wrap an asymmetric private key with a symmetric key.
Wrap an asymmetric private key with an asymmetric public key.

For types 1 and 3, a symmetric context should be provided. For types 2 and 4, an asymmetric context is provided. If there is a CSSM_ATTRIBUTE_WRAPPED_KEY_FORMAT argument in the context represented by the CCHandle, the value of the attribute specifies the format of the wrapped key. If this argument is not present, the symmetric key is wrapped according to CMS for types 1 and 3, and according to PKCS8 for types 2 and 4. If the wrapping algorithm in the context is CSSM_ALGID_NONE, then the key is returned in raw format, if permitted and supported by the CSP (in this case the CSSM_ATTRIBUTE_WRAPPED_KEY_FORMAT attribute is ignored). All significant key attributes are incorporated into the KeyHeader of the returned WrappedKey, such that the state of the key can be fully restored by the unwrap process.

The CSP can require that the cryptographic context includes access credentials for authentication and authorization checks when using the secret or private key.

NOTES

The KeyData field of the CSSM_KEY structure is allocated by the CSP. The application is required to free this memory using the CSSM_FreeKey() (CSSM API), or CSP_FreeKey() (CSP SPI) function, or with the memory functions registered for the CSPHandle.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

Errors are described in the CDSA Technical Standard.

None specific to this call.

WrapKey

» Table of Contents

» Glossary

» Index