Previous section.

Common Security: CDSA and CSSM
Copyright © 1997 The Open Group




    const CSSM_CRYPTO_DATA_PTR NewPassPhrase,
    const CSSM_KEY_PTR PublicKey
    const CSSM_WRAP_KEY_PTR WrappedKey,
    uint32 KeyUsage,
    uint32 KeyAttr,
    const CSSM_DATA_PTR KeyLabel,
    CSSM_KEY_PTR UnwrappedKey,
    CSSM_DATA_PTR DescriptiveData)


This function unwraps the wrapped key using the context. The wrapped key can be a symmetric key or a private key. If the key is a symmetric key, then a symmetric context must be provide describing the unwrapping algorithm. If the key is a private key, then an asymmetric context must be provide describing the unwrapping algorithm. Depending on the persistent object mode of the CSP and the storage mode specified by the key attribute value in the wrapped key header, the unwrapped key can be securely stored by the CSP and locked by the new passphrase. If the unwrapping algorithm is NULL 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 NULL 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.


CCHandle (input)

The handle that describes the context of this cryptographic operation.

PassPhrase (input/optional)

The passphrase or a callback function to be used to obtain the passphrase. If the unwrapped key is a private key and the persistent object mode is true, then the private key is unwrapped and securely stored by the CSP. The PassPhrase is used to control access to the private key after it is unwrapped. If a symmetric key is being unwrapped, then this parameter is optional.

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/optional)

A bit mask indicating all permitted uses for the imported key. If no value is specified, the CSP defines the usage mask for the imported key.

KeyAttr (input)

A bit mask defining 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.

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.


A CSSM return value. This function returns CSSM_OK if successful, and returns an error code if an error has occurred.



Invalid context handle.


Context type and operation do not match.


Invalid output CSSM_DATA pointer.


Invalid output CSSM_DATA buffer.


Unknown algorithm.


Unwrap key service not supported.


Cryptographic operation failed.


Specified key attribute is incorrect or unsupported.


Invalid CSSM_KEY or CSSM_WRAP_KEYpointers.


Invalid subject key (key to be unwrapped).


Invalid or missing passphrase (parameter required if the subject key is a private key).


Passphrase callback function failed for subject private key or for private key in the asymmetric context.


Cannot find the corresponding private key for either the subject private key or the private key in the asymmetric context.


Passphrase length error or passphrase badly formed for either the passphrase parameter or passphrase in the asymmetric context.


Error in getting the raw private key or private key storage error for either the subject private key or the private key in the asymmetric context.


Invalid or missing key data in the context attribute.


Key class is not private or public key class for asymmetric context or is not session key class for symmetric context.


The key in the context (key to be used for unwrapping) does not match the operation.


Key header and key data (for the unwrapping key) is inconsistent.


Key usage mask (for the unwrapping key) does not allow unwrap.


Unknown key format (for the unwrapping key).


Key size in bits unsupported (for the unwrapping key).


Unknown padding.


Unknown algorithm mode for symmetric context.


Invalid or missing passphrase attribute in the asymmetric context.


Init vector attribute data or length error for symmetric context.


Specified key attribute is incorrect or unsupported.


The KeyData field of the CSSM_KEY structure is not required to be allocated. In this case the memory required to represent the key is allocated by the CSP. The application is required to free this memory. The CSP will only allocate memory if the Data field of KeyData is NULL and the Length field is zero.



Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.
You should also read the legal notice explaining the terms and conditions relating to the CDSA documentation.

Contents Next section Index