DeriveKey, CSSM_DeriveKey, CSP_DeriveKey - Derive new symmetric
key (CDSA)
# 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 *CredAndAclEntry,
CSSM_KEY_PTR DerivedKey)
Common Security Services Manager library (libcssm.so)
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 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. A pointer to a
CSSM_KEY structure that returns the derived key.
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. Pointer to CSSM_CONTEXT
structure that describes the attributes with this context.
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: 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
delegate 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 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.
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 are described in the CDSA technical standard. See
CDSA_intro(3). CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS
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.
Books
Intel CDSA Application Developer's Guide (see
CDSA_intro(3))
Reference Pages [Toc] [Back]
Functions: CSSM_CSP_CreateDeriveKeyContext(3)
DeriveKey(3)
[ Back ] | 