GenerateKeyPair(3)GenerateKeyPair(3)NAME
GenerateKeyPair, CSSM_GenerateKeyPair, CSP_GenerateKeyPair - Generate
an asymmetric key pair (CDSA)
SYNOPSIS
# include <cdsa/cssm.h>
API: CSSM_RETURN CSSMAPI CSSM_GenerateKeyPair (CSSM_CC_HANDLE CCHandle,
uint32 PublicKeyUsage, uint32 PublicKeyAttr, const CSSM_DATA *PublicK‐
eyLabel, CSSM_KEY_PTR PublicKey, uint32 PrivateKeyUsage, uint32 Pri‐
vateKeyAttr, const CSSM_DATA *PrivateKeyLabel, const CSSM_RESOURCE_CON‐
TROL_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 PublicK‐
eyUsage, 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 (libcssm.so)
API PARAMETERS
The handle that describes the context of this cryptographic operation
used to link to the CSP-managed information. A bit mask indicating all
permitted uses for the new public key. A bit mask defining attribute
values for the new public key. Pointer to a byte string that will be
used as the label for the public key. 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 Pub‐
licKeyLabel input parameters. A bit mask indicating all permitted uses
for the new private key. A bit mask defining attribute values for the
new private key. Pointer to a byte string that will be used as the
label for the private key. A structure containing one or more creden‐
tials 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. 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 sup‐
plied in the cryptographic Context, PrivateKeyUsage, PrivateKeyAttr,
and PrivateKeyLabel input parameters.
SPI PARAMETERS
The handle that describes the add-in cryptographic service provider
module used to perform calls to CSSM for the memory functions managed
by CSSM. The handle that describes the context of this cryptographic
operation used to link to the CSP-managed information. Pointer to
CSSM_CONTEXT structure that describes the attributes with this context.
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 key‐
ing 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 identi‐
fies 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: 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. A value indicating whether the Subject can dele‐
gate the permissions recorded in the AuthorizationTag. (This item
applies only to public key subjects). The set of permissions that are
granted to the Subject. The start time and the stop time for which the
ACL entry is valid. 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 Direc‐
tory 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 repre‐
sent 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_GenerateKey(3), CSSM_GenerateRandom(3)
Functions for the CSP SPI:
CSP_GenerateKey(3), CSP_GenerateRandom(3)GenerateKeyPair(3)