NAME

CSSM_GenerateKey

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_GenerateKey
    (CSSM_CC_HANDLE CCHandle,
    uint32 KeyUsage,
    uint32 KeyAttr,
    const CSSM_DATA_PTR KeyLabel,
    CSSM_KEY_PTR Key)

DESCRIPTION

This function generates a symmetric key. The CSP may cache keying material associated with the new symmetric key. When the symmetric key is no longer in active use, the application can invoke the CSSM_FreeKey interface to allow cached keying material associated with the symmetric key to be removed.

PARAMETERS

CCHandle (input)

The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.

KeyUsage (input)

A bit mask indicating all permitted uses for the new key.

KeyAttr (input)

A bit mask defining attribute values for the new key.

KeyLabel (input)

A key label value to be associated with the new key.

Key (output)

Pointer to CSSM_KEY structure used to hold the new key. The CSSM_KEY structure should be empty upon input to this function. The CSP will ignore any values residing in this structure at function invocation. Input values should be supplied in the cryptographic context, KeyUsage, KeyAttr, and KeyLabel input parameters.

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_MANIFEST_ATTRIBUTES_NOT_FOUND

No capability attribute found in the manifest.

CSSM_CONTEXT_FILTER_FAILED

Requested context was not in the manifest capability attribute.

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_DATA_POINTER

Invalid CSSM_DATA pointer for KeyLabel.

CSSM_CSP_INVALID_DATA

Invalid CSSM_DATA buffer for KeyLabel.

CSSM_CSP_INVALID_KEY_POINTER

Invalid or missing CSSM_KEY pointer.

CSSM_CSP_INVALID_KEY

Invalid CSSM_KEY buffer.

CSSM_CSP_NOT_ENOUGH_BUFFER

The output key buffer is not big enough.

CSSM_CSP_INVALID_ALGORITHM

Unknown algorithm.

CSSM_CSP_MEMORY_ERROR

Not enough memory to allocate.

CSSM_CSP_OPERATION_UNSUPPORTED

Generate key service not supported.

CSSM_CSP_OPERATION_FAILED

Cryptographic operation failed.

CSSM_CSP_INVALID_KEYUSAGE_MASK

Specified key usage mask is invalid.

CSSM_CSP_KEYUSAGE_MASK_UNSUPPORTED

Requested key usage mask unsupported.

CSSM_CSP_INVALID_KEYATTR_MASK

Specified key attribute mask is invalid.

CSSM_CSP_KEYATTR_MASK_UNSUPPORTED

Requested key attribute mask unsupported.

CSSM_CSP_INVALID_KEY_SIZE_IN_BITS

Key size in bits unsupported.

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_SALT

Invalid salt attribute if caller provides one.

CSSM_CSP_INVALID_ATTR_ALG_PARAMS

Invalid param attribute if caller provides one.

CSSM_CSP_INVALID_ATTR_START_DATE

Invalid start date attribute if caller provides one.

CSSM_CSP_INVALID_ATTR_END_DATE

Invalid end date if caller provides one.

Comments

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.

SEE ALSO

CSSM_GenerateRandom, CSSM_GenerateKeyPair