CSSM_DL_DataGetFirst

Description

This function retrieves the first record in the key ring (data store) that matches the given selection criteria. Information is only returned for certificates that have been marked as trusted by RACF. If the certificate has not been marked as trusted, it is not returned to the application; that is, it is as if the certificate is not connected to the key ring.

The selection criteria is specified in the Query structure, which has specific characteristics when used with the OCEP Data Storage Library service provider module. The function returns a unique record identifier that is associated with the retrieved record. This identifier can then be used in other references to the retrieved data record. For example, it can be specified on calls to CSSM_DL_FreeUniqueRecord.

Note:

The calling application is responsible for freeing the storage that is acquired for the returned Data (including its sub-pieces CertData and PvtKeyData) and Attributes parameters. Also, the storage that was acquired for the CSSM_DB_UNIQUE_RECORD must be freed by calling CSSM_DL_FreeUniqueRecord. In addition, the storage that was acquired for the results handle must be freed by calling CSSM_DL_AbortQuery.
Because the private key data returned could be either an ICSF token label or a non-ICSF key, the application must attach the appropriate Cryptographic Service Provider (CSP) as identified by the CspId field in the CSSM_KEYHEADER.

Format

CSSM_DB_UNIQUE_RECORD_PTR CSSMAPI CSSM_DL_DataGetFirst
     (CSSM_DL_DB_HANDLE DLDBHandle,
      const CSSM_QUERY_PTR Query,
      CSSM_HANDLE_PTR 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.

Query (input)

specifies the information that will be used to query the specified key ring; this is a required value and it must have the following structure:

RecordType

must be set to CSSM_DL_DB_RECORD_CERT.

Conjuntive

must be set to CSSM_DB_NONE.

NumSelectionPredicates

must be either 0 or 1. If set to 1, then SelectionPredicates must point to a CSSM_SELECTION_PREDICATE structure, which has the following format:

DbOperator

must be set to CSSM_DB_EQUAL

Attribute

one of the queriable attributes, coded as follows:

Info.AttributeNameFormat, which must be set to CSSM_DB_ATTRIBUTE_NAME_AS_NUMBER
Info.Label.AttributeNumber, which must be one the following vales:
- CSSM_DL_ATTRIBUTE_LABEL = 0x3 - Query on label
- OCEP_DL_ATTRIBUTE_DEFAULT = 0x4 - Query on default flag (this constant is defined in the ibmocepdl.h header file)
- CSSM_DL_ATTRIBUTE_SUBJECT = 0x101 - Query on DER-encoded subject's name

ResultsHandle (output)

contains the key ring handle, which should be saved and used to retrieve subsequent records that satisfied this query.

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 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 structures will be coded as the Query attribute, as described above. 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