*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> CSSM_UnwrapKey (3)              
Title
Content
Arch
Section
 

UnwrapKey(3)

Contents


NAME    [Toc]    [Back]

       UnwrapKey,  CSSM_UnwrapKey,  CSP_UnwrapKey  -  Unwrap  the
       wrapped key (CDSA)

SYNOPSIS    [Toc]    [Back]

       # 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    [Toc]    [Back]

       Common Security Services Manager library (libcssm.so)

API PARAMETERS    [Toc]    [Back]

       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.






SPI PARAMETERS    [Toc]    [Back]

       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.

DESCRIPTION    [Toc]    [Back]

       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.

NOTES    [Toc]    [Back]

       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    [Toc]    [Back]

       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    [Toc]    [Back]

       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    [Toc]    [Back]

      
      
       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 ]
 Similar pages
Name OS Title
UnwrapKeyP Tru64 Unwrap the wrapped keys with privilege (CDSA)
CSP_GetTimeValue Tru64 Get a CSP time value (CDSA)
CSP_RetrieveUniqueId Tru64 Get identifier (CDSA)
CSSM_RetrieveUniqueId Tru64 Get identifier (CDSA)
CSSM_CSP_Login Tru64 Log user in to the CSP (CDSA)
CSSM_GetTimeValue Tru64 Get a CSP time value (CDSA)
CSSM_CL_CrlSign Tru64 Sign a CRL (CDSA)
CSSM_GetKeyAcl Tru64 Get ACL entries by key (CDSA)
CSSM_CL_CertVerifyWithKey Tru64 Verify with a key (CDSA)
CSSM_CL_CrlGetFirstFieldValue Tru64 Get the value of the first CRL field (CDSA)
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service