NAME
CSSM_DeriveKey, CSP_DeriveKey — Derive new symmetric key (CDSA)
SYNOPSIS
# include <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 *CredAndAclEntry,
CSSM_KEY_PTR DerivedKey) |
LIBRARY
Common Security Services Manager library (cdsa$incssm300_shr.exe)
API PARAMETERS
| CCHandle (input) | | The handle that describes the context of this cryptographic
operation. |
| Param (input/output) |
| | | 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. |
| KeyUsage (input) | | A bit mask indicating all permitted uses for the
new derived key. |
| KeyAttr (input) | | A bit mask defining other attribute values for the
new derived key. |
| KeyLabel (input/optional) |
| | | Pointer to a byte string that will be used as the
label for the derived 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 subject of 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 empty. |
| DerivedKey (output) |
| | | A pointer to a CSSM_KEY structure that returns the
derived key. |
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. |
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
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. 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 represent an error condition.
ERRORS
Errors are described in the CDSA Technical Standard.
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
Online Help
Functions: CSSM_CSP_CreateDeriveKeyContext
