NAME
   WrapKey,
   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:

    1.  Wrap a symmetric key with a symmetric key.

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

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

    4.  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.  See CDSA.

   None specific to this call.

 SEE ALSO
   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_UnwrapKey

   Functions for the CSP SPI:

       CSP_UnwrapKey