Index for Section 3

Alphabetical listing for W

Bottom of page

WrapKey(3)
NAME
  WrapKey, CSSM_WrapKey, CSP_WrapKey - Wrap a key using the context (CDSA)

SYNOPSIS
  # include <cdsa/cssm.h>

       API:
       CSSM_RETURN CSSMAPI CSSM_WrapKey
       (CSSM_CC_HANDLE CCHandle,
       const CSSM_ACCESS_CREDENTIALS *AccessCred,
       const CSSM_KEY *Key,
       const CSSM_DATA *DescriptiveData,
       CSSM_WRAP_KEY_PTR WrappedKey)
       SPI:
       CSSM_RETURN CSSMCSPI CSP_WrapKey
       (CSSM_CSP_HANDLE CSPHandle,
       CSSM_CC_HANDLE CCHandle,
       const CSSM_CONTEXT *Context,
       const CSSM_ACCESS_CREDENTIALS *AccessCred,
       const CSSM_KEY *Key,
       const CSSM_DATA *DescriptiveData,
       CSSM_WRAP_KEY_PTR WrappedKey,
       CSSM_PRIVILEGE Privilege)

LIBRARY
  Common Security Services Manager library (libcssm.so)

API PARAMETERS
  CCHandle (input)
	  The handle to the context that describes this cryptographic
	  operation.

  AccessCred (input)
	  A pointer to the set of one or more credentials required to access
	  the private or secret key to be exported from the CSP. The
	  credentials structure can contain an immediate value for the
	  credential, such as a passphrase, or the caller can specify a
	  callback function the CSP can use to obtain one or more
	  credentials.

  Key (input)
	  A pointer to the key to be wrapped.

  DescriptiveData (input/optional)
	  A pointer to a CSSM_DATA structure containing additional
	  descriptive data to be associated and included with the key during
	  the wrapping operation.  The caller and the wrapping algorithm
	  incorporate knowledge of the structure of the descriptive data. If
	  the wrapping algorithm does not accept additional descriptive data,
	  then this parameter must be NULL. If the wrapping algorithm accepts
	  descriptive data, the corresponding unwrapping algorithm can be
	  used to extract the descriptive data and the key.

  WrappedKey (output)
	  A pointer to a CSSM_WRAP_KEY structure that returns the wrapped
	  key.

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.

  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 wraps the supplied key using the context. It allows a key to
  be exported from a CSP. Four types of wrapping exist:

   1.  Wrap a symmetric key with a symmetric key.

   2.  Wrap a symmetric key with an asymmetric public key.

   3.  Wrap an asymmetric private key with a symmetric key.

   4.  Wrap an asymmetric private key with an asymmetric public key.

  For types 1 and 3, a symmetric context should be provided. For types 2 and
  4, an asymmetric context is provided. If there is a
  CSSM_ATTRIBUTE_WRAPPED_KEY_FORMAT argument in the context represented by
  the CCHandle, the value of the attribute specifies the format of the
  wrapped key. If this argument is not present, the symmetric key is wrapped
  according to CMS for types 1 and 3, and according to PKCS8 for types 2 and
  4. If the wrapping algorithm in the context is CSSM_ALGID_NONE, then the
  key is returned in raw format, if permitted and supported by the CSP (in
  this case the CSSM_ATTRIBUTE_WRAPPED_KEY_FORMAT attribute is ignored). All
  significant key attributes are incorporated into the KeyHeader of the
  returned WrappedKey, such that the state of the key can be fully restored
  by the unwrap process.

  The CSP can require that the cryptographic context includes access
  credentials for authentication and authorization checks when using the
  secret or private key.

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).

  None specific to this call.

SEE ALSO
  Books

  Intel CDSA Application Developer's Guide (see CDSA_intro(3))

  Reference Pages

  Functions for the CSSM API:

  CSSM_UnwrapKey(3)

  Functions for the CSP SPI:

  CSP_UnwrapKey(3)

Index for Section 3

Alphabetical listing for W

Top of page