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

Certificate Library Services API

Overview

The primary purpose of a Certificate Library (CL) module is to perform syntactic manipulations on a specific certificate format, and its associated certificate revocation list (CRL) format. These manipulations include:

Verifying the signatures on certificates and CRLs
Extracting field values from certificates and CRLs
Searching CRLs for specified certificates

Certificate libraries manipulate memory-based objects only. The persistence of certificates, CRLs, and other security-related objects is an independent property of these objects. It is the responsibility of the application and/or the trust policy module to use data storage modules to make objects persistent (if appropriate). The particular storage mechanism used by a data storage module can often be selected, independent of the trust policy and the application.

Application and Certificate Library Interaction

An application determines the availability and basic capabilities of a Certificate Library by querying the Module Directory Services (MDS) records describing the CL module. When a new CL is installed on a system, the certificate types and certificate fields that it supports are registered with MDS. An application uses registry information to find an appropriate CL and to request that CSSM attach to the CL. When CSSM attaches to the CL, it returns a CL handle to the application which uniquely identifies the pairing of the application thread to the CL module instance. This handle is used by the application to identify the CL in future function calls.

CSSM passes CL function calls from an application to the application-selected Certificate Library.

The application is responsible for the allocation and de-allocation of all memory which is passed into or out of the Certificate Library module. The application must register memory allocation and de-allocation upcalls with CSSM when it attaches any add-in service module. These upcalls and the handle identifying the application and module pairing are passed to the CL module at that time. The Certificate Library Module uses these functions to allocate and de-allocate memory which belongs to or will belong to the application.

Operations on Certificates

CSSM defines the general security API that all certificate libraries should provide to manipulate certificates and certificate revocation lists. The basic areas of functionality include:

Certificate operations
Certificate revocation list operations
Extensibility functions

Each certificate library may implement some or all of these functions. The available functions are registered with CSSM when the module is attached. Each certificate library should be accompanied with documentation specifying supported functions, non-supported functions, and module-specific passthrough functions. It is the responsibility of the application developer to obtain and use this information when developing applications using a selected certificate library.

Data Structures

This chapter describes the data structures which may be passed to or returned from a Certificate Library function. They will be 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. These data structures are defined in the header file <cssmtype.h>, distributed with CSSM.

CSSM_CL_HANDLE

The CSSM_CL_HANDLE is used to identify the association between an application thread and an instance of a CL module. It is assigned when an application causes CSSM to attach to a Certificate Library. It is freed when an application causes CSSM to detach from a Certificate Library. The application uses the CSSM_CL_HANDLE with every CL function call to identify the targeted CL. The CL module uses the CSSM_CL_HANDLE to identify the appropriate application's memory management routines when allocating memory on the application's behalf.


typedef CSSM_MODULE_HANDLE CSSM_CL_HANDLE

CSSM_CL_TEMPLATE_TYPE

This type defines an initial set of certificate template types. A certificate template is a buffer containing selected, encoded field values that are currently or will become values in a signed certificate. The template type defines the following aspects of the set of certificate fields:

The mandatory fields and the optional fields
Any ordering constraints on the selected fields
The encoding applied to the selected fields

Each Certificate Library Module should support one default template type.


typedef uint32 CSSM_CL_TEMPLATE_TYPE

#define CSSM_CL_TEMPLATE_INTERMEDIATE_CERT   1
    /* for X509 certificates, a fully-formed
       encoded certificate with empty signature field */
#define CSSM_CL_TEMPLATE_PKIX_CERTTEMPLATE   2
    /* as defined in RFC2511, section 5 CertTemplate */

CSSM_CERT_BUNDLE_TYPE

This enumerated type lists the industry-defined formats for aggregating certificates and possibly CRLs and other security objects. This class of aggregates is called a certificate bundle. Typically bundles include cryptographic hashes and/or digital signatures of some or all objects in the bundle. Bundles are often used as the representation for exchanging sets of certificates among computing systems. A certificate bundle differs from a CSSM_CERTGROUP in that a bundle is a single encoded object; a CSSM certificate group views each certificate as an independent, encoded object. The CSSM_CERTGROUP data structure is an array of references to individual certificates. Certificates contained in a bundle are located by repeatedly searching the single bundle object.


typedef enum cssm_cert_bundle_type {
    CSSM_CERT_BUNDLE_UNKNOWN = 0x00,
    CSSM_CERT_BUNDLE_CUSTOM = 0x01,
    CSSM_CERT_BUNDLE_PKCS7_SIGNED_DATA = 0x02,
    CSSM_CERT_BUNDLE_PKCS7_SIGNED_ENVELOPED_DATA = 0x03,
    CSSM_CERT_BUNDLE_PKCS12 = 0x04,
    CSSM_CERT_BUNDLE_PFX = 0x05,
    CSSM_CERT_BUNDLE_SPKI_SEQUENCE = 0x06,
    CSSM_CERT_BUNDLE_PGP_KEYRING = 0x07,
    CSSM_CERT_BUNDLE_LAST = 0x7FFF
} CSSM_CERT_BUNDLE_TYPE;

/* Applications wishing to define their own custom certificate
 * bundle type should define and publicly document a uint32
 * value greater than CSSM_CL_CUSTOM_CERT_BUNDLE_TYPE */

#define CSSM_CL_CUSTOM_CERT_BUNDLE_TYPE 0x8000

CSSM_CERT_BUNDLE_ENCODING

This enumerated type lists the encoding methods applied to the signed certificate aggregates that are considered to be certificate bundles.


typedef enum cssm_cert_bundle_encoding {
    CSSM_CERT_BUNDLE_ENCODING_UNKNOWN = 0x00,
    CSSM_CERT_BUNDLE_ENCODING_CUSTOM = 0x01,
    CSSM_CERT_BUNDLE_ENCODING_BER = 0x02,
    CSSM_CERT_BUNDLE_ENCODING_DER = 0x03,
    CSSM_CERT_BUNDLE_ENCODING_SEXPR = 0x04,
    CSSM_CERT_BUNDLE_ENCODING_PGP = 0x05,
} CSSM_CERT_BUNDLE_ENCODING;

CSSM_CERT_BUNDLE_HEADER

This structure defines a bundle header, which describes the type and encoding of a certificate bundle.


typedef struct cssm_cert_bundle_header {
    CSSM_CERT_BUNDLE_TYPE BundleType;
    CSSM_CERT_BUNDLE_ENCODING BundleEncoding;
} CSSM_CERT_BUNDLE_HEADER, *CSSM_CERT_BUNDLE_HEADER_PTR;

Definition

BundleType: A descriptor which identifies the format of the certificate aggregate.
BundleEncoding: A descriptor which identifies the encoding of the certificate aggregate.

CSSM_CERT_BUNDLE

This structure defines a certificate bundle, which consists of a descriptive header and a pointer to the opaque bundle. The bundle is an opaque aggregation of certificates and possibly other security-related objects.


typedef struct cssm_cert_bundle {
    CSSM_CERT_BUNDLE_HEADER BundleHeader;
    CSSM_DATA Bundle;
} CSSM_CERT_BUNDLE, *CSSM_CERT_BUNDLE_PTR;

Definition

BundleHeader: Information describing the format and encoding of the bundle contents.
Bundle: An opaque aggregation of certificates and possibly other security-related objects.

CSSM_OID

The object identifier (OID) structure is used to hold a unique identifier for the atomic data fields and the compound substructure that comprise the fields of a certificate or CRL. CSSM_OIDs exist outside of a certificate or a CRL. Typically, they are not stored within a certificate or CRL. A certificate library module implements a particular representation for certificates and CRLs. This representation is specified by the pair [certificate_type, certificate_encoding]. The underlying representation of a CSSM_OID is outside of the representation for a certificate or a CRL. Possible representations for a CSSM_OID include:

A character string in a character set native to the platform
A portable character string that can be exchanged across platforms
A DER-encoded, X.509-like OID that is parsed when used as a reference
A variable-length sequence of integers
An S-expression that must be evaluated when used as a reference
An enumerated value that is defined in header files supplied by group representing one or more CLMs

At most one representation and interpretation for a CSSM_OID should be defined for each unique cert-CRL representation. This provides interoperability among certificate library modules that manipulate the same certificate and CRL representations. Also the selected representation for CSSM_OIDs should be consist with the cert-CRL representation. For example, CLMs supporting BER/DER encoded X.509 certificates and CRL could use DER-encoded X.509-like OIDs as the representation for CSSM_OIDs. In contrast, CLMs supporting SDSI certificates could use S-expressions as the representation for CSSM_OIDs.


typedef CSSM_DATA CSSM_OID, *CSSM_OID_PTR

CSSM_CRL_TYPE

This structure represents the type of format used for revocation lists.


typedef enum cssm_crl_type {
    CSSM_CRL_TYPE_UNKNOWN,
    CSSM_CRL_TYPE_X_509v1,
    CSSM_CRL_TYPE_X_509v2,
    CSSM_CRL_TYPE_SPKI = 0x03,
    CSSM_CRL_TYPE_MULTIPLE = 0x7FFE,
} CSSM_CRL_TYPE, *CSSM_CRL_TYPE_PTR;

CSSM_CRL_ENCODING

This structure represents the encoding format used for revocation lists.


typedef enum cssm_crl_encoding { 
    CSSM_CRL_ENCODING_UNKNOWN,
    CSSM_CRL_ENCODING_CUSTOM,
    CSSM_CRL_ENCODING_BER,
    CSSM_CRL_ENCODING_DER,
    CSSM_CRL_ENCODING_BLOOM = 0x04,
    CSSM_CRL_ENCODING_SEXPR = 0x05,
    CSSM_CRL_ENCODING_MULTIPLE = 0x7FFE,
} CSSM_CRL_ENCODING, *CSSM_CRL_ENCODING_PTR;

CSSM_ENCODED_CRL

This structure contains a pointer to a certificate revocation list (CRL) in its encoded representation. The CRL is stored as a single contiguous byte array referenced by CrlBlob. The length of the byte array is contained in the Length subfield of the CrlBlob. The type and encoding of the CRL format are also contained in the structure.


typedef struct cssm_encoded_crl {
    CSSM_CRL_TYPE CrlType;          /* type of CRL */
    CSSM_CRL_ENCODING CrlEncoding;  /* encoding for this packed CRL */ 
    CSSM_DATA CrlBlob ;             /* packed CRL */ 
} CSSM_ENCODED_CRL, *CSSM_ENCODED_CRL_PTR ;

Definition

CrlType: Indicates the type of the certificate revocation list referenced by CrlBlob.
CrlEncoding: Indicates the encoding of the certificate revocation list referenced by CrlBlob.
CrlBlob: A two field structure containing a reference to a CRL in its opaque data blob format and the length of the byte array that contains the CRL blob.

CSSM_FIELD

This structure contains the OID/value pair for any item that can be identified by an OID. A certificate library module uses this structure to hold an OID/value pair for fields in a certificate or CRL.


typedef struct cssm_field {
    CSSM_OID FieldOid;
    CSSM_DATA FieldValue;
} CSSM_FIELD, *CSSM_FIELD_PTR;

Definition

FieldOid: The object identifier which identifies the certificate or CRL data type or data structure.
FieldValue: A CSSM_DATA type which contains the value of the specified OID in a contiguous block of memory.

CSSM_FIELDVALUE_COMPLEX_DATA_TYPE

The value to which the Length component of a CSSM_FIELD, FieldValue is set to indicate that the FieldValue Data pointer points to a complex data type.


#define CSSM_FIELDVALUE_COMPLEX_DATA_TYPE (0xFFFFFFFF)

Error Codes and Error Values

This section defines Error Values that can be returned by CL operations.

The Error Values that can be returned by CL functions can be either derived from the Common Error Codes defined in CSSM Error Handling, or from a set of Errors that more than one CL function can return, or they are specific to a CL function.

CL Error Values Derived from Common Error Codes


#define CSSMERR_CL_INTERNAL_ERROR \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_INTERNAL_ERROR)		
#define CSSMERR_CL_MEMORY_ERROR  \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_MEMORY_ERROR)			
#define CSSMERR_CL_MDS_ERROR  \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_MDS_ERROR)			
#define CSSMERR_CL_INVALID_POINTER  \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_INVALID_POINTER)			
#define CSSMERR_CL_INVALID_INPUT_POINTER  \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_INVALID_INPUT_POINTER)			
#define CSSMERR_CL_INVALID_OUTPUT_POINTER  \ 
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_INVALID_OUTPUT_POINTER)
#define CSSMERR_CL_FUNCTION_NOT_IMPLEMENTED  \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_FUNCTION_NOT_IMPLEMENTED)
#define CSSMERR_CL_SELF_CHECK_FAILED  \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_SELF_CHECK_FAILED)			
#define CSSMERR_CL_OS_ACCESS_DENIED  \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_OS_ACCESS_DENIED)			
#define CSSMERR_CL_FUNCTION_FAILED  \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_FUNCTION_FAILED)
#define CSSMERR_CL_INVALID_CONTEXT_HANDLE \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_INVALID_CONTEXT_HANDLE)		
#define CSSMERR_CL_INVALID_CERTGROUP_POINTER \				
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_INVALID_CERTGROUP_POINTER)
#define CSSMERR_CL_INVALID_CERT_POINTER \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_INVALID_CERT_POINTER)	
#define CSSMERR_CL_INVALID_CRL_POINTER \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_INVALID_CRL_POINTER)	
#define CSSMERR_CL_INVALID_FIELD_POINTER \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_INVALID_FIELD_POINTER)	
#define CSSMERR_CL_INVALID_DATA \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_INVALID_DATA)	
#define CSSMERR_CL_CRL_ALREADY_SIGNED \ 
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_CRL_ALREADY_SIGNED)	
#define CSSMERR_CL_INVALID_NUMBER_OF_FIELDS \ 
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_INVALID_NUMBER_OF_FIELDS)	
#define CSSMERR_CL_VERIFICATION_FAILURE \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_VERIFICATION_FAILURE)
#define CSSMERR_CL_UNKNOWN_FORMAT \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_UNKNOWN_FORMAT)
#define CSSMERR_CL_UNKNOWN_TAG \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_UNKNOWN_TAG)
#define CSSMERR_CL_INVALID_PASSTHROUGH_ID \
    (CSSM_CL_BASE_ERROR+CSSM_ERRCODE_INVALID_PASSTHROUGH_ID)

CL Error Values

These codes can be returned by one or more CL APIs.


#define CSSM_CL_BASE_CL_ERROR \
    (CSSM_CL_BASE_ERROR+CSSM_ERRORCODE_COMMON_EXTENT)

#define CSSMERR_CL_INVALID_BUNDLE_POINTER (CSSM_CL_BASE_CL_ERROR+1)

Invalid pointer for certificate bundle


#define CSSMERR_CL_INVALID_CACHE_HANDLE	(CSSM_CL_BASE_CL_ERROR+2)

Invalid certificate or CRL cache handle


#define CSSMERR_CL_INVALID_RESULTS_HANDLE (CSSM_CL_BASE_CL_ERROR+3)

Invalid handle for results of a certificate or CRL query


#define CSSMERR_CL_INVALID_BUNDLE_INFO (CSSM_CL_BASE_CL_ERROR+4)

Unknown type or encoding for certificate bundle


#define CSSMERR_CL_INVALID_CRL_INDEX (CSSM_CL_BASE_CL_ERROR+5)

Invalid index for revocation record in CRL


#define CSSMERR_CL_INVALID_SCOPE (CSSM_CL_BASE_CL_ERROR+6)

Invalid sign or verify scope (function dependent)


#define CSSMERR_CL_NO_FIELD_VALUES (CSSM_CL_BASE_CL_ERROR+7)

No field matched the specified certificate or CRL field OID


#define CSSMERR_CL_SCOPE_NOT_SUPPORTED (CSSM_CL_BASE_CL_ERROR+8)

Field signing or verifying is not supported by this module

Certificate Operations

This section defines the function prototypes and error codes supported by a Certificate Library module for operations on certificates.

The error codes given in this section constitute the generic error codes which 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

CSSM_CL_CertCreateTemplate

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 CertTemplate->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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_FIELD_POINTER
CSSMERR_CL_UNKNOWN_TAG
CSSMERR_CL_INVALID_NUMBER_OF_FIELDS

NAME

CSSM_CL_CertGetAllTemplateFields

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CL_UNKNOWN_FORMAT

NAME

CSSM_CL_CertSign

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CONTEXT_HANDLE
CSSMERR_CL_UNKNOWN_FORMAT
CSSMERR_CL_INVALID_FIELD_POINTER
CSSMERR_CL_UNKNOWN_TAG
CSSMERR_CL_INVALID_SCOPE
CSSMERR_CL_INVALID_NUMBER_OF_FIELDS
CSSMERR_CL_SCOPE_NOT_SUPPORTED

NAME

CSSM_CL_CertVerify

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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.

PARAMETERS

CLHandle (input/optional)

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.

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. (This should include all of 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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CONTEXT_HANDLE
CSSMERR_CL_INVALID_CERT_POINTER
CSSMERR_CL_UNKNOWN_FORMAT
CSSMERR_CL_INVALID_FIELD_POINTER
CSSMERR_CL_UNKNOWN_TAG
CSSMERR_CL_INVALID_SCOPE
CSSMERR_CL_INVALID_NUMBER_OF_FIELDS
CSSMERR_CL_SCOPE_NOT_SUPPORTED
CSSMERR_CL_VERIFICATION_FAILURE

NAME

CSSM_CL_CertVerifyWithKey

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CONTEXT_HANDLE
CSSMERR_CL_INVALID_CERT_POINTER
CSSMERR_CL_UNKNOWN_FORMAT
CSSMERR_CL_VERIFICATION_FAILURE

NAME

CSSM_CL_CertGetFirstFieldValue

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 CSSM_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 CSSM_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 which identifies the field value to be extracted from the Cert.

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

ERRORS

See also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CERT_POINTER
CSSMERR_CL_UNKNOWN_FORMAT
CSSMERR_CL_UNKNOWN_TAG
CSSMERR_CL_NO_FIELD_VALUES

NAME

CSSM_CL_CertGetNextFieldValue

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 CSSM_CL_CertGetFirstFieldValue() returns a results handle identifying the size and values contained in the result set. The CSSM_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 which 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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_RESULTS_HANDLE
CSSMERR_CL_NO_FIELD_VALUES

NAME

CSSM_CL_CertAbortQuery

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 CSSM_CL_CertGetFirstFieldValue() or by CSSM_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 CSSM_CL_CertGetNextFieldValue() or CSSM_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)

A pointer to the handle which identifies the results of a CSSM_CL_GetFieldValue request.

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 also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CL_INVALID_RESULTS_HANDLE

NAME

CSSM_CL_CertGetKeyInfo

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CL_CertGetKeyInfo
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Cert,
    CSSM_KEY_PTR *Key)

DESCRIPTION

This function returns the public key and integral information about the key from the specified certificate. The key structure returned is a compound object. It can be used in any function requiring a key, such as creating a cryptographic context.

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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CERT_POINTER
CSSMERR_CL_UNKNOWN_FORMAT

NAME

CSSM_CL_CertGetAllFields

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CL_CertGetAllFields
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Cert,
    uint32 *NumberOfFields,
    CSSM_FIELD_PTR *FieldList)

DESCRIPTION

This function returns a list of the values stored in the input certificate.

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 returned array of fields.

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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CERT_POINTER
CSSMERR_CL_UNKNOWN_FORMAT

NAME

CSSM_CL_FreeFields

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 calls

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 (input)

The length of the array of fields in FieldArray

FieldArray (input)

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

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

NAME

CSSM_CL_FreeFieldValue

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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
CSSM_CL_CertGetFirstFieldValue,()
CSSM_CL_CertGetNextFieldValue,()
CSSM_CL_CertGetFirstCachedFieldValue,()
CSSM_CL_CertGetNextCachedFieldValue,()
CSSM_CL_CrlGetFirstFieldValue,()
CSSM_CL_CrlGetNextFieldValue(),
CSSM_CL_CrlGetFirstCachedFieldValue,()
CSSM_CL_CrlGetNextCachedFieldValue,()

PARAMETERS

CLHandle (input)

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

CertOrCrlOid (input)

A pointer to the CSSM_OID structure describing 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 also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CL_UNKNOWN_TAG

Previous section.

NAME

CSSM_CL_CertCache

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 CSSM_CL_CertGetFirstCachedFieldValue() and CSSM_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 CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CERT_POINTER
CSSMERR_CL_UNKNOWN_FORMAT

NAME

CSSM_CL_CertGetFirstCachedFieldValue

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 CSSM_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 CSSM_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 CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CACHE_HANDLE
CSSMERR_CL_UNKNOWN_TAG
CSSMERR_CL_NO_FIELD_VALUES

NAME

CSSM_CL_CertGetNextCachedFieldValue

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_RESULTS_HANDLE
CSSMERR_CL_NO_FIELD_VALUES

NAME

CSSM_CL_CertAbortCache

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CL_CertAbortCache
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE CertHandle)

DECRIPTION

This function terminates a certificate cache handle created and returned by the function CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CL_INVALID_CACHE_HANDLE

NAME

CSSM_CL_CertGroupToSignedBundle

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CONTEXT_HANDLE
CSSMERR_CL_INVALID_CERTGROUP_POINTER
CSSMERR_CL_INVALID_CERT_POINTER
CSSMERR_CL_UNKNOWN_FORMAT
CSSMERR_CL_INVALID_BUNDLE_POINTER
CSSMERR_CL_INVALID_BUNDLE_INFO

NAME

CSSM_CL_CertGroupFromVerifiedBundle

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 substructures are allocated by the serivce 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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CONTEXT_HANDLE
CSSMERR_CL_INVALID_BUNDLE_POINTER
CSSMERR_CL_INVALID_BUNDLE_INFO
CSSMERR_CL_INVALID_CERT_POINTER
CSSMERR_CL_INVALID_CERTGROUP_POINTER
CSSMERR_CL_UNKNOWN_FORMAT

NAME

CSSM_CL_CertDescribeFormat

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 CSSM_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 (output)

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

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

Certificate Revocation List Operations

This section describes the function prototypes and error codes supported by a Certificate Library module for operations on certificate revocation lists (CRLs).

The error codes given in this section constitute the generic error codes which 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

CSSM_CL_CrlCreateTemplate

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CL_CrlCreateTemplate
    (CSSM_CL_HANDLE CLHandle,
    uint32 NumberOfFields,
    const CSSM_FIELD *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. Subsequent values may be set using the CSSM_CL_CrlSetFields operation. The new CRL contains no revocation records.

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)

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

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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_FIELD_POINTER
CSSMERR_CL_UNKNOWN_TAG
CSSMERR_CL_INVALID_NUMBER_OF_FIELDS
CSSMERR_CL_INVALID_CRL_POINTER

NAME

CSSM_CL_CrlSetFields

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CL_CrlSetFields
    (CSSM_CL_HANDLE CLHandle,
    uint32 NumberOfFields,
    const CSSM_FIELD *CrlTemplate,
    const CSSM_DATA *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. If there is more than one possible instance of an OID (for example, as in an extension or CRL record) then a NEW field with the specified value is added to the CRL.
This should be used to update any of the CRL field values. If a specified field was initialized by the CSSM_CL_CrlCreateTemplate() function, the field value is set to the new specified value. If a specified field was not initialized by the CSSM_CL_CrlCreateTemplate() function, the field is set to the new specified value. OldCrl must be unsigned. Once a CRL has been signed using CSSM_CL_CrlSign(), the signed CRL's field values can not be modified. Modification would invalidate the cryptographic signature of the CRL.

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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_FIELD_POINTER
CSSMERR_CL_UNKNOWN_TAG
CSSMERR_CL_INVALID_NUMBER_OF_FIELDS
CSSMERR_CL_UNKNOWN_FORMAT
CSSMERR_CL_INVALID_CRL_POINTER
CSSMERR_CL_CRL_ALREADY_SIGNED

NAME

CSSM_CL_CrlAddCert

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 reason for revocation is a typical value specified in the list. The 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 (by executing the CSSM_CL_CrlSign() function). 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)

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 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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CONTEXT_HANDLE
CSSMERR_CL_INVALID_CERT_POINTER
CSSMERR_CL_UNKNOWN_FORMAT
CSSMERR_CL_INVALID_FIELD_POINTER
CSSMERR_CL_UNKNOWN_TAG
CSSMERR_CL_INVALID_NUMBER_OF_FIELDS
CSSMERR_CL_INVALID_CRL_POINTER
CSSMERR_CL_CRL_ALREADY_SIGNED

NAME

CSSM_CL_CrlRemoveCert

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CL_CrlRemoveCert
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Cert,
    const CSSM_DATA *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 been closed by the process of signing the CRL (by executing the CSSM_CL_CrlSign function). 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 reinstated.

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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CERT_POINTER
CSSMERR_CL_INVALID_CRL_POINTER
CSSMERR_CL_UNKNOWN_FORMAT
CSSMERR_CL_CRL_ALREADY_SIGNED

NAME

CSSM_CL_CrlSign

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 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 CSSM_CL_CrlAddCert() or CSSM_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/optional)

A pointer to the CSSM_FIELD array containing the tag/value pairs of the fields to be signed. If the signing scope is null, the certificate library module includes a default set of CRL fields in the signing process.

ScopeSize (input)

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

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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CONTEXT_HANDLE
CSSMERR_CL_INVALID_CRL_POINTER
CSSMERR_CL_UNKNOWN_FORMAT
CSSMERR_CL_INVALID_FIELD_POINTER
CSSMERR_CL_UNKNOWN_TAG
CSSMERR_CL_INVALID_SCOPE
CSSMERR_CL_SCOPE_NOT_SUPPORTED
CSSMERR_CL_INVALID_NUMBER_OF_FIELDS
CSSMERR_CL_CRL_ALREADY_SIGNED

NAME

CSSM_CL_CrlVerify

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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/optional)

A pointer to the CSSM_FIELD array containing the tag/value pairs of the fields to be verified. If the verification scope is null, the certificate library module assumes that a default set of fields were used in the signing process 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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CONTEXT_HANDLE
CSSMERR_CL_INVALID_CERT_POINTER
CSSMERR_CL_INVALID_CRL_POINTER
CSSMERR_CL_UNKNOWN_FORMAT
CSSMERR_CL_INVALID_FIELD_POINTER
CSSMERR_CL_UNKNOWN_TAG
CSSMERR_CL_INVALID_SCOPE
CSSMERR_CL_INVALID_NUMBER_OF_FIELDS
CSSMERR_CL_SCOPE_NOT_SUPPORTED
CSSMERR_CL_VERIFICATION_FAILURE

NAME

CSSM_CL_CrlVerifyWithKey

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CONTEXT_HANDLE
CSSMERR_CL_INVALID_CRL_POINTER
CSSMERR_CL_UNKNOWN_FORMAT
CSSMERR_CL_VERIFICATION_FAILURE

NAME

CSSM_CL_IsCertInCrl

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 verified, 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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CERT_POINTER
CSSMERR_CL_INVALID_CRL_POINTER
CSSMERR_CL_UNKNOWN_FORMAT

Previous section.

NAME

CSSM_CL_CrlGetFirstFieldValue

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 CSSM_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 CSSM_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 which contains the CRL from which the field is to be retrieved.

CrlField (input)

An object identifier which 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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CRL_POINTER
CSSMERR_CL_UNKNOWN_FORMAT
CSSMERR_CL_UNKNOWN_TAG
CSSMERR_CL_NO_FIELD_VALUES

NAME

CSSM_CL_CrlGetNextFieldValue

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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. CRL with repeated fields (such as revocation records) have multiple field values corresponding to a single OID. A call to the function CSSM_CL_CrlGetFirstFieldValue initiates the process and returns a results handle identifying the size and values contained in the result set. The CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_RESULTS_HANDLE
CSSMERR_CL_NO_FIELD_VALUES

NAME

CSSM_CL_CrlAbortQuery

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CL_CrlAbortQuery
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE ResultsHandle)

DESCRIPTION

This function terminates the query initiated by CSSM_CL_CrlGetFirstFieldValue() or CSSM_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 CSSM_CL_CrlGetNextFieldValue() or CSSM_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 which 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 also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CL_INVALID_RESULTS_HANDLE

NAME

CSSM_CL_CrlGetAllFields

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CRL_POINTER
CSSMERR_CL_UNKNOWN_FORMAT

NAME

CSSM_CL_CrlCache

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 CSSM_CL_CrlGetFirstFieldValue() and CSSM_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 CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CRL_POINTER
CSSMERR_CL_UNKNOWN_FORMAT

NAME

CSSM_CL_IsCertInCachedCrl

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 CSSM_TP_CrlVerify() or CSSM_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)

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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CERT_POINTER
CSSMERR_CL_UNKNOWN_FORMAT
CSSMERR_CL_INVALID_CACHE_HANDLE

NAME

CSSM_CL_CrlGetFirstCachedFieldValue

SYNOPSIS


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

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 CSSM_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 CSSM_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 CSSM_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 CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CACHE_HANDLE
CSSMERR_CL_INVALID_CRL_INDEX
CSSMERR_CL_UNKNOWN_TAG
CSSMERR_CL_NO_FIELD_VALUES

NAME

CSSM_CL_CrlGetNextCachedFieldValue

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CL_CrlGetNextCachedFieldValue
    (CSSM_CL_HANDLE CLHandle, 
    CSSM_HANDLE ResultsHandle,
    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 CSSM_CL_CrlGetFirstCachedFieldValue() initiates the process and returns a ResultsHandle identifying the size and values contained in the result set. The CSSM_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 CSSM_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 CSSM_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 "(*FiledValue)->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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_RESULTS_HANDLE
CSSMERR_CL_NO_FIELD_VALUES

NAME

CSSM_CL_CrlGetAllCachedRecordFields

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CL_CrlGetAllCachedRecordFields
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE CrlHandle, 
    const CSSM_DATA *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 CSSM_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 CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CACHE_HANDLE
CSSMERR_CL_INVALID_CRL_INDEX

NAME

CSSM_CL_CrlAbortCache

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CL_INVALID_CACHE_HANDLE

NAME

CSSM_CL_CrlDescribeFormat

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 CSSM_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 returned array of OIDs.

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

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

Extensibility Functions

The man-page for the Certificate Library extensibility function is presented in this section. Previous section.

NAME

CSSM_CL_PassThrough

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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. If the module-specific operation does not perform any cryptographic operations a cryptographic context is not required.

PassThroughId (input)

An identifier assigned by the CL module to indicate the exported 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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CONTEXT_HANDLE
CSSMERR_CL_INVALID_PASSTHROUGH_ID
CSSMERR_CL_INVALID_DATA

Contents

Next section

Index

Certificate Library Services API

Overview

Application and Certificate Library Interaction

Operations on Certificates

Data Structures

CSSM_CL_HANDLE

CSSM_CL_TEMPLATE_TYPE

CSSM_CERT_BUNDLE_TYPE

CSSM_CERT_BUNDLE_ENCODING

CSSM_CERT_BUNDLE_HEADER

Definition

CSSM_CERT_BUNDLE

Definition

CSSM_OID

CSSM_CRL_TYPE

CSSM_CRL_ENCODING

CSSM_ENCODED_CRL

Definition

CSSM_FIELD

Definition

CSSM_FIELDVALUE_COMPLEX_DATA_TYPE

Error Codes and Error Values

CL Error Values Derived from Common Error Codes

CL Error Values

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

ERRORS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS