NAME
   GenerateKeyPair,
   CSSM_GenerateKeyPair,
   CSP_GenerateKeyPair  - Generate an asymmetric key pair (CDSA)

 SYNOPSIS
   # include <cssm.h>

    API:
        CSSM_RETURN CSSMAPI CSSM_GenerateKeyPair
        (CSSM_CC_HANDLE CCHandle,
        uint32 PublicKeyUsage,
        uint32 PublicKeyAttr,
        const CSSM_DATA *PublicKeyLabel,
        CSSM_KEY_PTR PublicKey,
        uint32 PrivateKeyUsage,
        uint32 PrivateKeyAttr,
        const CSSM_DATA *PrivateKeyLabel,
        const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
        CSSM_KEY_PTR PrivateKey)
    SPI:
        CSSM_RETURN CSSMCSPI CSP_GenerateKeyPair
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context,
        uint32 PublicKeyUsage,
        uint32 PublicKeyAttr,
        const CSSM_DATA *PublicKeyLabel,
        CSSM_KEY_PTR PublicKey,
        uint32 PrivateKeyUsage,
        uint32 PrivateKeyAttr
        const CSSM_DATA *PrivateKeyLabel,
        const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
        CSSM_KEY_PTR PrivateKey,
        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 used to link to the CSP-managed information.

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

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

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

   PublicKey (output)
           Pointer to CSSM_KEY structure used to hold the new public 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, PublicKeyUsage,
           PublicKeyAttr, and PublicKeyLabel input parameters.

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

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

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

   PrivateKey (output)
           Pointer to CSSM_KEY structure used to obtain the private key.
           Upon function invocation, any values in the CSSM_Key
           structure should be ignored.  All input values should be
           supplied in the cryptographic Context, PrivateKeyUsage,
           PrivateKeyAttr, and PrivateKeyLabel input parameters.

 SPI PARAMETERS
   CSPHandle (input)
           The handle that describes the add-in cryptographic service
           provider module used to perform calls to CSSM for the
           memory functions managed by CSSM.

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

   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 generates an asymmetric key pair. The CSP may cache
   keying material associated with the new asymmetric keypair. When
   one or both of the keys are no longer in active use, the application
   can invoke the CSSM_FreeKey() interface to allow cached keying
   material associated with the 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
           applies only 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 fields of the CSSM_KEY structures are 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_GenerateKey
       CSSM_GenerateRandom

   Functions for the CSP SPI:

       CSP_GenerateKey
       CSP_GenerateRandom