CL_CrlGetFirstCachedFieldValue

NAME

  CL_CrlGetFirstCachedFieldValue,
  CSSM_CL_CrlGetFirstCachedFieldValue - Get field values from the cached
                                        CRL (CDSA)

SYNOPSIS

  # include <cssm.h>

   API:
       CSSM_RETURN CSSMAPI CSSM_CL_CrlGetFirstCachedFieldValue
       (CSSM_CL_HANDLE CLHandle,
       CSSM_HANDLE CrlHandle,
       const CSSM_DATA *CrlRecordIndex,
       const CSSM_OID *CrlField,
       CSSM_HANDLE_PTR ResultsHandle,
       uint32 *NumberOfMatchedFields,
       CSSM_DATA_PTR *FieldValue)

   SPI:
       CSSM_RETURN CSSMCLI CL_CrlGetFirstCachedFieldValue
       (CSSM_CL_HANDLE CLHandle,
       CSSM_HANDLE CrlHandle,
       const CSSM_DATA *CrlRecordIndex,
       const CSSM_OID *CrlField,
       CSSM_HANDLE_PTR ResultsHandle,
       uint32 *NumberOfMatchedFields,
       CSSM_DATA_PTR *FieldValue)

LIBRARY

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

PARAMETERS

  CLHandle (input)
          The handle that describes the add-in Certificate Library module
          used to perform this function.

  CrlHandle (input)
          A handle identifying a CRL that the application has temporarily
          cached with the Certificate Library module. The referenced CRL
          is searched for the field values identified by CrlField.

  CrlRecordIndex (input/optional)
          An index value identifying a particular revocation record in
          a cached CRL. If an index value is supplied, the scan for the
          field values identified by CrlField is limited to the
          preselected revocation record.

  CrlField (input)
          A pointer to an object identifier that identifies the field
          value to be extracted from the CRL.

  ResultsHandle (output)
          A pointer to the CSSM_HANDLE that should be used to obtain any
          additional matching fields.

  NumberOfMatchedFields (output)
          The total number of fields that match the CrlField OID. This
          count includes the first match, which was returned by this
          function.

  FieldValue (output)
          A pointer to the structure containing the value of the
          requested field. The structure and the field at I
          "(*FieldValue)->Data" are allocated by the service provider.
          The CSSM_CL_FreeFieldValue() (CSSM API), or CL_FreeFieldValue()
          (CL SPI), function can be used to deallocate *FieldValue and
          (*FieldValue)->Data.

DESCRIPTION

  This function returns a single structure containing a set of field
  values from the cached CRL identified by CrlHandle parameter.  The
  selected fields are designated by the CSSM_OID CrlField parameter and
  returned in the output parameter FieldValue.  The OID also identifies
  the data format of the values returned to the caller.  If multiple
  OIDs designate the same CRL field, then each such OID defines a
  distinct data format for the returned values. The function
  CSSM_CL_CrlDescribeFormat() (CSSM API), or CL_CrlDescribeFormat()
  (CL SPI), provides a list of all CSSM_OID values supported by a CL
  module for naming fields of a CRL.

  The search can be limited to a particular revocation record within the
  CRL.  A single record is identified by the CrlRecordIndex parameter,
  which is returned by the function CSSM_CL_IsCertInCachedCrl()
  (CSSM API), or CL_IsCertInCachedCrl() (CL SPI).  If no record index
  is supplied, the search is initiated from the beginning of the CRL.

  The CRL can be signed or unsigned. This function does not perform any
  signature verification on the CRL fields or the CRL records. Each CRL
  record can be digitally signed when it is added to the CRL using the
  function CSSM_CL_CrlAddCert() (CSSM API), or CL_CrlAddCert() (CL SPI).
  The caller can examine fields in the CRL and CRL records at any time
  using this function.

  The CrlField OID can identify a single occurrence of a set of CRL fields
  or multiple occurrences of a set of CRL fields. If the CrlField OID
  matches more than one occurrence, this function outputs the total number
  of matches and a ResultsHandle to be used as input to
  CSSM_CrlGetNextFieldValue() (CSSM API), or CrlGetNextFieldValue()
  (CL SPI), to retrieve the remaining matches. The first match is returned
  as the return value of this function.

  This function determines the complete set of matches. The number of
  matches and the selected field values do not change between this
  function and subsequent calls to CSSM_CL_CrlGetNextFieldValue()
  (CSSM API), or CL_CrlGetNextFieldValue() (CL SPI).

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.

ERRORS

  Errors are described in the CDSA technical standard.  See CDSA.

       CSSMERR_CL_INVALID_CACHE_HANDLE
       CSSMERR_CL_INVALID_CRL_INDEX
       CSSMERR_CL_UNKNOWN_TAG
       CSSMERR_CL_NO_FIELD_VALUES

SEE ALSO

  Books

  Intel CDSA Application Developer's Guide (see CDSA)

  Other Help Topics

  Functions for the CSSM API:

      CSSM_CL_CrlGetNextCachedFieldValue
      CSSM_CL_IsCertInCachedCrl
      CSSM_CL_CrlAbortQuery
      CSSM_CL_CrlCache
      CSSM_CL_CrlAbortCache
      CSSM_CL_CrlDescribeFormat
      CSSM_CL_FreeFieldValue

  Functions for the CLI SPI:

      CL_CrlGetNextCachedFieldValue
      CL_IsCertInCachedCrl
      CL_CrlAbortQuery
      CL_CrlCache
      CL_CrlAbortCache
      CL_CrlDescribeFormat
      CL_FreeFieldValue