DeriveKey(3)DeriveKey(3)NAME
DeriveKey, CSSM_DeriveKey, CSP_DeriveKey - Derive new symmetric key
(CDSA)
SYNOPSIS
# include <cdsa/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 *CredAndAclEn‐
try, CSSM_KEY_PTR DerivedKey)
LIBRARY
Common Security Services Manager library (libcssm.so)
API PARAMETERS
The handle that describes the context of this cryptographic operation.
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. A bit mask indicating
all permitted uses for the new derived key. A bit mask defining other
attribute values for the new derived key. Pointer to a byte string
that will be used as the label for the derived key. A structure con‐
taining 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 imme‐
diate values or callback functions can be provided for use by the CSP
to acquire the credentials and/or the subject of the ACL entry interac‐
tively. 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. A pointer
to a CSSM_KEY structure that returns the derived key.
SPI PARAMETERS
The handle that describes the add-in cryptographic service provider
module used to perform up calls to CSSM for the memory functions man‐
aged by CSSM. 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 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 only
applies 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.
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 repre‐
sent an error condition.
ERRORS
Errors are described in the CDSA technical standard. See
CDSA_intro(3). 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_intro(3))
Reference Pages
Functions: CSSM_CSP_CreateDeriveKeyContext(3)DeriveKey(3)