CSSM_CSP_CreateSymmetricContext

NAME

  CSSM_CSP_CreateSymmetricContext - Create a symmetric encryption
                                    cryptographic context (CDSA)

SYNOPSIS

  # include <cssm.h>

       CSSM_RETURN CSSMAPI CSSM_CSP_CreateSymmetricContext
       (CSSM_CSP_HANDLE CSPHandle,
       CSSM_ALGORITHMS AlgorithmID,
       CSSM_ENCRYPT_MODE Mode,
       const CSSM_ACCESS_CREDENTIALS *AccessCred,
       const CSSM_KEY *Key,
       const CSSM_DATA *InitVector,
       CSSM_PADDING Padding,
       void *Reserved,
       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 error.

  AlgorithmID (input)
          The algorithm identification number for symmetric encryption.

  Mode (input)
          The mode of the specified algorithm ID.

  AccessCred (input/optional)
          A pointer to the set of one or more credentials required to
          unlock the private 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. Credentials may be required
          for encryption, decryption, and wrapping operations.

  Key (input)
          The key used for symmetric encryption. The caller passes a
          pointer to a CSSM_KEY structure containing the key.

  InitVector (input/optional)
          The initial vector for symmetric encryption. This is typically
          specified for block ciphers.

  Padding (input/optional)
          The method for padding. This is typically specified for ciphers
          that pad.

  Reserved (input)
          Reserved for future use.

  NewContextHandle (output)
          Cryptographic context handle.

DESCRIPTION

  This function creates a symmetric encryption cryptographic context,
  given a handle of a CSP, an algorithm identification number, a key,
  an initial vector, padding, and the number of encryption rounds.
  Algorithm-specific attributes must be added to the context after the
  initial creation using the CSSM_UpdateContextAttributes() function.
  The cryptographic context handle is returned. The cryptographic
  context handle can be used to call symmetric encryption functions
  and the cryptographic wrap or unwrap functions.

  Additional attributes can be added to the newly created context using
  the CSSM_UpdateContextAttributes() function . Incremental attributes
  of interest when using this context to unwrap a key include a
  handle-pair identifying a Data Storage Library service module and an
  open data store for CSPs that manage multiple, persistent key stores.
  If a CSP does not support multiple key stores, the CSP ignores the
  presence or absence of this attribute.

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_DecryptData
             CSSM_DecryptDataInit
             CSSM_DecryptDataUpdate
             CSSM_DecryptDataFinal
             CSSM_DeleteContext
             CSSM_EncryptData
             CSSM_EncryptDataInit
             CSSM_EncryptDataUpdate
             CSSM_EncryptDataFinal
             CSSM_GetContext
             CSSM_GetContextAttribute
             CSSM_QuerySize
             CSSM_SetContext
             CSSM_UpdateContextAttributes