NAME

   CSSM_CSP_CreateDeriveKeyContext - Create a cryptographic context to
                                     derive a symmetric key (CDSA)

 SYNOPSIS

   # include <cssm.h>

        CSSM_RETURN CSSMAPI CSSM_CSP_CreateDeriveKeyContext
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_ALGORITHMS AlgorithmID,
        CSSM_KEY_TYPE DeriveKeyType,
        uint32 DeriveKeyLengthInBits,
        const CSSM_ACCESS_CREDENTIALS *AccessCred,
        const CSSM_KEY *BaseKey,
        uint32 IterationCount,
        const CSSM_DATA *Salt,
        const CSSM_CRYPTO_DATA *Seed,
        CSSM_CC_HANDLE *NewContextHandle)

 LIBRARY

   Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE)

 PARAMETERS

   CSPHandle (input)
           The handle that describes the add-in cryptographic service
           provider module used to perform this function. If a NULL
           handle is specified, CSSM returns an error.

   AlgorithmID (input)
           The algorithm identification number for a derived key
           algorithm.

   DeriveKeyType (input)
           The type of symmetric key to derive.

   DeriveKeyLengthInBits (input)
           The logical length of the key in bits to be derived (
           LogicalKeySizeInBits)

   AccessCred (input/optional)
           A pointer to the set of one or more credentials required to
           access the base key. The credentials structure can contain
           an immediate value for the credential, such as a passphrase,
           or the caller can specify a callback function the CSP can use
           to obtain one or more credentials. If the BaseKey is NULL,
           then this parameter is optional.

   BaseKey (input/optional)
           The base key used to derive the new key. The base key can be
           a public key, a private key, or a symmetric key

   IterationCount (input/optional)
           The number of iterations to be performed during the
           derivation process.  Used heavily by password-based
           derivation methods.

   Salt (input/optional)
           A Salt used in deriving the key.

   Seed (input/optional)
           A seed used to generate a random number. The caller can either
           pass a seed and seed length in bytes or pass a callback
           function. If Seed is NULL, the cryptographic service provider
           will use its default seed-handling mechanism.

   NewContextHandle (output)
           Cryptographic context handle.

 DESCRIPTION

   This function creates a cryptographic context to derive a symmetric
   key, given a handle of a CSP, an algorithm, the type of symmetric key
   to derive, the length of the derived key, and an optional seed or an
   optional AccessCredentials structure from which to derive a new key.
   The cryptographic context handle is returned. The cryptographic
   context handle can be used for calling the cryptographic derive key
   function.

 RETURN VALUE

   A CSSM_RETURN value indicating success or specifying a particular
   error condition. The value CSSM_OK indicates success. All other
   values represent an error condition.

 SEE ALSO

   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions: CSSM_DeriveKey