NAME
   UnwrapKey,
   CSSM_UnwrapKey,
   CSP_UnwrapKey - Unwrap the wrapped key (CDSA)

 SYNOPSIS
   # include <cssm.h>

    API:
        CSSM_RETURN CSSMAPI CSSM_UnwrapKey
        (CSSM_CC_HANDLE CCHandle,
        const CSSM_KEY *PublicKey,
        const CSSM_WRAP_KEY *WrappedKey,
        uint32 KeyUsage,
        uint32 KeyAttr,
        const CSSM_DATA *KeyLabel,
        const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
        CSSM_KEY_PTR UnwrappedKey,
        CSSM_DATA_PTR DescriptiveData)
    SPI:
        CSSM_RETURN CSSMCSPI CSP_UnwrapKey
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context,
        const CSSM_KEY *PublicKey,
        const CSSM_WRAP_KEY *WrappedKey,
        uint32 KeyUsage,
        uint32 KeyAttr,
        const CSSM_DATA *KeyLabel,
        const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
        CSSM_KEY_PTR UnwrappedKey,
        CSSM_DATA_PTR DescriptiveData,
        CSSM_PRIVILEGE Privilege)

 LIBRARY
   Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE)

 API PARAMETERS
   CCHandle (input)
           The handle that describes the context of this cryptographic
           operation.

   PublicKey (input/optional)
           The public key corresponding to the private key being
           unwrapped. If a symmetric key is being unwrapped, then
           this parameter must be NULL.

   WrappedKey (input)
           A pointer to the wrapped key. The wrapped key may be a
           symmetric key or the private key of a public/private key
           pair. The unwrapping method is specified as meta data
           within the wrapped key and is not specified outside of the
           wrapped key.

   KeyUsage (input)
           A bit mask indicating all permitted uses for the unwrapped
           key. If no value is specified, the CSP defines the usage
           mask for the unwrapped key.

   KeyAttr (input)
           A bit mask defining other attribute values to be associated
           with the unwrapped key.

   KeyLabel (input/optional)
           Pointer to a byte string that will be used as the label for
           the unwrapped key.

   CredAndAclEntry (input/optional)
           A structure containing one or more credentials authorized
           for creating a key and the prototype ACL entry that will
           control future use of the newly created key. The credentials
           and ACL entry prototype can be presented as immediate values
           or callback functions can be provided for use by the CSP to
           acquire the credentials and/or the ACL entry interactively.
           If the CSP provides public access for creating a key, then
           the credentials can be NULL.  If the CSP defines a default
           initial ACL entry for the new key, then the ACL entry
           prototype can be an empty list.

   UnwrappedKey (output)
           A pointer to a CSSM_KEY structure that returns the unwrapped
           key.

   DescriptiveData (output)
           A pointer to a CSSM_DATA structure that returns any
           additional descriptive data that was associated with the
           key during the wrapping operation. It is assumed that the
           caller incorporated knowledge of the structure of this
           data. If no additional data is associated with the imported
           key, this output value is NULL.

 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.

   CCHandle (input)
           The handle that describes the context of this cryptographic
           operation.

   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 unwraps the wrapped key using the context. The wrapped
   key can be a symmetric key or a private key. If the unwrapping
   algorithm is a symmetric algorithm, then a symmetric context must be
   provided. If the unwrapping algorithm is an asymmetric algorithm,
   then an asymmetric context must be provided.  If the key is a private
   key, then an asymmetric context must be provide describing the
   unwrapping algorithm. The CSP can require the caller to provide
   credentials authorizing the caller to store the unwrapped key within
   the CSP. The CSP can also require that the caller provide an initial
   ACL entry to control future access to the newly stored key. These
   credentials and the initial ACL entry value are provided in
   CredAndAclEntry parameter. If the unwrapping algorithm is
   CSSM_ALGID_NONE and the wrapped key is actually a raw key (as
   indicated by its key attributes), then the key is imported into
   the CSP. Support for a CSSM_ALGID_NONE unwrapping algorithm is at
   the option of the CSP. The unwrapped key is restored to its
   original pre-wrap state based on the key attributes recorded by the
   wrapped key during the wrap operation.  These attributes must not
   be modified by the caller.

   Authorization policy can restrict the set of callers who can create
   a new resource. In this case, the caller must present a set of access
   credentials for authorization. Upon successfully authenticating the
   credentials, the template that verified the presented samples
   identifies the ACL entry that will be used in the authorization
   computation. If the caller is authorized, the new resource is created.

   The caller must provide an initial ACL entry to be associated with
   the newly created resource. This entry is used to control future
   access to the new resource and (since the subject is deemed to be
   the "Owner") exercise control over its associated ACL. The caller
   can specify the following items for initializing an ACL entry:

   Subject A CSSM_LIST structure, containing the type of the subject
           and a template value that can be used to verify samples
           that are presented in credentials when resource access is
           requested.

   Delegation flag
           A value indicating whether the Subject can delegate the
           permissions recorded in the AuthorizationTag. (This item
           only applies to public key subjects).

   Authorization tag
           The set of permissions that are granted to the Subject.

   Validity period
           The start time and the stop time for which the ACL entry is
           valid.

   ACL entry tag
           A user-defined string value associated with the ACL entry.

           The service provider can modify the caller-provided initial
           ACL entry to conform to any innate resource-access policy
           that the service provider may be required to enforce. If the
           initial ACL entry provided by the caller contains values or
           permissions that are not supported by the service provider,
           then the service provider can modify the initial ACL
           appropriately or can fail the request to create the new
           resource. Service providers list their supported
           AuthorizationTag values in their Module Directory Services
           primary record.

 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.

        CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS
        CSSMERR_CSP_PUBLIC_KEY_INCONSISTENT
        CSSMERR_CSP_PRIVATE_KEY_ALREADY_EXIST

 SEE ALSO
   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_WrapKey

   Functions for the CSP SPI:

       CSP_WrapKey