CSSM_DL_DataGetNext

Description

This function retrieves the next data record in the key ring that matches the selection criteria (specified by the CSSM_DL_DataGetFirst function). Information is only returned for certificates that have been marked as trusted by RACF; if the certificate has not been marked as trusted, it will not be returned to the calling application.

Format

CSSM_DB_UNIQUE_RECORD_PTR CSSMAPI CSSM_DL_DataGetNext
     (CSSM_DL_DB_HANDLE DLDBHandle,
      CSSM_HANDLE ResultsHandle,
      CSSM_BOOL *EndOfDataStore,
      CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
      CSSM_DATA_PTR Data)

Parameters

DLDBHandle (input)
specifies the RACF key ring handle; this is a required value.
ResultsHandle (input)
this is the handle that is returned by the CSSM_DL_DataGetFirst function.
EndOfDataStore (output)
one of the following flags, which indicates if a record that satisfied this query was available to be retrieved in the current operation:
CSSM_FALSE
a record was available and was retrieved, unless an error condition occurred.
CSSM_TRUE
all records satisfying the query have been previously retrieved and no record has been returned by this operation.
Attributes (output)
contains the attribute values of the retrieved record. This structure has the following format:
SemanticInformation
a structure defined by CSSM_DB_CERTRECORD_SEMANTICS; the following flags are supported:
  • CSSM_DB_CERT_USE_TRUSTED, which indicates this is a Certificate Authority certificate.
  • CSSM_DB_CERT_USE_OWNER, which indicates this is a User/Server certificate, with a possible private key.
If neither bit is set, a SITE certificate is indicated. A SITE certificate is one that the RACF administrator has explicitly defined and added as a trusted certificate.
NumberOfAttributes
indicates the number of CSSM_DB_ATTRIBUTE_DATA structures that are pointed to by Attributes. Each of these structure will be coded as the Query attribute (as described in CSSM_DL_DataGetFirst). In addition, the following non-queriable attribute will also be present:
  • CSSM_DL_ATTRIBUTE_ID = 0x101 - The RACF user ID that is associated with this certificate profile.
Data (output)
is a pointer to a CSSM_DATA structure that contains the nonattribute record data; for RACF, this is the certificate and an optional private key. Data->Data will point to the following structure:
typedef struct ocep_cert_key_record {
 CSSM_DATA CertData;    //DER encoded certificate
 CSSM_KEY PrvtKeyData;  //Optional Private key,
                        //KeyData.Length=KeyData.Data=NULL if not present
} OCEP_CERT_KEY_RECORD, *OCEP_CERT_KEY_RECORD_PTR