Common Security: CDSA and CSSM - Certificate Library Services API

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

Certificate Library Services API

Overview

The primary purpose of a Certificate Library (CL) module is to perform syntactic manipulations on a specific certificate format, and its associated certificate revocation list (CRL) format. These manipulations include the complete life cycle of a certificate and the keypair associated with that certificate. Certificates and CRLs are related by the life cycle model and by the data formats used to represent them. For this reason, these objects should be manipulated by a single, cohesive library.

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.

Certificate Life Cycle

The Certificate Library provides life cycle support and format-specific manipulation 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 of the certificate. Verification of this signature is the mechanism used to establish trust in the identity and authorizations recorded in the certificate. Certificates are signed by one or more other certificates. Root certificates are self-signed. The syntactic process of signing corresponds to 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 entire status and 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 used.

After registration, keying material is generated and certificates are 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 has forgotten the passphrase required to use the certificate for signing or for decryption
Update-issuing a new public/private key pair when a legitimate pair has or will expire soon.

Figure: Certificate Life Cycle States and Actions

The CSSM Certificate Library APIs define four functions supporting certificate creation and update, two functions supporting certificate verification, seven functions supporting certificate parsing, ten functions supporting certificate revocation and CRL manipulation, and four functions supporting certificate recovery. The certificate library passthrough function is defined so library implementors can extend the library with additional services (as appropriate).

Application and Certificate Library Interaction

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

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

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

Operations on Certificates

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

Certificate operations
Certificate revocation list operations
Extensibility functions

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

Data Structures

This chapter describes the data structures which may be passed to or returned from a Certificate Library function. They will be used by applications to prepare data to be passed as input parameters into CSSM API function calls which will be passed without modification to the appropriate CL. The CL is then responsible for interpreting them and returning the appropriate data structure to the calling application via CSSM. These data structures are defined in the header file <cssmtype.h>, distributed with CSSM.

CSSM_CL_HANDLE

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

typedef 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;

Definition

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

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_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 
                                        certificate */
    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.

typedef struct cssm_cl_ca_productinfo {
    CSSM_VERSION StandardVersion; /* Ver 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 supported by the CA service.
CertType: An enumerated value specifying the certificate 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.

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

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 chapter describes the function prototypes and error codes supported by a Certificate Library module for operations on certificates. The error codes given in this chapter constitute the generic error codes which are defined by CSSM for use by all certificate libraries in describing common error conditions. A certificate library may also define and return vendor-specific error codes. Applications must consult vendor-supplied documentation for the specification and description of any error codes defined outside of this specification.

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

Certificate Revocation List Operations

This chapter describes the function prototypes and error codes supported by a Certificate Library module for operations on certificate revocation lists (CRLs). The error codes given in this chapter constitute the generic error codes which are defined by CSSM for use by all certificate libraries in describing common error conditions. A certificate library may also define and return vendor-specific error codes. The error codes defined by CSSM are considered to be comprehensive and few if any vendor-specific codes should be required. Applications must consult vendor-supplied documentation for the specification and description of any error codes defined outside of this specification. The manpages for Certificate Revocation List Operations can be found at the end of this chapter.

Extensibility Functions

The manpages for Certificate Library 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