Index for Section 3

Alphabetical listing for G

Bottom of page

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

SYNOPSIS
  # include <cdsa/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 (libcssm.so)

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_intro(3).

       CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS

SEE ALSO
  Books

  Intel CDSA Application Developer's Guide (see CDSA_intro(3))

  Reference Pages

  Functions for the CSSM API:

  CSSM_GenerateRandom(3), CSSM_GenerateKeyPair(3)

  Functions for the CSP SPI:

  CSP_GenerateRandom(3), CSP_GenerateKeyPair(3)

Index for Section 3

Alphabetical listing for G

Top of page