UnwrapKey, CSSM_UnwrapKey, CSP_UnwrapKey - Unwrap the
wrapped key (CDSA)
# 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_CONTROL_CONTEXT
*CredAndAclEntry, CSSM_KEY_PTR UnwrappedKey, CSSM_DATA_PTR
DescriptiveData) SPI: CSSM_RETURN CSSMCSPI CSP_UnwrapKey
(CSSM_CSP_HANDLE 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 UnwrappedKey,
CSSM_DATA_PTR DescriptiveData, CSSM_PRIVILEGE Privilege)
Common Security Services Manager library (libcssm.so)
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 outside 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 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 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.
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. The handle that
describes the context of this cryptographic 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.
This function unwraps the wrapped key using the context.
The wrapped key can be a symmetric key or a private key.
If the unwrapping algorithm is a symmetric algorithm, then
a symmetric context must be provided. 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 algorithm. The CSP can require the caller to
provide credentials authorizing 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 initial 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 algorithm 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 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 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.
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 CSSMERR_CSP_PUBLIC_KEY_INCONSISTENT
CSSMERR_CSP_PRIVATE_KEY_ALREADY_EXIST
Books
Intel CDSA Application Developer's Guide (see
CDSA_intro(3))
Reference Pages [Toc] [Back]
Functions for the CSSM API:
CSSM_WrapKey(3)
Functions for the CSP SPI:
CSP_WrapKey(3)
UnwrapKey(3)
[ Back ] | 