Common Security: CDSA and CSSM - Certificate Library Interface

Common Security: CDSA and CSSM
Copyright © 1997 The Open Group

Certificate Library Interface

Overview

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

Certificate operations fall into four general areas:

Certificate Authority requests-These operations include requesting certificate registration forms, requesting certificate issuance, and recovering certificates and their associated key pairs. The certificate library is expected to encapsulate the format and mechanisms required to communicate with the Certificate Authorities it supports.
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.
Certificate format translation-In the heterogeneous world of multiple certificate formats, CL modules may want to provide the service of translating between certificate formats. This translation would involve mapping the fields from one certificate format into another certificate format, while maintaining the original format for integrity verification purposes. For example, an X509V1 certificate may be exported to a SDSI format or imported into an X509V3 certificate, but the original data and signature must somehow be maintained. The supported import and export types are registered with CSSM as part of CL installation.

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

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

Operations on certificate revocation lists are comprised of Certificate Authority requests, 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. CRLs may be requested from the signing Certificate Authority. The contents of the CRL can be queried for all of its revocation records, specific certificates, or individual CRL fields.

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

Certificate Operations

This section provides a more detailed look at the functions that compose the certificate operations in the CLI. It gives a high-level overview of each function's expected operation, its parameter definitions where necessary, and potential differences between CL module implementations.

CL_CertRequest(): This function will submit a certificate creation request to a Certificate Authority (CA) process. A certificate template must be provided to specify the initial values for the certificate. As the certificate issuer, the CA process may add default field values prior to signing the new certificate. The private key associated with the certificate will be stored in the CSP module identified by the caller. This function returns a ReferenceIdentifier and an EstimatedTime (specified in seconds). The estimated time defines the expected certificate creation time, after which the caller must use CL_CertRetrieve, with the reference identifier, to obtain the signed certificate.
CL_CertRetrieve(): This function returns the certificate created in response to a CL_CertRequest function call. A reference identifier denotes the corresponding CL_CertRequest call. The caller may be required to provide additional authentication information to retrieve the certificate. This function returns the signed certificate and stores the associated private key (generated locally or remotely) in the CSP specified in CL_CertRequest.If the CA requires additional time prior to certificate retrieval, this function will return an updated EstimatedTime parameter.
CL_RegistrationFormRequest(): This function returns a blank registration form from a Registration Authority (RA) process. The RA process can be local or remote. The CL module incorporates knowledge of the name, location, and interface protocol for communication with the RA.
CL_CertMultiSignRequest(): This function submits a request to a Certificate Authority (CA) process to add one or more signatures to an existing certificate. The signing operation may be performed locally or remotely. The SignScope parameter defines the set of certificate fields that are to be included in the signing process. This function returns a ReferenceIdentifier and an EstimatedTime (specified in seconds). The estimated time defines the expected signing time, after which the caller must use CL_CertMultiSignRetrieve, with the reference identifier, to obtain the multiply-signed certificate.
CL_CertMultiSignRetrieve(): This function returns the multiply-signed certificate created in response to a CL_CertMultiSignRequest function call. A reference handle identifies the corresponding CL_CertMultiSignRequest. If the CA requires additional time prior to certificate retrieval, this function will return an updated EstimatedTime parameter.
CL_CertRecoveryRequest(): This function submits a certificate recovery request to a Certificate Authority (CA) process (or other trusted backup facility) to prepare for the recovery of a set of certificates and their associated private keys. The caller can specify one or more certificate field values to limit the set of certificates selected for potential recovery. This function returns a ReferenceIdentifier and an EstimatedTime (specified in seconds). The estimated time defines the expected certificate recovery time, after which the caller must use CL_CertRecoveryRetrieve, with the reference identifier, to obtain the set of recovered certificates from the CA process.
CL_CertRecoveryRetrieve(): This function obtains the set of certificates recovered in response to a CL_CertRecoveryRequest call. A reference identifier denotes the corresponding CL_CertRecoveryRequest. The caller may be required to provide additional authentication information to recover the certificates. If the CA requires additional time prior to certificate recovery, this function will return an updated EstimatedTime parameter.
CL_CertRecover(): This function returns a certificate from a cache of certificates obtained by the CL_CertRecoveryRetrieve function. The certificate to be retrieved is specified by the CacheIndex parameter, which is a simple counter from one to the number of certificates in the cache. This function has no effect on the private key associated with the recovered certificate. Recovery of the private key can be performed using the function CL_CertKeyRecover.
CL_CertKeyRecover(): This function recovers the private key associated with a certificate and securely stores that key in the specified cryptographic service provider. The key is retrieved from the cache specified by the CacheIndex parameter, which is a simple counter from one to the number of certificates in the cache. To selectively recover private keys from the cache, the function CL_CertRecover and be used to determine the appropriate CacheIndex to use when recovering the associated private key.
CL_CertAbortRecovery(): This function terminates the iterative process of recovering certificates and their associated private keys from a cache of certificates. This function destroys all intermediate state and secret information used during the certificate and key recovery process, and must be called even if all certificates and their associated private keys have been recovered from the cache.
CL_CertVerify(): This function will verify the signer certificate's signature on the subject certificate. The cryptographic context handle indicates the algorithm and parameters to be used for verification. If the certificate library module supports field signing, the VerifyScope parameter may be used to identify the fields that were signed.
CL_CertGetFirstFieldValue(): This function returns the first field in the certificate that matches the input OID. If the certificate contains more than one instance of the requested OID, the CL module will return a handle to be used to obtain the additional instances and a count of the total number of instances of this OID in the certificate. The application obtains the additional matching instances by repeated calls to CL_CertGetNextFieldValue.
CL_CertGetNextFieldValue(): This function returns the next field that matched the OID given in the CL_CertGetFirstFieldValue function. It will only be supported by certificate library modules that allow multiple instances of an OID in a single certificate.
CL_CertAbortQuery(): This function releases the handle that was assigned by the CL_CertGetFirstFieldValue function to identify the results of a certificate query. It will only be supported by certificate library modules that allow multiple instances of an OID in a single certificate.
CL_CertGetKeyInfo(): This function retrieves the public key information stored in the certificate. In most certificate formats this includes multiple fields, but it may not include all of the fields defined by the CSSM_KEY data structure. Each CL module is responsible for making known which portions of the CSSM_KEY data structure will be returned.
CL_CertGetAllFields(): This function returns a list of all the fields in the input certificate, as described by their OID/value pairs.
CL_CertImport(): This function translates a certificate from a foreign certificate type to the native certificate type manipulated by the CL module.
CL_CertExport(): This function translates a certificate from the native certificate type manipulated by the CL module into a foreign certificate type.
CL_CertDescribeFormat(): This function returns a list of object identifiers corresponding to the data objects composing the CL module's native certificate format.

Certificate Revocation List Operations

This section provides a more detailed look at the functions that compose the certificate revocation list operations in the CLI. This section gives a high-level overview of each function's expected operation, its parameter definitions where necessary, and potential differences between CL module implementations.

CL_CrlCreateTemplate(): This function creates a CRL in the CL module's native CRL format based on the OID/value pairs provided by the application. The CL module makes its supported OIDs available to the application via the CrlTemplate registered with CSSM and via the CL_CrlDescribeFormat function. The CL Module is responsible for indicating which fields are required to create a CRL, or which fields cannot be set using this function. The returned CRL will not be a valid CRL until it has been signed.
CL_CrlRequest(): This function submits a request to a Certificate Authority (CA) process to issue the most current version of a CRL of a specified name. This function returns a ReferenceIdentifier and an EstimatedTime (specified in seconds). The estimated time defines the expected closing, signing and distribution time of the CRL, after which the caller must use the CL_CrlRetrieve, with the reference identifier, to obtain the CRL.
CL_CrlRetrieve(): This function returns the CRL closed and issued in response to a CL_CrlRequest function call. A reference identifier denotes the corresponding CL_CrlRequest call. If the CA requires additional time prior to CRL retrieval, this function will return an updated EstimatedTime parameter.
CL_CrlSetFields(): This function sets the fields of an existing CRL to new values, based on the OID/value pairs provided by the application. The CL Module is responsible for indicating any set of fields that must be or cannot be set using this function, and for specifying module-specific behavior such as overwriting existing fields, modifying extensions, or modifying CRL records. This operation is valid only if the CRL has not been closed by the process of signing the CRL (that is, execution of the function CSSM_CL_CrlSign). Once the CRL has been signed, fields cannot be changed.
CL_CrlAddCert(): 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 a list of OID/value input pairs provided by the application. A CL module that supports field signing would use the revoker's certificate to sign the new record. The updated CRL is returned to the calling application. The CL Module is responsible for indicating any set of fields that must be or cannot be set using this function. This operation is valid only if the CRL has not been closed by the process of signing the CRL (that is, execution of the function CSSM_CL_CrlSign). Once the CRL has been signed, entries cannot be added or removed.
CL_CrlRemoveCert(): This function reinstates the input certificate by removing the record representing the certificate from the CRL. The updated CRL is returned to the calling application. This operation is valid only if the CRL has not been closed by the process of signing the CRL (that is, execution of the function CSSM_CL_CrlSign). Once the CRL has been signed, entries cannot be added or removed.
CL_CrlSign(): This function will create a digital signature for the entire CRL using the signer's certificate. The cryptographic context handle indicates the algorithm and parameters to be used for signing. The field or fields of the CRL that should be signed will depend on the implementation of the CL module. A CL module may choose to ignore the SignScope parameter if the fields to be signed are pre-defined. A CL module that supports field signing would sign the subset of fields specified by the SignScope parameter. The CL module may refuse to sign the CRL if a pre-defined set of fields do not contain valid data. Typically, this function will be used to sign the entire CRL prior to distributing it to other systems. The signature will be used to quickly detect tampering of the CRL. CRL queries may be performed on both signed and unsigned CRLs. Once the CRL has been signed it may not be modified. This means that entries cannot be added or removed from the CRL through application of the CSSM_CL_CrlAddCert or CSSM_CL_CrlRemoveCert operations. A signed CRl can be verified, applied to a data store, and searched for values.
CL_CrlVerify(): This function will check the signer certificate's signature on the subject CRL to determine whether the CRL has been tampered with and whether the signer's certificate was actually used to sign the CRL. The cryptographic context handle indicates the algorithm and parameters to be used for verification. If the certificate library supports field signing on a CRL, the VerifyScope may be used to identify the fields that were signed.
CL_IsCertInCrl(): This function searches the CRL for a record corresponding to the input certificate.
CL_CrlGetFirstFieldValue(): This function returns the first field in the CRL that matches the input OID. It is likely that the CRL will support multiple instances of an OID that represents a revoked certificate record. If an application requests an OID that has multiple instances within the CRL, a results handle and a count of the number of matching instances will be returned along with the first instance of the OID. The application uses the results handle to obtain the additional matching instances by repeated calls to CL_CrlGetNextFieldValue. For example, given the OID for "revocation record", this function would return the first revocation record in the CRL. The remaining revocation records could be obtained by successive calls to CL_CrlGetNextFieldValue.
CL_CrlGetNextFieldValue(): This function returns the next field associated with the input results handle (obtained via an initial call to CSSM_CL_CrlGetFirstFieldValue).
CL_CrlAbortQuery(): This function releases a handle that was assigned by the CL_CrlGetFirstFieldValue function to identify the results of a CRL query, and allows the CL to release all intermediate state information associated with the get operation.
CL_CrlDescribeFormat(): This function returns a list of the object identifiers that represent the fields in the certificate revocation list format supported by the CL module.

Extensibility Functions

CL_PassThrough(): This performs the CL module-specific function indicated by the operation ID. The operation ID specifies an operation that the CL has exported for use by an application or module. Such operations should be specific to the data format of the certificates and CRLs manipulated by the CL module.

Data Structures

This section 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 uint32 CSSM_CL_HANDLE

CSSM_CERT_TYPE

This variable specifies the type of certificate format supported by a certificate library and the types of certificates understood for import and export. They are expected to define such well-known certificate formats as X.509 Version 3 and SDSI as well as custom certificate formats. The list of enumerated values can be extended for new types by defining a label with an associated value greater than CSSM_CL_CUSTOM_CERT_TYPE.

typedef enum cssm_cert_type {
    CSSM_CERT_UNKNOWN =  0x00,
    CSSM_CERT_X_509v1 =  0x01,
    CSSM_CERT_X_509v2 =  0x02,
    CSSM_CERT_X_509v3 =  0x03,
    CSSM_CERT_PGP =      0x04,
    CSSM_CERT_SPKI =     0x05,
    CSSM_CERT_SDSIv1 =   0x06,
    CSSM_CERT_Intel =    0x08,
    CSSM_CERT_X_509_ATTRIBUTE = 0x09, /* X.509 attribute cert */
    CSSM_CERT_X9_ATTRIBUTE = 0x0A,    /* X9 attribute cert */
    CSSM_CERT_LAST =     0x7FFF,
} CSSM_CERT_TYPE, *CSSM_CERT_TYPE_PTR;

/* Applications wishing to define their own custom certificate
 * type should create a random uint32 whose value is greater than
 * the CSSM_CL_CUSTOM_CERT_TYPE */
#define CSSM_CL_CUSTOM_CERT_TYPE  0x08000

CSSM_CERT_ENCODING

This variable specifies the certificate encoding format supported by a certificate library.

typedef enum cssm_cert_encoding {
    CSSM_CERT_ENCODING_UNKNOWN =  0x00,
    CSSM_CERT_ENCODING_CUSTOM  =  0x01,
    CSSM_CERT_ENCODING_BER     =  0x02,
    CSSM_CERT_ENCODING_DER     =  0x03,
    CSSM_CERT_ENCODING_NDR     =  0x04,
} CSSM_CERT_ENCODING, *CSSM_CERT_ENCODING_PTR;

CSSM_CERT_BUNDLE_TYPE

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

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_LAST = 0x7FFF
} CSSM_CERT_BUNDLE_TYPE;

/* Applications wishing to define their own custom certificate
 * BUNDLE type should create a random uint32 whose value
 * is greater than the 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;

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 itself is a signed opaque aggregate of certificates.

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

BundleHeader: Information describing the format and encoding of the bundle contents.
Bundle: A signed opaque aggregate of certificates.

CSSM_OID

The object identifier (OID) is used to hold an identifier for the data types and data structures which comprise the fields of a certificate or CRL. The underlying representation and meaning of the identifier is defined by the certificate library module. Popular representations include:

A character string in a character set native to the platform
A DER encoded X.509 OID that must be parsed
An S-expression that must be evaluated
An enumerated value that is defined in header files supplied by the CLM

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_CRLTYPE_UNKNOWN,
    CSSM_CRLTYPE_X_509v1,
    CSSM_CRLTYPE_X_509v2,
} 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
} CSSM_CRL_ENCODING, *CSSM_CRL_ENCODING_PTR;

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_ESTIMATED_TIME_UNKNOWN

The value used by an authority or process to indicate that an estimated completion time cannot be determined.

#define CSSM_ESTIMATED_TIME_UNKNOWN -1

CSSM_CA_SERVICES

This bit mask defines the additional certificate-creation-related services that an issuing Certificate Authority (CA) can offer. Such services include (but are not limited to) archiving the certificate and keypair, publishing the certificate to one or more certificate directory services, and sending automatic, out-of-band notifications of the need to renew a certificate. A CA may offer any subset of these services. Additional services can be defined over time.

typedef uint32 CSSM_CA_SERVICES;
/*  bit masks for additional CA services at cert enroll  */
#define CSSM_CA_KEY_ARCHIVE  0x0001 /* archive cert and keys */
#define CSSM_CA_CERT_PUBLISH  0x0002 /* cert in directory 
                                        service */
#define CSSM_CA_CERT_NOTIFY_RENEW 0x0004 /* notify at renewal 
                                        time */
#define CSSM_CA_CERT_DIR_UPDATE 0x0008 /* multi-signed cert to 
                                        dir svc */
#define CSSM_CA_CRL_DISTRIBUTE 0x0010 /* push CRL to everyone */

CSSM_CL_CA_CERT_CLASSINFO

This structure describes a class of certificates issued by a given CA.

typedef struct cssm_cl_ca_cert_classinfo {
   CSSM_STRING CertClassName; /* Name of the class of cert */
   CSSM_DATA CACert;   /* CA cert used to sign this cert class */
} CSSM_CL_CA_CERT_CLASSINFO, *CSSM_CL_CA_CERT_CLASSINFO_PTR;

Definition

CertClassName: The CA's description of the certificate class, including its name.
CACert: The CA's cert used to sign issued certificates of this cert class.

CSSM_CL_CA_PRODUCTINFO

This structure holds product information about a backend Certificate Authority (CA) that is accessible to the CL module. The CL module vendor is not required to provide this information, but may choose to do so. For example, a CL module that implements upstream protocols to a particular type of commercial CA can record information about that CA service in this structure.

typedef struct cssm_cl_ca_productinfo {
    CSSM_VERSION StandardVersion;    /* Version of standard this 
                                        product conforms to */
    CSSM_STRING StandardDescription; /* Desc of standard this 
                                        product conforms to */
    CSSM_VERSION ProductVersion;     /* Version of wrapped 
                                        product/library */
    CSSM_STRING ProductDescription;  /* Description of wrapped 
                                        product/library */
    CSSM_STRING ProductVendor;       /* Vendor of wrapped 
                                        product/library */
    CSSM_NET_PROTOCOL NetworkProtocol;  /* The network protocol 
                                   supported by the CA service */
    CSSM_CERT_TYPE CertType;         /* Type of certs 
                                        supported by CA */
    CSSM_CERT_ENCODING CertEncoding;  /* Cert encoding supported 
                                         by CA */
    CSSM_CRL_TYPE CrlType;  /* CRL type supported by CA */
 
    CSSM_CRL_ENCODING CrlEncoding;  /* CRL encoding supported by CA */
 
    CSSM_CA_SERVICES AdditionalServiceFlags; /* Mask of 
                      additional services a caller can request */
    uint32 NumberOfCertClasses;      /* Number of different 
                        cert types or classes the CA can issue */
    CSSM_CL_CA_CERT_CLASSINFO_PTR CertClasses /* Information 
                      about the cert classes issued by this CA */
} CSSM_CL_CA_PRODUCTINFO, *CSSM_CL_CA_PRODUCTINFO_PTR;

Definition

StandardVersion: If this product conforms to an industry standard, this is the version number of that standard.
StandardDescription: If this product conforms to an industry standard, this is a description of that standard.
ProductVersion: Version number information for the actual product version used in this version of the DL module.
ProductDescription: A string describing the product.
ProductVendor: The name of the product vendor.
NetworkProtocol: The name of the network protocol.
CertType: An enumerated value specifying the certificate and type that the CA manages.
CertEncoding: An enumerated value specifying the certificate encoding that the CA manages
CrlType: An enumerated value specifying the CRL type that the CA manages
CrlEncoding: An enumerated value specifying the CRL encoding that the CA manages
AdditionalServiceFlags: A bit mask indicating the additional services a caller can request from a CA (as side effects and in conjunction with other service requests.
NumberOfCertClasses: The number of classes or levels of Certificates managed by this CA.
CertClasses: An array of information about the classes of certificates supported by this CA.

CSSM_CL_ENCODER_PRODUCTINFO

This structure holds product information about embedded products that a CL module uses to provide its services. The CL module vendor is not required to provide this information, but may choose to do so. For example, a CL module that manipulates X.509 certificates may embed a third party tool that parses, encodes, and decodes those certificates. The CL module vendor can describe such embedded products using this structure.

typedef struct cssm_cl_encoder_productinfo {
    CSSM_VERSION StandardVersion; /* Ver of standard the product 
                                        conforms to */
    CSSM_STRING StandardDescription; /* Desc of standard this 
                                        product conforms to */
    CSSM_VERSION ProductVersion;  /* Version of wrapped product 
                                        or library */
    CSSM_STRING ProductDescription;  /* Description of wrapped 
                                        product or library */
    CSSM_STRING ProductVendor;       /* Vendor of wrapped product 
                                        or library */
    CSSM_CERT_TYPE CertType; /* Type of certs supported by encoder */
 
    CSSM_CRT_TYPE CrlType; /* Type of CRLs supported by encoder */
 
    uint32 ProductFlags;             /* Mask of selectable encoder 
                               features actually used by the CL */
} CSSM_CL_ENCODER_PRODUCTINFO, *CSSM_CL_ENCODER_PRODUCTINFO_PTR;

Definition

StandardVersion: If this product conforms to an industry standard, this is the version number of that standard.
StandardDescription: If this product conforms to an industry standard, this is a description of that standard.
ProductVersion: Version number information for the actual product version used in this version of the DL module.
ProductDescription: A string describing the product.
ProductVendor: The name of the product vendor.
CertType: An enumerated value specifying the certificate type that the encoder processes (if limited to one type).
CrlType: An enumerated value specifying the CRL type that the encoder processes (if limited to one type).
ProductFlags: A bit mask indicating any selectable features of the embedded product that the CL module selected to use.

CSSM_CL_WRAPPEDPRODUCTINFO

This structure lists the set of embedded products and the CA service used by the CL module to implement its services. The CL module is not required to provide any of this information, but may choose to do so.

typedef struct cssm_cl_wrappedproductinfo {
         /* List of encode/decode/parse libraries embedded 
                                             in the CL module */
    CSSM_CL_ENCODER_PRODUCTINFO_PTR EmbeddedEncoderProducts;
         /* library product description */
    uint32 NumberOfEncoderProducts;
         /* number of encode/decode/parse libraries used in CL */
         /* List of CAs accessible to the CL module */
    CSSM_CL_CA_PRODUCTINFO_PTR AccessibleCAProducts;
         /* CA product description*/
    uint32 NumberOfCAProducts;
         /* Number of accessible CAs */
} CSSM_CL_WRAPPEDPRODUCTINFO, *CSSM_CL_WRAPPEDPRODUCTINFO_PTR;

Definition

EmbeddedEncoderProducts: An array of structures that describe each embedded encoder product used in this CL module implementation.
NumberOfEncoderProducts: A count of the number of distinct embedded certificate encoder products used in the CL module implementation.
AccessibleCAProducts: An array of structures that describe each type of Certificate Authority accessible through this CL module implementation.
NumberOfCAProducts: A count of the number of distinct CA products described in the array AccessibleCAProducts.

CSSM_CLSUBSERVICE

This structure contains the static information that describes a certificate library sub- service. This information is stored in the CSSM registry when the CL module is installed with CSSM. CSSM checks the integrity of the CL module description before using the information. A certificate library module may implement multiple types of services and organize them as sub-services. For example, a CL module supporting X.509 encoded certificates may organize its implementation into three sub-services, one for X.509 version 1, a second for X.509 version 2, and a third for X.509 version 3. Most certificate library modules will implement exactly one sub-service.

The descriptive information stored in these structures can be queried using the function CSSM_GetModuleInfo() and specifying the certificate library module GUID.

typedef struct cssm_clsubservice {
    uint32 SubServiceId;
    CSSM_STRING Description;
    CSSM_CERT_TYPE CertType;
    CSSM_CERT_ENCODING CertEncoding;
    uint32 NumberOfBundleInfos;
    CSSM_CERT_BUNDLE_HEADER_PTR BundleInfo; /* first is default 
                                                       value */
    CSSM_USER_AUTHENTICATION_MECHANISM AuthenticationMechanism;
    uint32 NumberOfTemplateFields;
    CSSM_OID_PTR CertTemplate;
    uint32 NumberOfTranslationTypes;
    CSSM_CERT_TYPE_PTR CertTranslationTypes;
    CSSM_CL_WRAPPEDPRODUCTINFO WrappedProduct;
} CSSM_CLSUBSERVICE, *CSSM_CLSUBSERVICE_PTR;

Definition

SubServiceId: A unique, identifying number for the sub-service described in this structure.
Description: A string containing a description name or title for this sub-service.
CertType: An identifier for the type of certificate.
CertEncoding: An identifier for the certificate encoding format.
NumberOfBundleInfos: The number of distinct bundle type/encoding pairs supported by the certificate library module.
BundleInfo: A pointer to a list of bundle header structures. Each structure defines a bundle type and encoding supported by the certificate library module. The first bundle header is the default for the library.
AuthenticationMechanism: An enumerated value defining the credential format accepted by the CL module. Authentication credentials may be required when requesting certificate creation or other CL functions. Presented credentials must be of the required format.
NumberOfTemplateFields: The number of certificate template fields. This number also indicates the length of the CertTemplate array.
CertTemplate: A pointer to an array of tag/value pairs which identify the field values of a certificate.
NumberOfTranslationTypes: The number of certificate types that this certificate library add-in module can import and export. This number also indicates the length of the CertTranslationTypes array.
CertTranslationTypes: A pointer to an array of certificate types. This array indicates the certificate types that can be imported into and exported from this certificate library module's native certificate type.
WrappedProduct: Descriptions of the set of embedded products used by this module and the CA services available via this module.

Certificate Operations

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

The manpages for Certificate Operations can be found at the end of this chapter.

Certificate Revocation List Operations

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

The manpages for Certificate Revocation List Operations can be found at the end of this chapter.

Extensibility Functions

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

The manpages for Extensibility Functions can be found at the end of this chapter.

Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.
You should also read the legal notice explaining the terms and conditions relating to the CDSA documentation.

Contents

Next section

Index