NAME
   GenerateKey,
   CSSM_GenerateKey,
   CSP_GenerateKey   - Generate a symmetric key (CDSA)

 SYNOPSIS
   # include <cssm.h>

    API:
        CSSM_RETURN CSSMAPI CSSM_GenerateKey
        (CSSM_CC_HANDLE CCHandle,
        uint32 KeyUsage,
        uint32 KeyAttr,
        const CSSM_DATA *KeyLabel,
        const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
        CSSM_KEY_PTR Key)
    SPI:
        CSSM_RETURN CSSMCSPI CSP_GenerateKey
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context,
        uint32 KeyUsage,
        uint32 KeyAttr,
        const CSSM_DATA *KeyLabel,
        const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
        CSSM_KEY_PTR Key)

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

 API PARAMETERS
   CCHandle (input)
           The handle that describes the context of this cryptographic
           operation used to link to the CSP-managed information.

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

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

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

   Key (output)
           Pointer to CSSM_KEY structure used to hold the new key.
           The CSSM_KEY structure should be empty upon input to this
           function. The CSP will ignore any values residing in this
           structure at function invocation. Input values should be
           supplied in the cryptographic context, KeyUsage, KeyAttr,
           and KeyLabel input parameters.

 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.

   Key (output)
           Pointer to CSSM_KEY structure used to obtain the key. Upon
           function invocation, any values in the CSSM_Key structure
           should be ignored.  All input values should be supplied in
           the cryptographic Context, KeyUsage, KeyAttr, and KeyLabel
           input parameters.

 DESCRIPTION
   This function generates a symmetric key. The KeyUsage, and KeyAttr
   are used to initialize the keyheader for the newly created key.
   These values are not retained in the cryptographic Context, which
   contains additional parameters for this operation. The CSP may cache
   keying material associated with the new symmetric key. When the
   symmetric key is no longer in active use, the application can invoke
   the CSSM_FreeKey() interface to allow cached keying material
   associated with the symmetric key to be removed.

   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

 SEE ALSO
   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_GenerateRandom
       CSSM_GenerateKeyPair

   Functions for the CSP SPI:

       CSP_GenerateRandom
       CSP_GenerateKeyPair