NAME
CSSM_UnwrapKey, CSP_UnwrapKey — Unwrap the wrapped key (CDSA)
SYNOPSIS
# include <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) |
LIBRARY
Common Security Services Manager library (cdsa$incssm300_shr.exe)
API PARAMETERS
| CCHandle (input) | | The handle that describes the context of this cryptographic
operation. |
| PublicKey (input/optional) |
| | | The public key corresponding to the private key
being unwrapped. If a symmetric key is being unwrapped, then this
parameter must be NULL. |
| WrappedKey (input) |
| | | 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. |
| KeyUsage (input) | | 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. |
| KeyAttr (input) | | A bit mask defining other attribute values to be
associated with the unwrapped key. |
| KeyLabel (input/optional) |
| | | Pointer to a byte string that will be used as the
label for the unwrapped 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 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. |
| UnwrappedKey (output) |
| | | A pointer to a CSSM_KEY structure that returns the
unwrapped key. |
| DescriptiveData (output) |
| | | 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
| 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. |
| CCHandle (input) | | The handle that describes the context of this cryptographic
operation. |
| Context (input) | | Pointer to CSSM_CONTEXT structure that describes
the attributes with this context. |
| Privilege (input) |
| | | 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
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:
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.
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 represent an error condition.
ERRORS
Errors are described in the CDSA Technical Standard.
CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS
CSSMERR_CSP_PUBLIC_KEY_INCONSISTENT
CSSMERR_CSP_PRIVATE_KEY_ALREADY_EXIST |
SEE ALSO
Books
Intel CDSA Application Developer's Guide
Online Help
Functions for the CSSM API:
CSSM_WrapKey
Functions for the CSP SPI:
CSP_WrapKey
