Common Security: CDSA and CSSM, Version 2 (with corrigenda)
Copyright © 2000 The Open Group

Certificate Library Services

Overview

Certificates and CRLs

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 add-in 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
- 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.
Certificate revocation list operations
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.
Extensibility functions
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.

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.

The certificate library developer may choose to implement some or all of these CL interface 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.

Add-In Module

Figure: CDSA Add-In Module Structure

A CDSA add-in module is a dynamically-linkable library, composed of functions that implement some or all of the CSSM Module Interfaces. Add-in module functionality is partitioned into two areas:

The provision of security services to applications
Module administration

Add-in modules provide one or more categories of security services to applications, in this case the Certificate Library (CL) services. Each security service contains one or more implementation instances, called sub-services. For a CL service provider, a sub-service would represent a specific certificate format. These sub-services each support the module interface for their respective service categories.

Each module, regardless of the security services it offers, has the same set of administrative responsibilities. Every module must expose functions that allow CSSM to indicate events such as module attach and detach. In addition, as part of the attach operation, every module must be able to verify its own integrity, verify the integrity of CSSM, and register with CSSM. Detailed information about add-in module structure, administration, and interfaces can be found in Part 14 of this Technical Standard.

Certificate Life Cycle

The Certificate Library provides support for the certificate life cycle and for format-specific certificate or CRL manipulation services which an application can access via CSSM. These libraries allow applications and add-in modules to create, sign, verify, revoke, renew, and recover certificates without requiring knowledge of certificate and CRL formats and encodings.

A certificate is a form of credential. Under current certificate models, such as X.509, SDSI, SPKI, and so on, a single certificate represents the identity of an entity and optionally associates authorizations with that entity. When a certificate is issued, the issuer includes a digital signature on the certificate. Verification of this signature is the mechanism used to establish trust in the identity and authorizations recorded in the certificate. Certificates can be signed by one or more other certificates. Root certificates are self-signed. The syntactic process of signing corresponds to establishing a trust relationship between the entities identified by the certificates.

The certificate life cycle is presented in Certificate Life Cycle States and Actions. It begins with the registration process. During registration, the authenticity of a user's identity is verified. This can be a two part process beginning with manual procedures requiring physical presence followed by backoffice procedures to register results for use by the automated system. The level of verification associated with the identity of the individual will depend on the Security Policy and Certificate Management Practice Statements that apply to the individual who will receive a certificate and the domain in which that certificate will be issued and used.

After registration, keying material is generated and a certificate is created. Once the private key material and public key certificate are issued to a user and backed up if appropriate, the active phase of the certificate management life cycle begins.

The active phase includes:

Retrieval-retrieving a certificate from a remote repository such as an X.500 directory
Verification-verifying the validity dates, signatures on a certificate and revocation status
Revocation-asserting that a previously legitimate certificate is no longer a valid certificate
Recovery-when an end-user can no longer access encryption keys (for example, because they have forgotten their password)
Update-issuing a new public/private key pair when a legitimate pair has or will expire soon

Figure: Certificate Life Cycle States and Actions

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 presents the man-page definitions for the functions 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.

NAME

CSSM_CL_CertCreateTemplate for the CSSM API
CL_CertCreateTemplate for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CertCreateTemplate
    (CSSM_CL_HANDLE CLHandle,
    uint32 NumberOfFields,
    const CSSM_FIELD *CertFields, 
    CSSM_DATA_PTR CertTemplate)

SPI:
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 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 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 for the CSSM API
CL_CertGetAllTemplateFields for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CertGetAllTemplateFields
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *CertTemplate,
    uint32 *NumberOfFields,
    CSSM_FIELD_PTR *CertFields)

SPI:
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() (CSSM API) or CL_FreeFields() (CL SPI).

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

NAME

CSSM_CL_CertSign for the CSSM API
CL_CertSign for the CL SPI

SYNOPSIS


API:
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)

SPI:
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 CSSM_CL_CertCreateTemplate() (CSSM API) or CL_CertCreateTemplate() (CL SPI). The template is in the default format for this CL.
The CCHandle must be a signature context created using the function CSSM_CSP_CreateSignatureContext(). (CSSM API) or CSP_CreateSignatureContext(). (SPI). 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 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 for the CSSM API
CL_CertVerify for the CL SPI

SYNOPSIS


API:
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)

SPI:
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.
The caller can specify a cryptographic service provider and verification algorithm that 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 must specify the necessary verification algorithm parameters. These parameter values are specified in one of two locations:

As a field value in the SignerCert

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

If both of the above arguments are supplied, a consistency check is performed to ensure that they result in the same verification algorithm parameters. If they are not consistent, an error is returned. If only one of the above arguments is supplied, that argument is used to generate the verification algorithm parameters. 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. (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 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 for the CSSM API
CL_CertVerifyWithKey for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CertVerifyWithKey
    (CSSM_CL_HANDLE CLHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *CertToBeVerified)

SPI:
CSSM_RETURN CSSMCLI 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(). (CSSM API) or CSP_CreateSignatureContext(). (SPI). 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 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 for the CSSM API
CL_CertGetFirstFieldValue for the CL SPI

SYNOPSIS


API:
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)

SPI:
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 CSSM_CL_CertDescribeFormat() (CSSM API) or CL_CertDescribeFormat() (CL SPI). 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() (CSSM API) or CL_CertGetNextFieldValue() (CL SPI).

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() (CSSM API) or CL_FreeFieldValue() (CL SPI) 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 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 for the CSSM API
CL_CertGetNextFieldValue for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CertGetNextFieldValue
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE ResultsHandle,
    CSSM_DATA_PTR *Value)

SPI:
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 CSSM_CL_CertGetFirstFieldValue() (CSSM API) or CL_CertGetFirstFieldValue() (CL SPI). returns a results handle identifying the size and values contained in the result set. The CSSM_CL_CertGetNextFieldValue() (CSSM API) or CL_CertGetNextFieldValue() (CL SPI) 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() (CSSM API) or CL_FreeFieldValue() (CL SPI) 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 Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_RESULTS_HANDLE
CSSMERR_CL_NO_FIELD_VALUES

NAME

CSSM_CL_CertAbortQuery for the CSSM API
CL_CertAbortQuery for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CertAbortQuery
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE ResultsHandle)

SPI:
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() (CSSM API) or CL_CertGetFirstFieldValue() (CL SPI), or by CSSM_CL_CertGetFirstCachedFieldValue(). (CSSM API) or CL_CertGetFirstCachedFieldValue(). (CL SPI). 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() (CSSM API) or CL_CertGetNextFieldValue() (CL SPI), or CSSM_CL_CertGetNextCachedFieldValue() (CSSM API) or CL_CertGetNextCachedFieldValue() (CL SPI), 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() (CSSM API) or CL_GetFieldValue() (CLI SPI) 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 the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CL_INVALID_RESULTS_HANDLE

NAME

CSSM_CL_CertGetKeyInfo for the CSSM API
CL_CertGetKeyInfo for the CL SPI

SYNOPSIS


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

SPI:
CSSM_RETURN CSSMCLI 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 the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CERT_POINTER
CSSMERR_CL_UNKNOWN_FORMAT

NAME

CSSM_CL_CertGetAllFields for the CSSM API
CL_CertGetAllFields for the CL SPI

SYNOPSIS


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

SPI:
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 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() (CSSM API) or CL_FreeFields() (CL SPI).

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

CSSMERR_CL_INVALID_CERT_POINTER
CSSMERR_CL_UNKNOWN_FORMAT

NAME

CSSM_CL_FreeFields for the CSSM API
CL_FreeFields for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_FreeFields
    (CSSM_CL_HANDLE CLHandle,
    uint32 NumberOfFields,
    CSSM_FIELD_PTR *FieldArray)

SPI:
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 calls

CSSM_TP_CertGetAllTemplateFields()
CSSM_CL_CertGetAllTemplateFields()
CSSM_CL_CertGetAllFields()
CSSM_CL_CrlGetAllFields()
CSSM_CL_CrlGetAllCachedRecordFields()
or their SPI equivalent calls.

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.

Previous section.

NAME

CSSM_CL_FreeFieldValue for the CSSM API
CL_FreeFieldValue for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_FreeFieldValue
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_OID *CertOrCrlOid,
    CSSM_DATA_PTR Value) 

SPI:
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
CSSM_CL_CertGetFirstFieldValue()
CSSM_CL_CertGetNextFieldValue()
CSSM_CL_CertGetFirstCachedFieldValue()
CSSM_CL_CertGetNextCachedFieldValue()
CSSM_CL_CrlGetFirstFieldValue()
CSSM_CL_CrlGetNextFieldValue()
CSSM_CL_CrlGetFirstCachedFieldValue()
CSSM_CL_CrlGetNextCachedFieldValue()
or their CLI SPI equivalents.

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

Previous section.

NAME

CSSM_CL_CertCache for the CSSM API
CL_CertCache for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CertCache
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Cert,
    CSSM_HANDLE_PTR CertHandle)

SPI:
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() (CSSM API) or CL_CertGetFirstCachedFieldValue() (CL SPI), and CSSM_CL_CertGetNextCachedFieldValue() (CSSM API) or CL_CertGetNextCachedFieldValue() (CL SPI).
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() (CSSM API) or CL_CertAbortCache() (CL SPI), 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 Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CERT_POINTER
CSSMERR_CL_UNKNOWN_FORMAT

NAME

CSSM_CL_CertGetFirstCachedFieldValue for the CSSM API
CL_CertGetFirstCachedFieldValue for the CL SPI

SYNOPSIS


API:
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)

SPI:
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() (CSSM API) or CL_CertDescribeFormat() (CL SPI) 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() (CSM API) or CertGetNextCachedFieldValue() (CL SPI) to retrieve the remaining matches. The first match is returned as the return value of this function.
This function determines the complete set of matches. The number of matches and the selected field values do not change between this function and subsequent calls to CSSM_CL_CertGetNextCachedFieldValue(). (CSSM API) or CL_CertGetNextCachedFieldValue(). (CL SPI).

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() (CSSM API) or CL_FreeFieldValue() (CL SPI) 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 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 for the CSSM API
CL_CertGetNextCachedFieldValue for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CertGetNextCachedFieldValue
    (CSSM_CL_HANDLE CLHandle, 
    CSSM_HANDLE ResultsHandle,
    CSSM_DATA_PTR *FieldValue) 

SPI:
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() (CSSM API) or CL_CertGetFirstCachedFieldValue() (CL SPI) returns a ResultsHandle identifying the size and values contained in the result set. The CSSM_CL_CertGetNextCachedFieldValue() (CSSMAPI) or CL_CertGetNextCachedFieldValue() (CL SPI) 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() (CSSM API) or CL_FreeFieldValue() (CL SPI) 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 Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_RESULTS_HANDLE
CSSMERR_CL_NO_FIELD_VALUES

NAME

CSSM_CL_CertAbortCache for the CSSM API
CL_CertAbortCache for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CertAbortCache
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE CertHandle)
SPI:

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() (CSSM API) or CL_CertCache() (CL SPI). 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 Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CL_INVALID_CACHE_HANDLE

NAME

CSSM_CL_CertGroupToSignedBundle for the CSSM API
CL_CertGroupToSignedBundle for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CertGroupToSignedBundle
    (CSSM_CL_HANDLE CLHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CERTGROUP *CertGroupToBundle,
    const CSSM_CERT_BUNDLE_HEADER *BundleInfo,
    CSSM_DATA_PTR SignedBundle)

SPI:
CSSM_RETURN CSSMCLI CL_CertGroupToSignedBundle
    (CSSM_CL_HANDLE CLHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CERTGROUP *CertGroupToBundle,
    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. 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.

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 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 for the CSSM API
CL_CertGroupFromVerifiedBundle for the CL SPI

SYNOPSIS


API:
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)

SPI:
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/optional)

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 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 for the CSSM API
CL_CertDescribeFormat for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CertDescribeFormat
    (CSSM_CL_HANDLE CLHandle,
    uint32 *NumberOfOids,
    CSSM_OID_PTR *OidList)

SPI:
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() (CSSM API) or CL_CertGetFirstFieldValue() (CL SPI) 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 presents the man-page definitions for the functions prototypes 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 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

CSSM_CL_CrlCreateTemplate for the CSSM API
CL_CrlCreateTemplate for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CrlCreateTemplate
    (CSSM_CL_HANDLE CLHandle,
    uint32 NumberOfFields,
    const CSSM_FIELD *CrlTemplate,
    CSSM_DATA_PTR NewCrl)

SPI:
CSSM_RETURN CSSMCLI 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() call (CSSM API) or CL_CrlSetFields() call (CL SPI). 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 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 for the CSSM API
CL_CrlSetFields for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CrlSetFields
    (CSSM_CL_HANDLE CLHandle,
    uint32 NumberOfFields,
    const CSSM_FIELD *CrlTemplate,
    const CSSM_DATA *OldCrl,
    CSSM_DATA_PTR ModifiedCrl)
SPI:
CSSM_RETURN CSSMCLI 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 CSSM_CL_CrlCreateTemplate() (CSSM API) or CL_CrlCreateTemplate() (CL SPI), the field value is set to the new specified value. If a specified field was not initialized by the CSSM_CL_CrlCreateTemplate() (CSSM API) or CL_CrlCreateTemplate() (CL SPI), the field is set to the new specified value. OldCrl must be unsigned. Once a CRL has been signed using CSSM_CL_CrlSign() (CSSM API) or CL_CrlSign() (CL SPI), 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 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 for the CSSM API
CL_CrlAddCert for the CL SPI

SYNOPSIS


API:
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)

SPI:
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 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() (CSSM API) or CSP_CreateSignatureContext() (CL SPI). 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 calling CSSM_CL_CrlSign() (CSSM API) or CL_CrlSign() (CL SPI). 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 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 for the CSSM API
CL_CrlRemoveCert for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CrlRemoveCert
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Cert,
    const CSSM_DATA *OldCrl,
    CSSM_DATA_PTR NewCrl)

SPI:
CSSM_RETURN CSSMCLI 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 CSSM_CL_CrlSign() (CSSM API) or CL_CrlSign() (CL SPI). 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 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 for the CSSM API
CL_CrlSign for the CL SPI

SYNOPSIS


API:
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)

SPI:
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 CRL 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 (for the CSSM API) or their CL SPI equivalents.
The CCHandle must be a context created using the function CSSM_CSP_CreateSignatureContext() (CSSM API) or CSP_CreateSignatureContext() (SPI). 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() (or their CL SPI equivalent 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 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 for the CSSM API
CL_CrlVerify for the CL SPI

SYNOPSIS


API:
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)

SPI:
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/optional)

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/optional)

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 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 for the CSSM API
CL_CrlVerifyWithKey for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CrlVerifyWithKey
    (CSSM_CL_HANDLE CLHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *CrlToBeVerified) 

SPI:
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 CSSM_CSP_CreateSignatureContext() (CSSM API) or CSP_CreateSignatureContext() (CL SPI). 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 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 for the CSSM API
CL_IsCertInCrl for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_IsCertInCrl
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Cert,
    const CSSM_DATA *Crl,
    CSSM_BOOL *CertFound)

SPI:
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() (or their SPI equivalents) 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 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 for the CSSM API
CL_CrlGetFirstFieldValue for the CL SPI

SYNOPSIS


API:
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)

SPI:
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 CSSM_CL_CrlDescribeFormat() (CSSM API) or CL_CrlDescribeFormat() (CL SPI) 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() (CSSM API) or CL_CrlGetNextFieldValue() (CL SPI).

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() (CSSM API) or CL_FreeFieldValue() (CL SPI) 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 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 for the CSSM API
CL_CrlGetNextFieldValue for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CrlGetNextFieldValue
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE ResultsHandle,
    CSSM_DATA_PTR *Value)

SPI:
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. 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() (CSSM API) or CL_CrlGetFirstFieldValue() (CL SPI) initiates the process and returns a results handle identifying the size and values contained in the result set. The CSSM_CL_CrlGetNextFieldValue() (CSSM API) or CL_CrlGetNextFieldValue() (CL SPI) 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() (CSSM API) or CL_FreeFieldValue() (CL SPI) 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 Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_RESULTS_HANDLE
CSSMERR_CL_NO_FIELD_VALUES

NAME

CSSM_CL_CrlAbortQuery for the CSSM API
CL_CrlAbortQuery for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CrlAbortQuery
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE ResultsHandle)

SPI:
CSSM_RETURN CSSMCLI CL_CrlAbortQuery
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE ResultsHandle)

DESCRIPTION

This function terminates the query initiated by CSSM_CL_CrlGetFirstFieldValue() or CSSM_CL_CrlGetFirstCachedFieldValue() (or their CL SPI equivalents) 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() (or their CL SPI equivalents) 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 the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CL_INVALID_RESULTS_HANDLE

NAME

CSSM_CL_CrlGetAllFields for the CSSM API
CL_CrlGetAllFields for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CrlGetAllFields
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Crl,
    uint32 *NumberOfCrlFields,
    CSSM_FIELD_PTR *CrlFields)

SPI:
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 CSSM_CL_CrlAddCert() (CSSM API) or CL_CrlAddCert() (CL SPI).

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() (CSSM API) or CL_FreeFields() (CL SPI).

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

CSSMERR_CL_INVALID_CRL_POINTER
CSSMERR_CL_UNKNOWN_FORMAT

NAME

CSSM_CL_CrlCache for the CSSM API
CL_CrlCache for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CrlCache
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Crl, 
    CSSM_HANDLE_PTR CrlHandle) 

SPI:
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 CSSM_CL_CrlGetFirstFieldValue() and CSSM_CL_CrlGetNextFieldValue() (or their CL SPI equivalents).
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() (CSSM API) or CL_CrlCacheAbort() (CL SPI) 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 Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_CRL_POINTER
CSSMERR_CL_UNKNOWN_FORMAT

NAME

CSSM_CL_IsCertInCachedCrl for the CSSM API
CL_IsCertInCachedCrl for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_IsCertInCachedCrl
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA *Cert,
    CSSM_HANDLE CrlHandle,
    CSSM_BOOL *CertFound,
    CSSM_DATA_PTR CrlRecordIndex)

SPI:
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 CSSM_TP_CrlVerify() or CSSM_CL_CrlVerify() (or their SPI equivalents) 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 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 for the CSSM API
CL_CrlGetFirstCachedFieldValue for the CL SPI

SYNOPSIS


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

SPI:
CSSM_RETURN CSSMCLI CL_CrlGetFirstCachedFieldValue
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE CrlHandle, 
    const CSSM_DATA *CrlRecordIndex, 
    const CSSM_OID *CrlField,
    CSSM_HANDLE_PTR ResultsHandle,
    uint32 *NumberOfMatchedFields,
    CSSM_DATA_PTR *FieldValue)

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() (CSSM API) or CL_CrlDescribeFormat() (CL SPI) provides a list of all CSSM_OID values supported by a CL module for naming fields of a CRL.
The search can be limited to a particular revocation record within the CRL. A single record is identified by the CrlRecordIndex, which is returned by the function CSSM_CL_IsCertInCachedCrl() (CSSM API) or CL_IsCertInCachedCrl() (CL SPI). If no record index is supplied, the search is initiated from the beginning of the CRL.
The CRL can be signed or unsigned. This function does not perform any signature verification on the CRL fields or the CRL-records. Each CRL-record may be digitally signed when it is added to the CRL using the function CSSM_CL_CrlAddCert() (CSSM API) or CL_CrlAddCert() (CL SPI). The caller can examine fields in the CRL and CRL-records at any time using this function.
The CrlField OID can identify a single occurrence of a set of CRL fields, or multiple occurrences of a set of CRL fields. If the CrlField OID matches more than one occurrence, this function outputs the total number of matches and a ResultsHandle to be used as input to CSSM_CrlGetNextFieldValue() (CSSM API) or CrlGetNextFieldValue() (CL SPI) to retrieve the remaining matches. The first match is returned as the return value of this function..
This function determines the complete set of matches. The number of matches and the selected field values do not change between this function and subsequent calls to CSSM_CL_CrlGetNextFieldValue() (CSSM API) or CL_CrlGetNextFieldValue() (CL SPI).

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() (CSSM API) or CL_FreeFieldValue() (CL SPI) 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 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 for the CSSM API
CL_CrlGetNextCachedFieldValue for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CrlGetNextCachedFieldValue
    (CSSM_CL_HANDLE CLHandle, 
    CSSM_HANDLE ResultsHandle,
    CSSM_DATA_PTR *FieldValue) 

SPI:
CSSM_RETURN CSSMCLI 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() (CSSM API) or CL_CrlGetFirstCachedFieldValue() (CL SPI) initiates the process and returns a ResultsHandle identifying the size and values contained in the result set. The CSSM_CL_CrlGetNextCachedFieldValue() (CSSM API) or CL_CrlGetNextCachedFieldValue() (CL SPI) 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() (CSSM API) or CL_CrlGetFirstCachedFieldValue() (CL SPI) 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() (CSSM API) or CL_CrlGetFirstCachedFieldValue() (CL SPI). 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() (CSSM API) or CL_FreeFieldValue() (CL SPI) 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 Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CL_INVALID_RESULTS_HANDLE
CSSMERR_CL_NO_FIELD_VALUES

NAME

CSSM_CL_CrlGetAllCachedRecordFields for the CSSM API
CL_CrlGetAllCachedRecordFields for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CrlGetAllCachedRecordFields
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE CrlHandle, 
    const CSSM_DATA *CrlRecordIndex,
    uint32 *NumberOfFields,
    CSSM_FIELD_PTR *Fields) 

SPI:
CSSM_RETURN CSSMCLI 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() (CSSM API) or CL_IsCertInCachedCrl() (CL SPI).
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() (CSSM API) or CL_CrlAddCert() (CL SPI). 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() (CSSM API) or. CL_FreeFields() (CL SPI).

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

CSSMERR_CL_INVALID_CACHE_HANDLE
CSSMERR_CL_INVALID_CRL_INDEX

NAME

CSSM_CL_CrlAbortCache for the CSSM API
CL_CrlAbortCache for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CrlAbortCache
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE CrlHandle) 

SPI:
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() (CSSM API) or CL_CrlCache() (CL SPI). 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 Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CL_INVALID_CACHE_HANDLE

NAME

CSSM_CL_CrlDescribeFormat for the CSSM API
CL_CrlDescribeFormat for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_CrlDescribeFormat
    (CSSM_CL_HANDLE CLHandle,
    uint32 *NumberOfOids,
    CSSM_OID_PTR *OidList)

SPI:
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 CSSM_CL_CrlGetFirstFieldValue() (CSSM API) or CL_CrlGetFirstFieldValue() (CL SPI) 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 definition for the Certificate Library pass-through extensibility function is presented in this section.

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

CSSM_CL_PassThrough for the CSSM API
CL_PassThrough for the CL SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_CL_PassThrough
    (CSSM_CL_HANDLE CLHandle,
    CSSM_CC_HANDLE CCHandle,
    uint32 PassThroughId,
    const void *InputParams,
    void **OutputParams)

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

Overview

Certificates and CRLs

Application and Certificate Library Interaction

Operations on Certificates

Add-In Module

Certificate Life Cycle

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