Common Security: CDSA and CSSM, Version 2
Copyright © 1999 The Open Group

Certificate Library Interface

Overview

The Certificate Library Interface (CLI) specifies the functions that a certificate library may make available to applications via CSSM in order to support certificate and certificate revocation list (CRL) formats. These functions mirror the CSSM API for certificates and certificate revocation lists. They include the basic areas of functionality expected of a certificate library: certificate operations, certificate revocation list operations, extensibility functions, and module management functions. The certificate library developer may choose to implement some or all of these CLI functions. The available functions will be made known to CSSM at attach time when it receives the certificate library's function table. In the function table, any unsupported function will have a NULL function pointer. It is the responsibility of the certificate library module developer to make its certificate format and general functionality known to application developers.

Certificate operations fall into two general areas:

Cryptographic operations
These operations include signing a certificate and verifying the signature on a certificate. It is expected that the certificate library will determine the certificate fields to be signed or verified and will manage the interaction with a cryptographic service provider to perform the signing or verification.
Certificate field management
Fields are added to a certificate when it is created. After the certificate is signed, the fields cannot be modified in any way. However, they can be queried for their values using the CSSM certificate interface. Field values can be retrieve in their encoded representation or in a type-specific parsed format. Certificates and CRLs can be cached by the certificate library module for efficient processing of repeated access requests for field values.

To support new certificate types and new uses of certificates, the sign and verify operations in the Certificate Library Interface support a scope parameter. The scope parameter enables an application to sign a portion of the certificate, namely the fields identified by the scope. This enables future certificate models, which are expected to allow field signing. CL modules that support existing certificate formats, such as X.509 Version 1, which sign and verify a pre-defined portion of the certificate, will ignore this parameter.

The CL module's certificate format is exposed via its fields. These fields will consist of tag/value pairs, where the tag is an object identifier (OID). These OIDs reference specific data types or data structures within the certificate or CRL. OIDs are defined by the certificate library developer at a granularity appropriate for the expected usage of the CL.

Operations on certificate revocation lists comprise cryptographic operations and field management operations on the CRL as a whole, and on individual revocation records. The entire CRL can be signed or verified. This will ensure the integrity of the CRL's contents as it is passed between systems. Individual revocation records may be signed when they are revoked and verified when they are queried, as determined by the CL Module. Certificates may be revoked and unrevoked by adding or removing them from the CRL at any time prior to its being signed. The contents of the CRL can be queried for all of its revocation records, specific certificates, or individual CRL fields.

A pass-through function is included in the Certificate Library Interface to allow certificate libraries to expose additional services beyond what is currently defined in the CSSM API. These services should be syntactic in nature, meaning that they should be dependent on the data format of the certificates and CRLs manipulated by the library. CSSM will pass an operation identifier and input parameters from the application to the appropriate certificate library. Within the CL_PassThrough function in the certificate library, the input parameters will be interpreted and the appropriate operation performed. The certificate library developer is responsible for making known to the application the identity and parameters of the supported pass-through operations.

Data Structures

This section describes the data structures which may be passed to or returned from a Certificate Library function, that are not defined by the CSSM API specification (see Part 2).

These data structures are used by applications to prepare data to be passed as input parameters into CSSM API function calls which will be passed without modification to the appropriate CL. The CL is then responsible for interpreting them and returning the appropriate data structure to the calling application via CSSM.

CSSM_SPI_CL_FUNCS

This structure defines the function table for all the certificate library service functions that a service module can return to CSSM. CSSM uses these function pointers to dispatch corresponding application programming interface functions to the service module for processing.


typedef struct cssm_spi_cl_funcs {
    CSSM_RETURN (CSSMAPI *CertCreateTemplate)
        (CSSM_CL_HANDLE CLHandle,
        uint32 NumberOfFields,
        const CSSM_FIELD *CertFields, 
        CSSM_DATA_PTR CertTemplate);
    CSSM_RETURN (CSSMAPI *CertGetAllTemplateFields)
        (CSSM_CL_HANDLE CLHandle,
        const CSSM_DATA *CertTemplate,
        uint32 *NumberOfFields,
        CSSM_FIELD_PTR *CertFields);
    CSSM_RETURN (CSSMAPI *CertSign)
        (CSSM_CL_HANDLE CLHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *CertTemplate,
        const CSSM_FIELD *SignScope,
        uint32 ScopeSize,
        CSSM_DATA_PTR SignedCert);
    CSSM_RETURN (CSSMAPI *CertVerify)
        (CSSM_CL_HANDLE CLHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *CertToBeVerified,
        const CSSM_DATA *SignerCert,
        const CSSM_FIELD *VerifyScope,
        uint32 ScopeSize); 
    CSSM_RETURN (CSSMAPI *CertVerifyWithKey)
        (CSSM_CL_HANDLE CLHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *CertToBeVerified); 
    CSSM_RETURN (CSSMAPI *CertGetFirstFieldValue)
        (CSSM_CL_HANDLE CLHandle,
        const CSSM_DATA *Cert,
        const CSSM_OID *CertField,
        CSSM_HANDLE_PTR ResultsHandle,
        uint32 *NumberOfMatchedFields,
        CSSM_DATA_PTR *Value);
    CSSM_RETURN (CSSMAPI *CertGetNextFieldValue)
        (CSSM_CL_HANDLE CLHandle,
        CSSM_HANDLE ResultsHandle,
        CSSM_DATA_PTR *Value);
    CSSM_RETURN (CSSMAPI *CertAbortQuery)
        (CSSM_CL_HANDLE CLHandle,
        CSSM_HANDLE ResultsHandle); 
    CSSM_RETURN (CSSMAPI *CertGetKeyInfo)
        (CSSM_CL_HANDLE CLHandle,
        const CSSM_DATA *Cert,
        CSSM_KEY_PTR *Key);
    CSSM_RETURN (CSSMAPI *CertGetAllFields)
        (CSSM_CL_HANDLE CLHandle,
        const CSSM_DATA *Cert,
        uint32 *NumberOfFields,
        CSSM_FIELD_PTR *FieldList);
    CSSM_RETURN (CSSMAPI FreeFields)
        (CSSM_CL_HANDLE CLHandle,
        uint32 NumberOfFields,
        CSSM_FIELD_PTR FieldArray);
    CSSM_RETURN (CSSMAPI *FreeFieldValue)
        (CSSM_CL_HANDLE CLHandle,
        const CSSM_OID *CertOrCrlOid,
        CSSM_DATA_PTR Value);
    CSSM_RETURN (CSSMAPI *CertCache)
        (CSSM_CL_HANDLE CLHandle,
        const CSSM_DATA *Cert, 
        CSSM_HANDLE_PTR CertHandle); 
    CSSM_RETURN (CSSMAPI *CertGetFirstCachedFieldValue)
        (CSSM_CL_HANDLE CLHandle,
        CSSM_HANDLE CertHandle, 
        const CSSM_OID *CertField,
        CSSM_HANDLE_PTR ResultsHandle,
        uint32 *NumberOfMatchedFields,
        CSSM_DATA_PTR *FieldValue); 
    CSSM_RETURN (CSSMAPI *CertGetNextCachedFieldValue)
        (CSSM_CL_HANDLE CLHandle, 
        CSSM_HANDLE ResultsHandle,
        CSSM_DATA_PTR *FieldValue); 
    CSSM_RETURN (CSSMAPI *CertAbortCache)
        (CSSM_CL_HANDLE CLHandle,
        CSSM_HANDLE CertHandle); 
    CSSM_RETURN (CSSMAPI *CertGroupToSignedBundle)
        (CSSM_CL_HANDLE CLHandle, 
        CSSM_CC_HANDLE CCHandle, 
        const CSSM_CERTGROUP *CertGroupToBundle, 
        const CSSM_DATA *SignerCert,
        const CSSM_CERT_BUNDLE_HEADER *BundleInfo,
        CSSM_DATA_PTR SignedBundle);
    CSSM_RETURN (CSSMAPI *CertGroupFromVerifiedBundle)
        (CSSM_CL_HANDLE CLHandle, 
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CERT_BUNDLE *CertBundle, 
        const CSSM_DATA *SignerCert,
        CSSM_CERTGROUP_PTR *CertGroup);
    CSSM_RETURN (CSSMAPI *CertDescribeFormat)
        (CSSM_CL_HANDLE CLHandle,
        uint32 *NumberOfOids,
        CSSM_OID_PTR *OidList);
    CSSM_RETURN (CSSMAPI *CrlCreateTemplate)
        (CSSM_CL_HANDLE CLHandle,
        uint32 NumberOfFields,
        const CSSM_FIELD *CrlTemplate,
        CSSM_DATA_PTR NewCrl);
    CSSM_RETURN (CSSMAPI *CrlSetFields)
        (CSSM_CL_HANDLE CLHandle,
        uint32 NumberOfFields,
        const CSSM_FIELD *CrlTemplate, 
        const CSSM_DATA *OldCrl,
        CSSM_DATA_PTR ModifiedCrl);
    CSSM_RETURN (CSSMAPI *CrlAddCert)
        (CSSM_CL_HANDLE CLHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *Cert,
        uint32 NumberOfFields,
        const CSSM_FIELD *CrlEntryFields,
        const CSSM_DATA *OldCrl,
        CSSM_DATA_PTR NewCrl);
    CSSM_RETURN (CSSMAPI *CrlRemoveCert)
        (CSSM_CL_HANDLE CLHandle,
        const CSSM_DATA *Cert,
        const CSSM_DATA *OldCrl,
        CSSM_DATA_PTR NewCrl);
    CSSM_RETURN (CSSMAPI *CrlSign)
        (CSSM_CL_HANDLE CLHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *UnsignedCrl,
        const CSSM_FIELD *SignScope,
        uint32 ScopeSize,
        CSSM_DATA_PTR SignedCrl);
    CSSM_RETURN (CSSMAPI *CrlVerify)
        (CSSM_CL_HANDLE CLHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *CrlToBeVerified,
        const CSSM_DATA *SignerCert,
        const CSSM_FIELD *VerifyScope,
        uint32 ScopeSize); 
    CSSM_RETURN (CSSMAPI *CrlVerifyWithKey)
        (CSSM_CL_HANDLE CLHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *CrlToBeVerified); 
    CSSM_RETURN (CSSMAPI *IsCertInCrl)
        (CSSM_CL_HANDLE CLHandle,
        const CSSM_DATA *Cert,
        const CSSM_DATA *Crl,
        CSSM_BOOL *CertFound);
    CSSM_RETURN (CSSMAPI *CrlGetFirstFieldValue)
        (CSSM_CL_HANDLE CLHandle,
        const CSSM_DATA *Crl,
        const CSSM_OID *CrlField,
        CSSM_HANDLE_PTR ResultsHandle,
        uint32 *NumberOfMatchedFields,
        CSSM_DATA_PTR *Value);
    CSSM_RETURN (CSSMAPI *CrlGetNextFieldValue)
        (CSSM_CL_HANDLE CLHandle,
        CSSM_HANDLE ResultsHandle,
        CSSM_DATA_PTR *Value); 
    CSSM_RETURN (CSSMAPI *CrlAbortQuery)
        (CSSM_CL_HANDLE CLHandle,
        CSSM_HANDLE ResultsHandle); 
    CSSM_RETURN (CSSMAPI *CrlGetAllFields)
        (CSSM_CL_HANDLE CLHandle,
        const CSSM_DATA *Crl,
        uint32 *NumberOfCrlFields,
        CSSM_FIELD_PTR *CrlFields);
    CSSM_RETURN (CSSMAPI *CrlCache)
        (CSSM_CL_HANDLE CLHandle,
        const CSSM_DATA *Crl, 
        CSSM_HANDLE_PTR CrlHandle); 
    CSSM_RETURN (CSSMAPI *IsCertInCachedCrl)
        (CSSM_CL_HANDLE CLHandle,
        const CSSM_DATA *Cert,
        CSSM_HANDLE CrlHandle,
        CSSM_BOOL *CertFound,
        CSSM_DATA_PTR CrlRecordIndex);
    CSSM_RETURN (CSSMAPI *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); 
    CSSM_RETURN (CSSMAPI *CrlGetNextCachedFieldValue)
        (CSSM_CL_HANDLE CLHandle, 
        CSSM_HANDLE ResultsHandle,
        CSSM_DATA_PTR *FieldValue); 
    CSSM_RETURN (CSSMAPI *CrlGetAllCachedRecordFields)
        (CSSM_CL_HANDLE CLHandle,
        CSSM_HANDLE CrlHandle, 
        const CSSM_DATA *CrlRecordIndex,
        uint32 *NumberOfFields,
        CSSM_FIELD_PTR *Fields); 
    CSSM_RETURN (CSSMAPI *CrlAbortCache)
        (CSSM_CL_HANDLE CLHandle,
        CSSM_HANDLE CrlHandle);
    CSSM_RETURN (CSSMAPI *CrlDescribeFormat)
        (CSSM_CL_HANDLE CLHandle,
        uint32 *NumberOfOids,
        CSSM_OID_PTR *OidList);
    CSSM_RETURN (CSSMAPI *PassThrough)
        (CSSM_CL_HANDLE CLHandle,
        CSSM_CC_HANDLE CCHandle,
        uint32 PassThroughId,
        const void * InputParams,
        void **OutputParams);
} CSSM_SPI_CL_FUNCS, *CSSM_SPI_CL_FUNCS_PTR;

Error Return Codes

Certificate Library service provider modules can return error codes from other service provider modules that are used to implement the Certificate Library services. Based on the security services defined in this specification, a CL could use a Cryptographic Service Provider module or a new, elective security service as part of its implementation. As such, the certificate library can return error codes generated by these other module types. A certificate library implementation can and should document propagated error codes for specific CL operations.

All certificate library service provider modules can return the following common error codes from any certificate library service function. These error codes are not repeated in individual function definitions.

CSSM_ADDIN_AUTHENTICATE_FAILED
CSSM_BAD_MODULE_HANDLE
CSSM_CALLOC_FAILED
CSSM_CANT_CLOSE_OBJECT
CSSM_CANT_CREATE_OBJECT
CSSM_CANT_GET_PROC_ADDR
CSSM_FUNCTION_INTEGRITY_FAIL
CSSM_FUNCTION_NOT_IMPLEMENTED
CSSM_INVALID_ADDIN_HANDLE: An invalid handle is passed to a function
CSSM_INVALID_CONTEXT_HANDLE
CSSM_INVALID_CSP_HANDLE
CSSM_INVALID_HANDLE_USAGE: A handle is used incorrectly in a function
CSSM_INVALID_INPUT
CSSM_INVALID_OBJECT_PTR: An invalid object reference occurred.
CSSM_INVALID_POINTER
CSSM_LOAD_LIBRARY_FAILED
CSSM_LOCK_MUTEX_FAILED
CSSM_LOCK_OBJECT_FAILED: A CSSM object locking failure occurred
CSSM_MALLOC_FAILED
CSSM_MEMORY_ERROR: A CSSM memory failure occurred
CSSM_NOT_INITIALIZED: A function is called without initializing CSSM
CSSM_TRYLOCK_OBJECT_FAILED
CSSM_UNLOCK_MUTEX_FAILED
CSSM_UNLOCK_OBJECT_FAILED

Certificate Operations

This section describes the function prototypes and error codes expected for the certificate functions in the CLI. The functions will be exposed to CSSM via a function table, so the function names may vary at the discretion of the certificate library developer. However, the function parameter list and return type must match the prototypes given in this section in order to be used by applications. The error codes given in this section constitute the generic error codes that are defined by CSSM for use by all certificate libraries in describing common error conditions. A certificate library may also define and return vendor-specific error codes. Applications must consult vendor supplied documentation for the specification and description of any error codes defined outside of this specification.

Previous section.

Click here to return to the publication details.

NAME

CL_CertCreateTemplate

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CertCreateTemplate
    (CSSM_CL_HANDLE CLHandle,
    uint32 NumberOfFields
    const CSSM_FIELD *CertFields,
    CSSM_DATA_PTR CertTemplate)

DESCRIPTION

This function allocates and initializes memory for an encoded certificate template output in CertTemplate->Data. The template values are specified by the input OID/value pairs contained in CertFields. The initialization process includes encoding all certificate field values according to the certificate type and certificate encoding supported by the certificate library module.
The memory for CerTemplate->Data is allocated by the service provider using the calling application's memory management routines. The application must deallocate the memory.

PARAMETERS

CLHandle (input)

The handle that describes the certificate library module used to perform this function.

NumberOfFields (input)

The number of certificate field values specified in the CertFields.

CertFields (input)

A pointer to an array of OID/value pairs that identify the field values to initialize a new certificate.

CertTemplate (output)

A pointer to a CSSM_DATA structure that will contain the unsigned certificate template as a result of this function.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CertGetAllTemplateFields

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CertGetAllTemplateFields
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *CertTemplate,
    uint32 *NumberOfFields,
    CSSM_FIELD_PTR *CertFields)

DESCRIPTION

This function extracts and returns a copy of the values stored in the encoded CertTemplate. The memory for the CertFields output is allocated by the service provider using the calling application's memory management routines. The application must deallocate the memory by calling CSSM_CL_FreeFields().

PARAMETERS

CLHandle (input)

The handle that describes the certificate library module used to perform this function.

CertTemplate (input)

A pointer to the CSSM_DATA structure containing the packed, encoded certificate template.

NumberOfFields (output)

The length of the output array of fields.

CertFields (output)

A pointer to an array of CSSM_FIELD structures which contains the OIDs and values of the fields of the input certificate template.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CertSign

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CertSign
    (CSSM_CL_HANDLE CLHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *CertTemplate,
    const CSSM_FIELD *SignScope,
    uint32 ScopeSize,
    CSSM_DATA_PTR *SignedCert)

DESCRIPTION

This function signs a certificate using the private key and signing algorithm specified in the CCHandle. The result is a signed, encoded certificate in SignedCert. The certificate field values are specified in the input certificate template. The template is constructed using CL_CertCreateTemplate(). The template is in the default format for this CL.
The CCHandle must be a signature context created using the function CSSM_CSP_CreateSignatureContext(). The context must specify the Cryptographic Services Provider module, the signing algorithm, and the signing key that must be used to perform this operation. The context must also provide the passphrase or a callback function to obtain the passphrase required to access and use the private key.
The fields included in the signing operation are identified by the OIDs in the optional SignScope array.
The memory for the SignedCert->Data output is allocated by the service provider using the calling application's memory management routines. The application must deallocate the memory.

PARAMETERS

CLHandle (input)

The handle that describes the certificate library module used to perform this operation.

CCHandle (input)

A signature context defining the CSP, signing algorithm, and private key that must be used to perform the operation. The passphrase for the private key is also provided.

CertTemplate (input)

A pointer to a CSSM_DATA structure containing a certificate template in the default format supported by this CL. The template contains values that are currently contained in or will be contained in a signed certificate.

SignScope (input/optional)

A pointer to the CSSM_FIELD array containing the OID/value pairs of the fields to be signed. A null input signs all the fields provided by CertTemplate

ScopeSize (input)

The number of entries in the SignScope list. If the sign scope is not specified, the input value for scope size must be zero.

SignedCert (output)

A pointer to the CSSM_DATA structure containing the signed certificate.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CertVerify

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CertVerify
    (CSSM_CL_HANDLE CLHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *CertToBeVerified,
    const CSSM_DATA *SignerCert,
    const CSSM_FIELD *VerifyScope,
    uint32 ScopeSize)

DESCRIPTION

This function verifies that the signed certificate has not been altered since it was signed by the designated signer. Only one signature is verified by this function. If the certificate to be verified includes multiple signatures, this function must be applied once for each signature to be verified. This function verifies a digital signature over the certificate fields specified by VerifyScope. If the verification scope fields are not specified, the function performs verification using a pre-selected set of fields in the certificate.
The caller can specify a cryptographic service provider and verification algorithm the CL can use to perform the verification. The handle for the CSP is contained in the cryptographic context identified by CCHandle.
The verification process requires that the caller specifies the necessary verification algorithm parameters. These parameter values are specified in one of two prioritized locations:

As a field value in the SignerCert

As a set of algorithm parameters contained in the cryptographic context identified by CCHandle

The Certificate Library module uses the first set of algorithm parameters encountered in this priority order. If no algorithm parameters are found, the certificate can not be verified and the operation fails.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

CCHandle (input/optional)

The handle that describes the context of this cryptographic operation.

CertToBeVerified (input)

A pointer to the CSSM_DATA structure containing a certificate containing at least one signature for verification. An unsigned certificate template cannot be verified.

SignerCert (input/optional)

A pointer to the CSSM_DATA structure containing the certificate used to sign the subject certificate. This certificate provides the public key to use in the verification process and if the certificate being verified contains multiple signatures, the signer's certificate indicates which signature is to be verified.

VerifyScope (input/optional)

A pointer to the CSSM_FIELD array containing the tag/value pairs of the fields to be used in verifying the signature (that is, the fields that were used to calculate the signature). If the verify scope is null, the certificate library module assumes that its default set of certificate fields were used to calculate the signature and those same fields are used in the verification process.

ScopeSize (input)

The number of entries in the verify scope list. If the verification scope is not specified, the input value for scope size must be zero.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CertVerifyWithKey

SYNOPSIS


CSSM_RETURN CSSMAPI CL_CertVerifyWithKey
    (CSSM_CL_HANDLE CLHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *CertToBeVerified)

DESCRIPTION

This function verifies that the CertToBeVerified was signed using a specific private key and that the certificate has not been altered since it was signed using that private key. The public key corresponding to the private signing key is used in the verification process.
The CCHandle, must be a signature verification context created using the function CSP_CreateSignatureContext(). The context must specify the Cryptographic Services Provider module, the verification algorithm, and the public verification key that must be used to perform this operation.

PARAMETERS

CLHandle (input)

The handle that describes the certificate library service module used to perform this function.

CCHandle (input)

A signature verification context defining the CSP, verification algorithm, and public key that must be used to perform the operation.

CertToBeVerified (input)

A signed certificate whose signature is to be verified.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CertGetFirstFieldValue

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CertGetFirstFieldValue
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Cert,
    const CSSM_OID *CertField,
    CSSM_HANDLE_PTR ResultsHandle,
    uint32 *NumberOfMatchedFields,
    CSSM_DATA_PTR *Value)

DESCRIPTION

This function returns the value of the certificate field designated by the CSSM_OID CertField. The OID also identifies the data format for the field value returned to the caller. If multiple OIDs name the same certificate field, then each such OID defines a distinct data format for the returned field value. The function CL_CertDescribeFormat() provides a list of all CSSM_OID values supported by a certificate library module for naming fields of a certificate.
If more than one field matches the CertField OID, the first matching field will be returned. The number of matching fields is an output parameter, as is the ResultsHandle to be used to retrieve the remaining matching fields.
The set of matching fields is determined by this function. The number of matching fields and the field values do not change between this function and subsequent calls to CL_CertGetNextFieldValue().

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

Cert (input)

A pointer to the CSSM_DATA structure containing the certificate.

CertField (input)

A pointer to an object identifier that identifies the field value to be extracted from the Cert.

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 CertField OID. This count includes the first match, which was returned by this function.

Value (output)

A pointer to the structure containing the value of the requested field. The structure and the field at I "(*Value)->Data" are allocated by the service provider. The CSSM_CL_FreeFieldValue() function can be used to deallocate *Value and (*Value)->Data.

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 the corresponding function call definition in Part 2 of this document.

NAME

CL_CertGetNextFieldValue

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CertGetNextFieldValue
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE ResultsHandle,
    CSSM_DATA_PTR *Value)

DESCRIPTION

This function returns the value of a certificate field, when that field occurs multiple times in a certificate. Certificates with repeated fields (such as multiple signatures) have multiple field values corresponding to a single OID. A call to the function CL_CertGetFirstFieldValue() returns a results handle identifying the size and values contained in the result set. The CL_CertGetNextFieldValue() function can be called repeatedly to obtain these values, one at a time. The result set does not change in size or value between calls to this function.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

ResultsHandle (input)

The handle that identifies the results of a certificate query.

Value (output)

A pointer to the structure containing the value of the requested field. The structure and the field at I "(*Value)->Data" are allocated by the service provider. The CSSM_CL_FreeFieldValue() function can be used to deallocate *Value and (*Value)->Data.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CertAbortQuery

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CertAbortQuery
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE ResultsHandle)

DESCRIPTION

This function terminates a results handle used to access multiple certificate fields identified by a single OID. The ResultsHandle was created and returned by CL_CertGetFirstFieldValue() or by CL_CertGetFirstCachedFieldValue(). The CL releases all intermediate state information associated with the repeating-value query. Once this function has been invoked, the results handle is invalid.
Applications must invoke this function to terminate the ResultsHandle. Using CL_CertGetNextFieldValue() or CL_CertGetNextCachedFieldValue() to access all of the attributes named by a single OID does not terminate the ResultsHandle. This function can be invoked to terminate the results handle without accessing all of the values identified by the single OID.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

ResultsHandle (input)

The handle that identifies the results of a certificate query.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CertGetKeyInfo

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CertGetKeyInfo
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Cert,
    CSSM_KEY_PTR *Key)

DESCRIPTION

This function obtains information about the certificate's public key. Ideally, this information comprises the key fields the application needs to create a cryptographic context that uses this certificate's key.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

Cert (input)

A pointer to the CSSM_DATA structure containing the certificate from which to extract the public key information.

Key (output)

A pointer to the CSSM_KEY structure containing the public key and possibly other key information. The CSSM_KEY structure and its sub-structures are allocated by the service provider and must be deallocated by the application.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_FreeFields

SYNOPSIS


CSSM_RETURN CSSMCLI CL_FreeFields
    (CSSM_CL_HANDLE CLHandle,
    uint32 NumberOfFields,
    CSSM_FIELD_PTR FieldArray)

DEFINITIONS

This function frees the fields in the FieldArray by freeing the data pointers for both the FieldOid and FieldValue fields. It also frees the top level FieldArray pointer. This function should only be used to free CSSM_FIELD_PTR values returned from the following calls:
CSSM_TP_CertGetAllTemplateFields()
CSSM_CL_CertGetAllTemplateFields()
CSSM_CL_CertGetAllFields()
CSSM_CL_CrlGetAllFields()
CSSM_CL_CrlGetAllCachedRecordFields()

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

NumberOfFields (output)

The length of the array of fields in FieldArray.

FieldArray (output)

A pointer to an array of CSSM_FIELD structures that need to be deallocated.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CertGetAllFields

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CertGetAllFields
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Cert,
    uint32 *NumberOfFields,
    CSSM_FIELD_PTR *FieldList)

DESCRIPTION

This function returns a list of the fields in the input certificate, as described by their OID/value pairs.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

Cert (input)

A pointer to the CSSM_DATA structure containing the certificate whose fields will be returned.

NumberOfFields (output)

The length of the output CSSM_FIELD array.

FieldList (output)

A pointer to an array of CSSM_FIELD structures that contain the values of all of the fields of the input certificate. The field list is allocated by the service provider and must be de-allocated by the application by calling CSSM_CL_FreeFields().

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_FreeFieldValue

SYNOPSIS


CSSM_RETURN CSSMCLI CL_FreeFieldValue
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_OID *CertOrCrlOid,
    CSSM_DATA_PTR Value)

DESCRIPTION

This function frees the data specified by Value and Value->Data. CertOrCrlOid indicates the type of the data in Value.
This function should only be used to free CSSM_DATA values returned from calls to:
CL_CertGetFirstFieldValue()
CL_CertGetNextFieldValue()
CL_CertGetFirstCachedFieldValue()
CL_CertGetNextCachedFieldValue()
CL_CrlGetFirstFieldValue()
CL_CrlGetNextFieldValue()
CL_CrlGetFirstCachedFieldValue()
CL_CrlGetNextCachedFieldValue()

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

CertOrCrlField (input)

A pointer to the CSSM_OID structure containing the type of the Value to be freed.

Value (input)

A pointer to the CSSM_DATA structure containing the Data to be freed.

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

See the corresponding function call definition in Part 2 of this document.

Previous section.

NAME

CL_CertCache

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CertCache
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Cert, 
    CSSM_HANDLE_PTR CertHandle)

DESCRIPTION

This function caches a copy of a certificate for subsequent accesses using the functions CL_CertGetFirstCachedFieldValue() and CL_CertGetNextCachedFieldValue.()
The input certificate must be in an encoded representation. The Certificate Library module can cache the certificate in any appropriate internal representation. Parsed or incrementally parsed representations are common. The selected representation is opaque to the caller.
The application must call CL_CertAbortCache() to remove the cached copy when additional get operations will not be performed on the cached certificate.

PARAMETERS

CLHandle (input)

The handle that describes the certificate library module used to perform this function.

Cert (input)

A pointer to the CSSM_DATA structure containing the encoded certificate.

CertHandle (output)

A pointer to the CSSM_HANDLE that should be used in all future references to the cached certificate.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CertGetFirstCachedFieldValue

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CertGetFirstCachedFieldValue
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE CertHandle, 
    const CSSM_OID *CertField,
    CSSM_HANDLE_PTR ResultsHandle,
    uint32 *NumberOfMatchedFields,
    CSSM_DATA_PTR *FieldValue)

DESCRIPTION

This function returns a single structure containing a set of field values from the cached certificate identified by CertHandle. The selected fields are designated by the CSSM_OID CertField 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 certificate field, then each such OID defines a distinct data format for the returned values. The function CL_CertDescribeFormat() provides a list of all CSSM_OID values supported by a certificate library module for naming fields of a certificate.
The CertField OID can identify a single occurrence of a set of certificate fields, or multiple occurrences of a set of certificate fields. If the CertField OID matches more than one occurrence, this function outputs the total number of matches and a ResultsHandle to be used as input to CertGetNextCachedFieldValue() 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 CL_CertGetNextCachedFieldValue().

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

CertHandle (input)

A handle identifying a certificate that the application has temporarily cached with the Certificate Library module. The referenced certificate is searched for the field value named by CertField.

CertField (input)

A pointer to an object identifier that identifies the field value to be extracted from the Cert.

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 CertField 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() function can be used to deallocate *FieldValue and (*FieldValue)->Data.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CertGetNextCachedFieldValue

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CertGetNextCachedFieldValue
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE ResultsHandle,
    CSSM_DATA_PTR *FieldValue)

DESCRIPTION

This function returns the value of a certificate field, when that field occurs multiple times in a certificate. Certificates with repeated fields (such as multiple signatures) have multiple field values corresponding to a single OID. A call to the function CL_CertGetFirstCachedFieldValue() returns a ResultsHandle identifying the size and values contained in the result set. The CSSM_CL_CertGetNextCachedFieldValue() function can be called repeatedly to obtain these values, one at a time. The result set does not change in size or value between calls to this function.

PARAMETERS

CLHandle (input)

The handle that describes the certificate library module used to perform this function.

ResultsHandle (input)

The handle that identifies the results of a certificate query.

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() function can be used to deallocate *FieldValue and (*FieldValue)->Data.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CertAbortCache

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CertAbortCache
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE CertHandle)

DECRIPTION

This function terminates a certificate cache handle created and returned by the function CL_CertCache(). The Certificate Library module releases all cache space and state information associated with the cached certificate.

PARAMETERS

CLHandle (input)

The handle that describes the certificate library module used to perform this function.

CertHandle (input)

The handle that identifies the cached certificate.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CertGroupToSignedBundle

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CertGroupToSignedBundle
    (CSSM_CL_HANDLE CLHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CERTGROUP *CertGroupToBundle,
    const CSSM_DATA *SignerCert,
    const CSSM_CERT_BUNDLE_HEADER *BundleInfo,
    CSSM_DATA_PTR SignedBundle)

DESCRIPTION

This function accepts as input a certificate group (as an array of individual certificates) and returns a certificate bundle (a codified and signed aggregation of the certificates in the group). The certificate group will first be encoded according to the BundleInfo input by the user. If BundleInfo is NULL, the library will perform a default encoding for its default bundle type. If possible, the certificate group ordering will be maintained in this certificate aggregate encoding. After encoding, the certificate aggregate will be signed using the input context and signer certificate. The CL module embeds knowledge of the signing scope for the bundle types it supports. The signature is then associated with the certificate aggregate according to the bundle type and encoding rules and is returned as a bundle to the calling application.

PARAMETERS

CLHandle (input)

The handle of the add-in module to perform this operation.

CCHandle (input/optional)

The handle of the cryptographic context to control the signing operation. The operation will fail if a signature is required for this type of bundle and the cryptographic context is not valid.

CertGroupToBundle (input)

An array of individual, encoded certificates. All of the certificates in this list will be included in the resulting certificate bundle.

SignerCert (input/optional)

If signing is required for this type of certificate bundle, this is the certificate to be used to sign the bundle. If a signing certificate is required but not specified, then the module will assume a default certificate. If a signature is not required for this certificate bundle type, this parameter will be ignored.

BundleInfo (input/optional)

A structure containing the type and encoding of the bundle to be created. If the type and the encoding are not specified, then the module will assume a default bundle type and bundle encoding.

SignedBundle (output)

The function returns a pointer to a signed certificate bundle containing all of the certificates in the certificate group. The bundle is of the type and encoding requested by the caller or is the default type defined by the library module if the BundleInfo was not specified by the caller. The SignedBundle->Data is allocated by the service provider and must be deallocated by the application.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CertGroupFromVerifiedBundle

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CertGroupFromVerifiedBundle
    (CSSM_CL_HANDLE CLHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CERT_BUNDLE  *CertBundle,
    const CSSM_DATA *SignerCert,
    CSSM_CERTGROUP_PTR *CertGroup)

DESCRIPTION

This function accepts as input a certificate bundle (a codified and signed aggregation of the certificates in the group), verifies the signature of the bundle (if a signature is present) and returns a certificate group (as an array of individual certificates) including every certificate contained in the bundle. The signature on the certificate aggregate is verified using the cryptographic context and possibly using the input signer certificate. The CL module embeds the knowledge of the verification scope for the bundle types that it supports. A CL module's supported bundle types and encodings are available to applications by querying the CSSM registry. The type and encoding of the certificate bundle must be specified with the input bundle. If signature verification is successful, the certificate aggregate will be parsed into a certificate group whose order corresponds to the certificate aggregate ordering. This certificate group will then be returned to the calling application.

PARAMETERS

CLHandle (input)

The handle of the add-in module to perform this operation.

CCHandle (input)

The handle of the cryptographic context to control the verification operation.

CertBundle (input)

A structure containing a reference to a signed, encoded bundle of certificates, and to descriptors of the type and encoding of the bundle. The bundled certificates are to be separated into a certificate group (list of individual encoded certificates). If the bundle type and bundle encoding are not specified, the add-in module may either attempt to decode the bundle assuming a default type and encoding or may immediately fail.

SignerCert (input/optional)

The certificate to be used to verify the signature on the certificate bundle. If the bundle is signed but this field is not specified, then the module will assume a default certificate for verification.

CertGroup (output)

A pointer to the certificate group, represented as an array of individual, encoded certificates. The certificate group and CSSM_CERTGROUP sub-structures are allocated by the service provider and must be deallocated by the application. The group contains all of the certificates contained in the certificate bundle.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CertDescribeFormat

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CertDescribeFormat
    (CSSM_CL_HANDLE CLHandle,
    uint32 *NumberOfOids,
    CSSM_OID_PTR *OidList)

DESCRIPTION

This function returns a list of the CSSM_OID values this certificate library module uses to name and reference fields of a certificate. Multiple CSSM_OID values can correspond to a single field. These OIDs can be provided as input to CL_CertGetFirstFieldValue() to retrieve field values from the certificate. The OID also implies the data format of the returned value. When multiple OIDs name the same field of a certificate, those OIDs have a different return data formats associated with them.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

NumberOfOids (output)

The length of the returned array of OIDs.

OidList

A pointer to the array of CSSM_OIDs which represent the supported certificate format. The OID list is allocated by the service provider and must be de-allocated by the application.

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

See the corresponding function call definition in Part 2 of this document.

Certificate Revocation List Operations

This section defines the function prototypes and error codes supported by a Certificate Library module for operations on certificate revocation lists (CRLs). The functions will be exposed to CSSM via a function table, so the function names may vary at the discretion of the certificate library developer. However, the function parameter list and return type must match the prototypes given in this section in order to be used by applications. The error codes given in this section constitute the generic error codes that are defined by CSSM for use by all certificate libraries in describing common error conditions. A certificate library may also define and return vendor-specific error codes. The error codes defined by CSSM are considered to be comprehensive and few if any vendor-specific codes should be required. Applications must consult vendor supplied documentation for the specification and description of any error codes defined outside of this specification. Previous section.

NAME

CL_CrlCreateTemplate

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CrlCreateTemplate
    (CSSM_CL_HANDLE CLHandle
    uint32 NumberOfFields,
    const CSSM_FIELD_PTR *CrlTemplate,
    CSSM_DATA_PTR NewCrl)

DESCRIPTION

This function creates an unsigned, memory-resident CRL. Fields in the CRL are initialized with the descriptive data specified by the OID/value input pairs. The specified OID/value pairs can initialize all or a subset of the general attribute fields in the new CRL, though the module developer may specify a set of fields that must be or cannot be set using this operation. Subsequent values may be set using the CL_CrlSetFields() operation.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

NumberOfFields (input)

The number of OID/value pairs specified in the CrlTemplate input parameter.

CrlTemplate (input)

Any array of field OID/value pairs containing the values to initialize the CRL attribute fields.

NewCrl (output)

A pointer to the CSSM_DATA structure containing the new CRL. The NewCrl->Data is allocated by the service provider and must be deallocated by the application.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CrlSetFields

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CrlSetFields
    (CSSM_CL_HANDLE CLHandle,
    uint32 NumberOfFields,
    const CSSM_FIELD_PTR *CrlTemplate,
    const CSSM_DATA_PTR *OldCrl,
    CSSM_DATA_PTR ModifiedCrl)

DESCRIPTION

This function will set the fields of the input CRL to the new values, specified by the input OID/value pairs. The module developer may specify a set of fields that must be or cannot be set using this operation. This operation is valid only if the CRL has not been closed by the process of signing the CRL (that is, execution of the function CL_CrlSign()). Once the CRL has been signed, fields cannot be changed.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

NumberOfFields (input)

The number of OID/value pairs specified in the CrlTemplate input parameter.

CrlTemplate (input)

Any array of field OID/value pairs containing the values to initialize the CRL attribute fields.

OldCrl (input)

The CRL to be updated with the new attribute values. The CRL must be unsigned and available for update.

ModifiedCrl (output)

A pointer to the modified, unsigned CRL. The ModifiedCrl->Data is allocated by the service provider and must be deallocated by the application.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CrlAddCert

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CrlAddCert
    (CSSM_CL_HANDLE CLHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *Cert,
    uint32 NumberOfFields,
    const CSSM_FIELD *CrlEntryFields,
    const CSSM_DATA *OldCrl,
    CSSM_DATA_PTR NewCrl)

DESCRIPTION

This function revokes the input certificate by adding a record representing the certificate to the CRL. The values for the new entry in the CRL are specified by the a list of OID/value input pairs. The module developer may specify that a certain set of fields must be or cannot be set by use of the list of OID/value pairs. If the CRL format supports the signing of individual records, new CRL entry is signed using the private key and signing algorithm specified in the CCHandle.
The CCHandle must be a context created using the function CSSM_CSP_CreateSignatureContext(). The context must specify the Cryptographic Services Provider module, the signing algorithm, and the signing key that must be used to perform this operation. The context must also provide the passphrase or a callback function to obtain the passphrase required to access and use the private key.
The operation is valid only if the CRL has not been closed by the process of signing the CRL (that is, execution of the function CL_CrlSign()). Once the CRL has been signed, entries cannot be added or removed.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

CCHandle (input/optional)

The handle that describes the context of this cryptographic operation.

Cert (input)

A pointer to the CSSM_DATA structure containing the certificate to be revoked.

NumberOfFields (input)

The number of OID/value pairs specified in the CrlEntryFields input parameter.

CrlEntryFields (input)

An array of OID/value pairs specifying the initial values for descriptive data fields of the new CRL entry.

OldCrl (input)

A pointer to the CSSM_DATA structure containing the CRL to which the newly revoked certificate will be added.

NewCrl (output)

A pointer to the CSSM_DATA structure containing the updated CRL. The NewCrl->Data is allocated by the service provider and must be deallocated by the application.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CrlRemoveCert

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CrlRemoveCert
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA_PTR *Cert,
    const CSSM_DATA_PTR *OldCrl,
    CSSM_DATA_PTR NewCrl)

DESCRIPTION

This function reinstates a certificate by removing it from the specified CRL. The operation is valid only if the CRL has not be closed by the process of signing the CRL (that is, execution of the function CL_CrlSign()). Once the CRL has been signed, entries cannot be added or removed.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

Cert (input)

A pointer to the CSSM_DATA structure containing the certificate to be unrevoked.

OldCrl (input)

A pointer to the CSSM_DATA structure containing the CRL from which the certificate is to be removed.

NewCrl (output)

A pointer to the CSSM_DATA structure containing the updated CRL. The NewCrl->Data is allocated by the service provider and must be deallocated by the application.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CrlSign

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CrlSign
    (CSSM_CL_HANDLE CLHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *UnsignedCrl,
    const CSSM_FIELD *SignScope,
    uint32 ScopeSize,
    CSSM_DATA_PTR SignedCrl)

DESCRIPTION

This function signs a certificate revocation list using the private key and signing algorithm specified in the CCHandle. The result is a signed, encoded certificate revocation list in SignedCrl. The unsigned CRL is specified in the input UnsignedCrl. The UnsignedCrl is constructed using the CSSM_CL_CrlCreateTemplate(), CSSM_CL_CrlSetFields(), CSSM_CL_CrlAddCert(), and CSSM_CL_CrlRemoveCert() functions.
The CCHandle must be a context created using the function CSSM_CSP_CreateSignatureContext(). The context must specify the Cryptographic Services Provider module, the signing algorithm, and the signing key that must be used to perform this operation. The context must also provide the passphrase or a callback function to obtain the passphrase required to access and use the private key.
The fields included in the signing operation are identified by the OIDs in the optional SignScope array.
Once the CRL has been signed it may not be modified. This means that entries cannot be added or removed from the CRL through application of the CL_CrlAddCert() or CL_CrlRemoveCert() operations. A signed CRL can be verified, applied to a data store, and searched for values.
The memory for the SignedCrl->Data output is allocated by the service provider using the calling application's memory management routines. The application must deallocate the memory.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

CCHandle (input)

The handle that describes the context of this cryptographic operation.

UnsignedCrl (input)

A pointer to the CSSM_DATA structure containing the CRL to be signed.

SignScope (input)

A pointer to the CSSM_FIELD array containing the tag/value pairs of the fields to be signed. A null input signs all the fields in the CRL.

ScopeSize (input)

The number of entries in the sign scope list.

SignedCrl (output)

A pointer to the CSSM_DATA structure containing the signed CRL. The SignedCrl->Data is allocated by the service provider and must be deallocated by the application.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CrlVerify

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CrlVerify
    (CSSM_CL_HANDLE CLHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *CrlToBeVerified,
    const CSSM_DATA *SignerCert,
    const CSSM_FIELD *VerifyScope,
    uint32 ScopeSize)

DESCRIPTION

This function verifies that the signed CRL has not been altered since it was signed by the designated signer. It does this by verifying the digital signature over the fields specified by the VerifyScope parameter.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

CCHandle (input)

The handle that describes the context of this cryptographic operation.

CrlToBeVerified (input)

A pointer to the CSSM_DATA structure containing the CRL to be verified.

SignerCert (input)

A pointer to the CSSM_DATA structure containing the certificate used to sign the CRL.

VerifyScope (input)

A pointer to the CSSM_FIELD array containing the tag/value pairs of the fields to be verified. A null input verifies all the fields in the CRL.

ScopeSize (input)

The number of entries in the verify scope list.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CrlVerifyWithKey

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CrlVerifyWithKey
    (CSSM_CL_HANDLE CLHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *CrlToBeVerified)

DESCRIPTION

This function verifies that the CrlToBeVerified was signed using a specific private key and that the certificate revocation list has not been altered since it was signed using that private key. The public key corresponding to the private signing key is used in the verification process.
The cryptographic context indicated by CCHandle must be a signature verification context created using the function CSP_CreateSignatureContext(). The context must specify the Cryptographic Services Provider module, the verification algorithm, and the public verification key that must be used to perform this operation.

PARAMETERS

CLHandle (input)

The handle that describes the certificate library service module used to perform this function.

CCHandle (input)

A signature verification context defining the CSP, verification algorithm, and public key that must be used to perform the operation.

CrlToBeVerified (input)

A signed certificate revocation list whose signature is to be verified.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_IsCertInCrl

SYNOPSIS


CSSM_RETURN CSSMCLI CL_IsCertInCrl
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Cert,
    const CSSM_DATA *Crl,
    CSSM_BOOL *CertFound)

DESCRIPTION

This function searches the CRL for a record corresponding to the certificate. The result of the search is returned in CertFound. The CRL and the records within the CRL must be digitally signed. This function does not verify either signature. The caller should use CSSM_TP_CrlVerify() or CSSM_CL_CrlVerify() before invoking this function. Once the CRL has been verifiedi, the caller can invoke this function repeatedly without repeating the verification process.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

Cert (input)

A pointer to the CSSM_DATA structure containing the certificate to be located.

Crl (input)

A pointer to the CSSM_DATA structure containing the CRL to be searched.

CertFound (output)

A pointer to a CSSM_BOOL indicating success or failure in finding the specified certificate in the CRL. CSSM_TRUE signifies that the certificate was found in the CRL. CSSM_FALSE indicates that the certificate was not found in the CRL.

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

See the corresponding function call definition in Part 2 of this document.

Previous section.

NAME

CL_CrlGetFirstFieldValue

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CrlGetFirstFieldValue
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Crl,
    const CSSM_OID *CrlField,
    CSSM_HANDLE_PTR ResultsHandle,
    uint32 *NumberOfMatchedFields,
    CSSM_DATA_PTR *Value)

DESCRIPTION

This function returns the value of the CRL field designated by the CSSM_OID CrlField. The OID also identifies the data format for the field value returned to the caller. If multiple OIDs name the same CRL field, then each such OID defines a distinct data format for the returned field value. The function CL_CrlDescribeFormat() provides a list of all CSSM_OID values supported by a certificate library module for naming fields of a CRL.
If more than one field matches the CrlField OID, the first matching field will be returned. The number of matching fields is an output parameter, as is the ResultsHandle to be used to retrieve the remaining matching fields.
The set of matching fields is determined by this function. The number of matching fields and the field values do not change between this function and subsequent calls to CL_CrlGetNextFieldValue().

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

Crl (input)

A pointer to the CSSM_DATA structure that contains the CRL from which the field is to be retrieved.

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, which 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.

Value (output)

A pointer to the structure containing the value of the requested field. The structure and the field at I "(*Value)->Data" are allocated by the service provider. The CSSM_CL_FreeFieldValue() function can be used to deallocate *Value and (*Value)->Data.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CrlGetNextFieldValue

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CrlGetNextFieldValue
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE ResultsHandle,
    CSSM_DATA_PTR *Value)

DESCRIPTION

This function returns the value of a CRL field, when that field occurs multiple times in a CRL. CRLs with repeated fields (such as revocation records) have multiple field values corresponding to a single OID. A call to the function CL_CrlGetFirstFieldValue() initiates the process and returns a results handle identifying the size and values contained in the result set. The CL_CrlGetNextFieldValue() function can be called repeatedly to obtain these values, one at a time. The result set does not change in size or value between calls to this function.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

ResultsHandle (input)

The handle that identifies the results of a CRL query.

Value (output)

A pointer to the structure containing the value of the requested field. The structure and the field at I "(*Value)->Data" are allocated by the service provider. The CSSM_CL_FreeFieldValue() function can be used to deallocate *Value and (*Value)->Data.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CrlAbortQuery

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CrlAbortQuery
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE ResultsHandle)

DESCRIPTION

This function terminates the query initiated by CL_CrlGetFirstFieldValue() or CL_CrlGetFirstCachedFieldValue() and allows the CL to release all intermediate state information associated with the repeating-value get operation. Once this function has been invoked, the results handle is invalid.
Applications must invoke this function to terminate the ResultsHandle. Using CL_CrlGetNextFieldValue() or CL_CrlGetNextCachedFieldValue() to access all of the attributes named by a single OID does not terminate the ResultsHandle. This function can be invoked to terminate the results handle without accessing all of the values identified by the single OID.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

ResultsHandle (input)

The handle that identifies the results of a CRL query.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CrlGetAllFields

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CrlGetAllFields
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Crl,
    uint32 *NumberOfCrlFields,
    CSSM_FIELD_PTR *CrlFields)

DESCRIPTION

This function returns one or more structures each containing a set of field values from the encoded, packed CRL contained in Crl. Each structure is returned in the FieldValue entry of the CSSM_FIELD structure CrlFields.. The parameter NumberOfCrlFields indicates the number of returned structures.
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 CL_CrlAddCert().

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

Crl (input)

A pointer to the CSSM_DATA structure that contains the encoded, packed, CRL from which field values are to be extracted.

NumberOfCrlFields (output)

The number of entries in the array CrlFields.

CrlFields (output)

A pointer to an array of OID-value pairs that describe the contents of the CRL. The extracted CRL fields are returned as the value portion of each OID-value pair. The field list is allocated by the service provider and must be deallocated by the application by calling CSSM_CL_FreeFields().

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

See the corresponding function call definition in Part 2 of this document.

Previous section.

NAME

CL_CrlCache

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CrlCache
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Crl,
    CSSM_HANDLE_PTR CrlHandle)

DESCRIPTION

This function caches a copy of a CertificateRevocationList (CRL) for subsequent accesses using the functions CL_CrlGetFirstFieldValue() and CL_CrlGetNextFieldValue().
The input CRL must be in an encoded representation. The Certificate Library module can cache the CRL in any appropriate internal represent. Parsed or incrementally parsed representations are common. The selected representation is opaque to the caller.
The application must call CL_CrlCacheAbort() to remove the cached copy when additional get operations will not be performed on the cached CRL.

PARAMETERS

CLHandle (input)

The handle that describes the certificate library module used to perform this function.

Crl (input)

A pointer to the CSSM_DATA structure containing the encoded CRL.

CrlHandle (output)

A pointer to the CSSM_HANDLE that should be used in all future references to the cached CRL.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_IsCertInCachedCrl

SYNOPSIS


CSSM_RETURN CSSMCLI CL_IsCertInCachedCrl
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Cert,
    CSSM_HANDLE CrlHandle,
    CSSM_BOOL *CertFound,
    CSSM_DATA_PTR CrlRecordIndex)

DESCRIPTION

This function searches the cached CRL for a record corresponding to the certificate. The result of the search is returned in CertFound. The CRL and the records within the CRL must be digitally signed. This function does not verify either signature. The caller should use TP_CrlVerify() or CL_CrlVerify() before invoking this function. Once the CRL has been verified, the caller can invoke this function repeatedly without repeating the verification process.
If the certificate is found in the CRL, the CL module returns an index descriptor CrlRecordIndex for use with other Certificate Library CRL functions. The index provides more direct access to the selected CRL record.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

Cert (input)

A pointer to the CSSM_DATA structure containing an encoded, packed certificate.

CrlHandle (input)

A handle identifying a CRL that the application has temporarily cached with the Certificate Library module. The referenced CRL is searched for a revocation record matching the specified Cert.

CertFound (output)

A pointer to a CSSM_BOOL indicating success or failure in finding the specified certificate in the CRL. CSSM_TRUE signifies that the certificate was found in the CRL. CSSM_FALSE indicates that the certificate was not found in the CRL.

CrlRecordIndex (output/optional)

A pointer to a CSSM_DATA structure containing an index descriptor for direct access to the located CRL record. CrlRecordIndex->Data is allocated by the service provider and must be deallocated by the application.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CrlGetFirstCachedFieldValue

SYNOPSIS


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,
    const CSSM_DATA_PTR *FieldValue)

DESCRIPTION

This function returns a single structure containing a set of field values from the cached CRL identified by CrlHandle.TheselectedfieldsaredesignatedbytheCSSM_OID CrlField 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 CL_CrlDescribeFormat() 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, which is returned by the function CL_IsCertInCachedCrl(). 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 may be digitally signed when it is added to the CRL using the function CL_CrlAddCert(). 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() 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 CL_CrlGetNextFieldValue.()

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 pre-selected 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, which 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() function can be used to deallocate *FieldValue and (*FieldValue)->Data.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CrlGetNextCachedFieldValue

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CrlGetNextCachedFieldValue
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE ResultsHandle,
    const CSSM_DATA_PTR *FieldValue)

DESCRIPTION

This function returns the value of a CRL field, when that field occurs multiple times in a CRL. CRLs with repeated fields (such as revocation records) have multiple field values corresponding to a single OID. A call to the function CL_CrlGetFirstCachedFieldValue() initiates the process and returns a ResultsHandle identifying the size and values contained in the result set. The CL_CrlGetNextCachedFieldValue() function can be called repeatedly to obtain these values, one at a time. The result set does not change in size or value between calls to this function.
The results set selected by CL_CrlGetFirstCachedFieldValue() and identified by ResultsHandle can reference CRL fields repeated across multiple revocation records or within one revocation record. The scope of the scan was set by an optional CrlRecordIndex input to the function CL_CrlGetFirstCachedFieldValue(). If the record index was specified, then the results set is to the revocation record identified by the index. If no record index was specified, then the results set can include repeated fields from multiple revocation records in a CRL.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

ResultsHandle (input)

The handle that identifies the results of a CRL query.

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() function can be used to deallocate *FieldValue and (*FieldValue)->Data.

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CrlGetAllCachedRecordFields

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CrlGetAllCachedRecordFields
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE CrlHandle,
    Const CSSM_DATA_PTR *CrlRecordIndex,
    uint32 *NumberOfFields,
    CSSM_FIELD_PTR *Fields)

DESCRIPTION

This function returns all field values from a pre-located, cached CRL record. The scanned CRL record is identified by CrlRecordIndex, which is returned by the function CL_IsCertInCachedCrl().
Fields are returned as a set of OID-value pairs. The OID identifies the CRL record field and the data format of the value extracted from that field. The Certificate Library module defines and uses a preferred data format for returning field values in this function.
Each CRL record may be digitally signed when it is added to the CRL using the function CL_CrlAddCert(). This function does not perform any signature verification on the CRL record.

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 must contain the CRL record identified by CrlRecordIndex.

CrlRecordIndex (input)

An index value identifying a particular revocation record in a cached CRL.

NumberOfFields (output)

The number of OID-value pairs returned by this function.

Fields (output)

A pointer to an array of CSSM_FIELD structures, describing the contents of the pre-selected CRL record using OID-value pairs. The field list is allocated by the service provider and must be deallocated by the application by calling CSSM_CL_FreeFields().

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

See the corresponding function call definition in Part 2 of this document.

NAME

CL_CrlAbortCache

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CrlAbortCache
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE CrlHandle)

DESCRIPTION

This function terminates a CRL cache handle created and returned by the function CSSM_CL_CrlCache(). The Certificate Library module releases all cache space and state information associated with the cached CRL.

PARAMETERS

CLHandle (input)

The handle that describes the certificate library module used to perform this function.

CrlHandle (input)

The handle that identifies the cached CRL.

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

See the corresponding function call definition in Part 2 of this document.

Previous section.

NAME

CL_CrlDescribeFormat

SYNOPSIS


CSSM_RETURN CSSMCLI CL_CrlDescribeFormat
    (CSSM_CL_HANDLE CLHandle,
    uint32 *NumberOfOids,
    CSSM_OID_PTR *OidList)

DESCRIPTION

This function returns a list of the CSSM_OID values this certificate library module uses to name and reference fields of a CRL. Multiple CSSM_OID values can correspond to a single field. These OIDs can be provided as input to CL_CrlGetFirstFieldValue() to retrieve field values from the CRL. The OID also implies the data format of the returned value. When multiple OIDs name the same field of a CRL, those OIDs have a different return data formats associated with them.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

NumberOfOids (output)

The length of the output array.

OidList (output)

A pointer to the array of CSSM_OIDs which represent the supported CRL format. The OID list is allocated by the service provider and must be de-allocated by the application.

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

See the corresponding function call definition in Part 2 of this document.

Extensibility Functions

The CL_PassThrough() function is provided to allow CL developers to extend the certificate and CRL format-specific functionality of the CSSM API. Because it is only exposed to CSSM as a function pointer, its name internal to the certificate library can be assigned at the discretion of the CL module developer. However, its parameter list and return value must match what is shown below. The error codes given in this section constitute the generic error codes, which may be used by all certificate libraries to describe common error conditions. Certificate library developers may also define their own module-specific error codes. Previous section.

NAME

CL_PassThrough

SYNOPSIS


CSSM_RETURN CSSMCLI CL_PassThrough
    (CSSM_CL_HANDLE CLHandle,
    CSSM_CC_HANDLE CCHandle,
    uint32 PassThroughId,
    const void *InputParams,
    void **OutputParams)

DESCRIPTION

This function allows applications to call certificate library module-specific operations. Such operations may include queries or services that are specific to the domain represented by the CL module.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

CCHandle (input/optional)

The handle that describes the context of the cryptographic operation.

PassThroughId (input)

An identifier assigned by the CL module to indicate the function to perform.

InputParams (input/optional)

A pointer to a module implementation-specific structure containing parameters to be interpreted in a function-specific manner by the requested CL module.

OutputParams (output/optional)

A pointer to a module, implementation-specific structure containing the output data. The service provider allocates the memory for the structure and sub-structures. The application should free the memory for the structure and sub-structures.

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

See the corresponding function call definition in Part 2 of this document.

Contents

Next section

Index

Certificate Library Interface

Overview

Data Structures

CSSM_SPI_CL_FUNCS

Error Return Codes

Certificate Operations

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

SEE ALSO

NAME

SYNOPSIS

DEFINITIONS

PARAMETERS

RETURN VALUE

ERRORS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE