UnwrapKey(3)UnwrapKey(3)NAME
UnwrapKey, CSSM_UnwrapKey, CSP_UnwrapKey - Unwrap the wrapped key
(CDSA)
SYNOPSIS
# include <cdsa/cssm.h>
API: CSSM_RETURN CSSMAPI CSSM_UnwrapKey (CSSM_CC_HANDLE CCHandle, const
CSSM_KEY *PublicKey, const CSSM_WRAP_KEY *WrappedKey, uint32 KeyUsage,
uint32 KeyAttr, const CSSM_DATA *KeyLabel, const CSSM_RESOURCE_CON‐
TROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR UnwrappedKey, CSSM_DATA_PTR
DescriptiveData) SPI: CSSM_RETURN CSSMCSPI CSP_UnwrapKey (CSSM_CSP_HAN‐
DLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context,
const CSSM_KEY *PublicKey, const CSSM_WRAP_KEY *WrappedKey, uint32
KeyUsage, uint32 KeyAttr, const CSSM_DATA *KeyLabel, const
CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR Unwrapped‐
Key, CSSM_DATA_PTR DescriptiveData, CSSM_PRIVILEGE Privilege)
LIBRARY
Common Security Services Manager library (libcssm.so)
API PARAMETERS
The handle that describes the context of this cryptographic operation.
The public key corresponding to the private key being unwrapped. If a
symmetric key is being unwrapped, then this parameter must be NULL. A
pointer to the wrapped key. The wrapped key may be a symmetric key or
the private key of a public/private key pair. The unwrapping method is
specified as meta data within the wrapped key and is not specified out‐
side of the wrapped key. A bit mask indicating all permitted uses for
the unwrapped key. If no value is specified, the CSP defines the usage
mask for the unwrapped key. A bit mask defining other attribute values
to be associated with the unwrapped key. Pointer to a byte string that
will be used as the label for the unwrapped key. A structure contain‐
ing one or more credentials authorized for creating a key and the pro‐
totype 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. A pointer to a
CSSM_KEY structure that returns the unwrapped key. A pointer to a
CSSM_DATA structure that returns any additional descriptive data that
was associated with the key during the wrapping operation. It is
assumed that the caller incorporated knowledge of the structure of this
data. If no additional data is associated with the imported key, this
output value is NULL.
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. The handle that describes the context of this crypto‐
graphic operation. 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 unwraps the wrapped key using the context. The wrapped
key can be a symmetric key or a private key. If the unwrapping algo‐
rithm is a symmetric algorithm, then a symmetric context must be pro‐
vided. If the unwrapping algorithm is an asymmetric algorithm, then an
asymmetric context must be provided. If the key is a private key, then
an asymmetric context must be provide describing the unwrapping algo‐
rithm. The CSP can require the caller to provide credentials authoriz‐
ing the caller to store the unwrapped key within the CSP. The CSP can
also require that the caller provide an initial ACL entry to control
future access to the newly stored key. These credentials and the ini‐
tial ACL entry value are provided in CredAndAclEntry parameter. If the
unwrapping algorithm is CSSM_ALGID_NONE and the wrapped key is actually
a raw key (as indicated by its key attributes), then the key is
imported into the CSP. Support for a CSSM_ALGID_NONE unwrapping algo‐
rithm is at the option of the CSP. The unwrapped key is restored to its
original pre-wrap state based on the key attributes recorded by the
wrapped key during the wrap operation. These attributes must not be
modified by the caller.
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.
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 repre‐
sent an error condition.
ERRORS
Errors are described in the CDSA technical standard. See
CDSA_intro(3). CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS CSSMERR_CSP_PUB‐
LIC_KEY_INCONSISTENT CSSMERR_CSP_PRIVATE_KEY_ALREADY_EXIST
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA_intro(3))
Reference Pages
Functions for the CSSM API:
CSSM_WrapKey(3)
Functions for the CSP SPI:
CSP_WrapKey(3)UnwrapKey(3)
