CL_CrlGetFirstCachedFieldValue(3CL_CrlGetFirstCachedFieldValue(3)

NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

       # include <cdsa/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    [Toc]    [Back]

       Common Security Services Manager library (libcssm.so)

PARAMETERS    [Toc]    [Back]

       The  handle  that describes the add-in Certificate Library
       module used to perform this function.  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.  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.   A  pointer to an object
       identifier that identifies the field value to be extracted
       from the CRL.  A pointer to the CSSM_HANDLE that should be
       used to obtain any additional matching fields.  The  total
       number  of  fields that match the CrlField OID. This count
       includes the first match, which was returned by this function.
   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    [Toc]    [Back]

       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    [Toc]    [Back]

       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    [Toc]    [Back]

       Errors are described in the CDSA technical standard.   See
       CDSA_intro(3).     CSSMERR_CL_INVALID_CACHE_HANDLE    CSSMERR_CL_INVALID_CRL_INDEX
   CSSMERR_CL_UNKNOWN_TAG    CSSMERR_CL_NO_FIELD_VALUES

SEE ALSO    [Toc]    [Back]

       Books

       Intel    CDSA    Application    Developer's   Guide   (see
       CDSA_intro(3))

       Reference Pages    [Toc]    [Back]

       Functions for the CSSM API:

       CSSM_CL_CrlGetNextCachedFieldValue(3),   CSSM_CL_IsCertInCachedCrl(3),    CSSM_CL_CrlAbortQuery(3),    CSSM_CL_CrlCache(3),     CSSM_CL_CrlAbortCache(3),     CSSM_CL_CrlDescribeFormat(3), CSSM_CL_FreeFieldValue(3)

       Functions for the CLI SPI:

       CL_CrlGetNextCachedFieldValue(3), CL_IsCertInCachedCrl(3),
       CL_CrlAbortQuery(3), CL_CrlCache(3),  CL_CrlAbortCache(3),
       CL_CrlDescribeFormat(3), CL_Free