NAME

CSP_DeriveKey

SYNOPSIS

CSSM_RETURN CSSMSPI CSP_DeriveKey
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT_PTR Context,
    const CSSM_KEY_PTR BaseKey,
    CSSM_DATA_PTR Param,
    uint32 KeyUsage,
    uint32 KeyAttr,
    const CSSM_DATA_PTR KeyLabel,
    CSSM_KEY_PTR DerivedKey)

DESCRIPTION

This function derives a new symmetric key using the context and information from the base key.

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.

BaseKey (input)

The base key used to derive the new key. The base key may be a public key, a private key, or a symmetric key.

Param (input/output)

This parameter varies depending on the derivation mechanism. Password based derivation algorithms use this parameter to return a cipher block chaining initialization vector. Concatenation algorithms will use this parameter to get the second item to concatenate.

KeyUsage (input/optional)

A bit mask specifying how the new key can be used.

KeyAttr (input/optional)

A bit mask specifying other attributes to be associated with the new key.

KeyLabel (input/optional)

Pointer to a byte string that will be used as the label for the derived key.

DerivedKey (output)

A pointer to a CSSM_KEY structure that returns the derived key.

RETURN VALUE

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

ERRORS

CSSM_CSP_INVALID_CSP_HANDLE

Invalid CSP handle.

CSSM_CSP_INVALID_CONTEXT_HANDLE

Invalid context handle.

CSSM_CSP_INVALID_CONTEXT_POINTER

Invalid CSSM_CONTEXT pointer.

CSSM_CSP_INVALID_CONTEXT

Context type and operation do not match.

CSSM_CSP_INVALID_ALGORITHM

Unknown algorithm.

CSSM_CSP_INVALID_DATA_POINTER

Invalid input or output CSSM_DATA pointer.

CSSM_CSP_INVALID_DATA

Invalid output CSSM_DATA buffer.

CSSM_CSP_NOT_ENOUGH_BUFFER

The output buffer is not big enough.

CSSM_CSP_INVALID_ALGORITHM

Unknown algorithm.

CSSM_CSP_MEMORY_ERROR

Not enough memory to allocate.

CSSM_CSP_OPERATION_UNSUPPORTED

Derive key service not supported.

CSSM_CSP_OPERATION_FAILED

Cryptographic operation failed.

CSSM_CSP_INVALID_SUBJECT_KEY

Invalid or missing BaseKey.

CSSM_CSP_INVALID_KEYUSAGE_MASK

Specified usage mask for the key being derived is invalid.

CSSM_CSP_KEYUSAGE_MASK_UNSUPPORTED

Requested usage mask for the key being derived is unsupported.

CSSM_CSP_INVALID_KEYATTR_MASK

Specified attribute mask for the key being derived is invalid.

CSSM_CSP_KEYATTR_MASK_UNSUPPORTED

Requested attribute mask for the key being derived is unsupported.

CSSM_CSP_KEY_USAGE_INCORRECT

Usage mask on BaseKey does not allow key derivation.

CSSM_CSP_INVALID_KEY

Invalid buffer specified for the DerivedKey parameter.

CSSM_CSP_NOT_ENOUGH_BUFFER

The output DerivedKey buffer is not big enough.

CSSM_CSP_KEY_ALGID_MISMATCH

The BaseKey does not match the operation.

CSSM_CSP_KEY_KEYHEADER_INCONSISTENT

BaseKey header and BaseKey data is inconsistent.

CSSM_CSP_KEY_FORMAT_INCORRECT

Unknown BaseKey format.

CSSM_CSP_INVALID_ATTR_SEED

Invalid seed attribute in the context if caller provides the seed crypto data structure.

CSSM_CSP_CALLBACK_FAILED

Seed callback function failed if caller provides a seed callback function.

CSSM_CSP_INVALID_ATTR_PASSPHRASE

Invalid or missing passphrase attribute in the asymmetric context.

CSSM_CSP_PASSPHRASE_INVALID

Passphrase length error or passphrase badly formed.

CSSM_CSP_INVALID_ATTR_SALT

Invalid salt attribute if caller provides one.

CSSM_CSP_INVALID_ATTR_INTERATION_COUNT

Invalid iteration count attribute or value.

CSSM_CSP_INVALID_KEY_SIZE_IN_BITS

The key size in bits for BaseKey or DerivedKey is unsupported.