NAME

CSP_GenerateKeyPair

SYNOPSIS

CSSM_RETURN CSSMSPI CSP_GenerateKeyPair
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT_PTR Context,
    uint32 PublicKeyUsage,
    uint32 PublicKeyAttr,
    const CSSM_DATA_PTR PublicKeyLabel,
    CSSM_KEY_PTR PublicKey,
    uint32 PrivateKeyUsage,
    uint32 PrivateKeyAttr,
    const CSSM_DATA_PTR PrivateKeyLabel,
    CSSM_KEY_PTR PrivateKey)

DESCRIPTION

This function generates an asymmetric key pair. The CSP may cache keying material associated with the new asymmetric keypair. When one or both of the keys are no longer in active use, the application can invoke the CSSM_FreeKey interface to allow cached keying material associated with the key to be removed.

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 used to link to the CSP-managed information.

Context (input)

Pointer to CSSM_CONTEXT structure that describes the attributes with this context. .

PublicKeyUsage (input/optional)

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

PublicKeyAttr (input/optional)

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

PublicKeyLabel (input)

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

PublicKey (output)

Pointer to CSSM_KEY structure used to obtain the public key. Upon function invocation, any values in the CSSM_Key structure should be ignored. All input values should be supplied in the cryptographic context, PublicKeyUsage, PublicKeyAttr, and PublicKeyLabel input parameters.

PrivateKeyUsage (input/optional)

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

PrivateKeyAttr (input/optional)

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

PrivateKeyLabel (input)

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

PrivateKey (output)

Pointer to CSSM_KEY structure used to obtain the private key. Upon function invocation, any values in the CSSM_Key structure should be ignored. All input values should be supplied in the cryptographic context, PublicKeyUsage, PublicKeyAttr, and PublicKeyLabel 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_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_DATA_POINTER

Invalid CSSM_DATA pointer for PublicKeyLabel or PrivateKeyLabel.

CSSM_CSP_INVALID_DATA

Invalid CSSM_DATA buffer for PublicKeyLabel or PrivateKeyLabel.

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 pair service not supported.

CSSM_CSP_OPERATION_FAILED

Cryptographic operation failed.

CSSM_CSP_INVALID_ATTR_PASSPHRASE

Invalid or missing passphrase attribute in the context.

CSSM_CSP_CALLBACK_FAILED

Passphrase callback function 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_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 attribute if caller provides one.

Comments

The output can be obtained either by filling the caller-supplied buffer or using the application's memory allocation functions to allocate space; application has to free the memory in this case. If the output buffer pointer is NULL, an error code CSSM_CSP_INVALID_DATA_POINTER is returned.

SEE ALSO

CSP_GenerateRandom, CSP_GenerateKey