Index for Section 3

Alphabetical listing for U

Bottom of page

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_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 (libcssm.so)

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.	See CDSA_intro(3).

       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 (see CDSA_intro(3))

  Reference Pages

  Functions for the CSSM API:

  CSSM_WrapKey(3)

  Functions for the CSP SPI:

  CSP_WrapKey(3)

Index for Section 3

Alphabetical listing for U

Top of page