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