WrapKey(3)WrapKey(3)NAME
WrapKey, CSSM_WrapKey, CSP_WrapKey - Wrap a key using the context
(CDSA)
SYNOPSIS
# include <cdsa/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_PRIVI‐
LEGE Privilege)
LIBRARY
Common Security Services Manager library (libcssm.so)
API PARAMETERS
The handle to the context that describes this cryptographic operation.
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. A pointer to the key to be
wrapped. 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 param‐
eter 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. A pointer to a CSSM_WRAP_KEY structure
that returns the wrapped key.
SPI PARAMETERS
The handle that describes the add-in cryptographic service provider
module used to perform up-calls to CSSM for the memory functions man‐
aged by CSSM. Pointer to CSSM_CONTEXT structure that describes the
attributes with this context. The export privilege to be applied dur‐
ing 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 symmet‐
ric 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 signifi‐
cant 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 cre‐
dentials 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 repre‐
sent an error condition.
ERRORS
Errors are described in the CDSA technical standard. See
CDSA_intro(3).
None specific to this call.
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA_intro(3))
Reference Pages
Functions for the CSSM API:
CSSM_UnwrapKey(3)
Functions for the CSP SPI:
CSP_UnwrapKey(3)WrapKey(3)
