DeriveKey

NAME
  DeriveKey,
  CSSM_DeriveKey,
  CSP_DeriveKey   - Derive new symmetric key (CDSA)

SYNOPSIS
  # include <cssm.h>

   API:
       CSSM_RETURN CSSMAPI CSSM_DeriveKey
       (CSSM_CC_HANDLE CCHandle,
       CSSM_DATA_PTR Param,
       uint32 KeyUsage,
       uint32 KeyAttr,
       const CSSM_DATA *KeyLabel,
       const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
       CSSM_KEY_PTR DerivedKey)
   SPI:
       CSSM_RETURN CSSMCSPI CSP_DeriveKey
       (CSSM_CSP_HANDLE CSPHandle,
       CSSM_CC_HANDLE CCHandle,
       const CSSM_CONTEXT *Context,
       CSSM_DATA_PTR Param,
       uint32 KeyUsage,
       uint32 KeyAttr,
       const CSSM_DATA *KeyLabel,
       const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
       CSSM_KEY_PTR DerivedKey)

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

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

  Param (input/output)
          This parameter varies depending on the derivation algorithm.
          Password based derivation algorithms use this parameter to
          return a cipher block chaining initialization vector.
          Concatenation algorithms use this parameter to get the second
          item to concatenate.

  KeyUsage (input)
          A bit mask indicating all permitted uses for the new derived
          key.

  KeyAttr (input)
          A bit mask defining other attribute values for the new derived
          key.

  KeyLabel (input/optional)
          Pointer to a byte string that will be used as the label for the
          derived 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 subject of 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 empty.

  DerivedKey (output)
          A pointer to a CSSM_KEY structure that returns the derived 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.

DESCRIPTION
  This function derives a new symmetric key using the context and/or
  information from the base key in the context. The CSP can require that
  the cryptographic context include access credentials for authentication
  and authorization checks when using a private key or a secret key.

  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.

          The CSP can require that the cryptographic context include
          access credentials for authentication and authorization
          checks when using a private key or a secret key.

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

COMMENTS
  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) call, or with
  the memory functions registered for the CSPHandle.

SEE ALSO
  Books

  Intel CDSA Application Developer's Guide (see CDSA)

  Other Help Topics

  Functions: CSSM_CSP_CreateDeriveKeyContext