UnwrapKey

If both a Table of Contents and Search form are not displayed in separate frames along with this one, you may wish to redisplay this book in a frameset, beginning with the first page.

HP Open Source Security for OpenVMS Volume 1:...

API Functions

Terminate

UnwrapKeyP

UnwrapKey

Library
Spi Parameters
Notes
Errors

Api Parameters
Description
Return Value
See Also

NAME

UnwrapKey: 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 cryptographicoperation.
`PublicKey` (input/optional)
		The public key corresponding to the private keybeing unwrapped. If a symmetric key is being unwrapped, then thisparameter must be NULL.
`WrappedKey` (input)
		A pointer to the wrapped key. The wrapped key maybe a symmetric key or the private key of a public/private key pair.The unwrapping method is specified as meta data within the wrappedkey and is not specified outside of the wrapped key.
`KeyUsage` (input)
		A bit mask indicating all permitted uses for theunwrapped key. If no value is specified, the CSP defines the usagemask for the unwrapped key.
`KeyAttr` (input)
		A bit mask defining other attribute values to beassociated with the unwrapped key.
`KeyLabel` (input/optional)
		Pointer to a byte string that will be used as thelabel for the unwrapped key.
`CredAndAclEntry` (input/optional)
		A structure containing one or more credentials authorizedfor creating a key and the prototype ACL entry that will controlfuture use of the newly created key. The credentials and ACL entryprototype can be presented as immediate values or callback functionscan be provided for use by the CSP to acquire the credentials and/orthe ACL entry interactively. If the CSP provides public access forcreating a key, then the credentials can be NULL. If the CSP definesa default initial ACL entry for the new key, then the ACL entryprototype can be an empty list.
`UnwrappedKey` (output)
		A pointer to a CSSM_KEY structure that returns theunwrapped key.
`DescriptiveData` (output)
		A pointer to a CSSM_DATA structure that returnsany additional descriptive data that was associated with the keyduring the wrapping operation. It is assumed that the caller incorporatedknowledge of the structure of this data. If no additional data isassociated with the imported key, this output value is NULL.

SPI PARAMETERS

`CSPHandle` (input)
		The handle that describes the add-in CryptographicService Provider module used to perform up calls to CSSM for thememory functions managed by CSSM.
`CCHandle` (input)
		The handle that describes the context of this cryptographicoperation.
`Context` (input)
		Pointer to CSSM_CONTEXT structure that describesthe attributes with this context.
`Privilege` (input)
		The export privilege to be applied during the cryptographicoperation. This parameter is forwarded to the CSP after CSSM verifiesthe caller and service provider privilege set includes the specifiedPRIVILEGE.

DESCRIPTION

This function unwraps the wrapped key using the context. Thewrapped key can be a symmetric key or a private key. If the unwrappingalgorithm is a symmetric algorithm, then a symmetric context mustbe provided. If the unwrapping algorithm is an asymmetric algorithm,then an asymmetric context must be provided. If the key is a privatekey, then an asymmetric context must be provide describing the unwrapping algorithm.The CSP can require the caller to provide credentials authorizingthe caller to store the unwrapped key within the CSP. The CSP canalso require that the caller provide an initial ACL entry to controlfuture access to the newly stored key. These credentials and theinitial ACL entry value are provided in CredAndAclEntry parameter.If the unwrapping algorithm is CSSM_ALGID_NONE and the wrapped key isactually a raw key (as indicated by its key attributes), then thekey is imported into the CSP. Support for a CSSM_ALGID_NONE unwrappingalgorithm is at the option of the CSP. The unwrapped key is restoredto its original pre-wrap state based on the key attributes recordedby the wrapped key during the wrap operation. These attributes mustnot be modified by the caller.

Authorization policy can restrict the set of callers who cancreate a new resource. In this case, the caller must present a setof access credentials for authorization. Upon successfully authenticatingthe credentials, the template that verified the presented samplesidentifies 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 associatedwith the newly created resource. This entry is used to control futureaccess to the new resource and (since the subject is deemed to bethe "Owner") exercise control over its associated ACL. The callercan specify the following items for initializing an ACL entry:

Subject - A CSSM_LIST structure, containingthe type of the subject and a template value that can be used toverify samples that are presented in credentials when resource accessis requested.

Delegation flag - A value indicating whether theSubject can delegate the permissions recorded in the AuthorizationTag.(This item only applies to public key subjects).

Authorization tag - The set of permissions thatare granted to the Subject.

Validity period - The start time and the stop timefor which the ACL entry is valid.

ACL entry tag - A user-defined string value associatedwith the ACL entry.

The service provider can modify the caller-provided initialACL entry to conform to any innate resource-access policy that theservice provider may be required to enforce. If the initial ACLentry provided by the caller contains values or permissions thatare not supported by the service provider, then the service providercan modify the initial ACL appropriately or can fail the requestto create the new resource. Service providers list their supported AuthorizationTag valuesin their Module Directory Services primary record.

NOTES

The KeyData field of the CSSM_KEY structureis allocated by the CSP. The application is required to free this memoryusing the CSSM_FreeKey() (CSSM API), or CSP_FreeKey() (CSP SPI), function or with the memory functions registeredfor the CSPHandle.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particularerror condition. The value CSSM_OK indicates success. All othervalues represent an error condition.

ERRORS

Errors are described in the CDSA Technical Standard.

CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTSCSSMERR_CSP_PUBLIC_KEY_INCONSISTENTCSSMERR_CSP_PRIVATE_KEY_ALREADY_EXIST