WrapKey

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