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.
SEE ALSO
Books
Intel CDSA Application Developer's Guide
Online Help
Functions for the CSSM API:
CSSM_UnwrapKey
Functions for the CSP SPI:
CSP_UnwrapKey
