Overview#
The following document is based upon the Netscape Certificate Management System 6.1 Packaging Design Software Design Specification by Thomas Kwan (last updated April 16, 2002), and outlines the class path structure of Netscape Certificate Management System’s (CMS)’s public external inferfaces as well as its private internal interfaces.
The details provided below represent the historical “package” layout (think ‘jar’, ‘class path’, and ‘classes’ rather than RPM) utilized by Dogtag Certificate System (see http://pki.fedoraproject.org/wiki/PKI_History Certificate System History (Dogtag Ancestors) for historical references).
Some of the content has been altered for clarity. For example, the use of “package” has been replaced by “jar”, “class path”, and/or “classes” to distinguish the content from the common modern day usage of “package” referring to RPMS. Additionally, it should be understood that ALL references to an RA refer to a legacy Java implementation of a Registration Authority that was utilized in the CMS 6.0 timeframe (it does NOT refer to the current RA that exists as an Apache plug-in written primarily in Perl).
Goals and Guidelines#
The goal of separating CMS into multiple jars is that jars can be updated and distributed individually.
For example, the CMS team may want to ship the public external implementation [certsrv.jar, cmsutil.jar, and cms.jar] to CMS developers, while excluding the private internal implementation [cmscore.jar].
Policies and Tactics#
Public Interface Changes#
Beginning with version 6.0 of CMS, the functions or methods defined within the public interface classes shall not be altered without approval from the CMS team. Neither they, nor the signature of the methods shall be altered, since any changes to these classes may lead to future incompatibilities of the plug-ins.
CMS engineers, however, are allowed to add new methods that extend the capabilities with the understanding that all new methods shall be well-documented.
Detailed System Design#
CMS has been organized into the following jars (presented in their build sequence order):
Netscape’s Utility Jar [nsutil.jar]
CMS’s Utility Jar [cmsutil.jar]
CMS’s Public Interface Jar [certsrv.jar]
CMS’s Servlet Jar [cms.jar]
CMS’s Resource Bundle Jar [cmsbundle.jar]
CMS’s Private Implementation Jar [cmscore.jar]
CMS’s Configuration Jar [certsetup.jar]
CMS’s Command-Line Tool Jar [cmstools.jar]
Note that all CMS public external interfaces and utilities jars are built prior to the CMS private internal implementation jar. This build sequence ensures that public classes such as plug-ins will have no dependency on the private core implementation.
The following diagram illustrates the CMS 6.x design pictorially:
apidep.png#
Imported Binary Classes#
Netscape’s Utility Jar [nsutil.jar]#
This jar includes all the java classes that provide the basic X.509 and Public-Key Cryptography Standards (PKCS) implementations, and provides external developers with a way to build X.509 extensions.
This jar includes the following class paths:
Class Path |
Description |
|---|---|
netscape.net |
This class path includes classes that support the Simple Mail Transfer Protocol (SMTP) implemented in netscape.net.smtp.*. |
netscape.net.smtp |
This class path includes classes that implement SMTP for email communication. |
netscape.security.acl |
This class path includes classes that set of access control lists (ACL)s for the security framework. |
netscape.security.extensions |
This class path includes classes that implement additional Public-Key Infrastructure X.509 (PKIX) extensions. |
netscape.security.pkcs |
This class path includes classes that set of PKCS implementations. |
netscape.security.provider |
This class path includes a set of classes that implement key provider. |
netscape.security.spec |
This class path includes classes for the key spec implementation. |
netscape.security.util |
This class path includes a set of classes for Distinguished Encoding Rules (DER) encoding utilities. |
netscape.security.wTLS |
This class path includes classes for the Wireless Transport Layer Security (wTLS) certificate implementation. |
netscape.security.x509 |
This class path includes classes for X.509 certificate implementation. |
Note that this jar needs to be dropped eventually because the original implementation is from Sun Microsystems. This jar shall not be developed further except for bug fixes.
CMS Public External Interfaces and Utilities#
CMS’s Utility Jar [cmsutil.jar]#
This jar includes all the java classes that provide the basic building-blocks or utilities for CMS core implementation. This jar should not have any dependencies on netscape.security.* nor netscape.net.*.
This jar includes the following class paths:
Class Path |
Description |
|---|---|
com.netscape.cmsutil.http |
This class path includes classes that implement the secure Hypertext Transfer Protocol (HTTP) client. |
com.netscape.cmsutil.net |
This class path includes classes that define the socket factory framework interfaces. |
com.netscape.cmsutil.ocsp |
This class path includes classes for an Online Certificate Status Protocol (OCSP) implementation (built on top of Java Security Services (JSS) DER encoding/decoding framework). |
com.netscape.cmsutil.radius |
This class path includes classes that implement the Remote Authentication Dial In User Service (RADIUS) protocol as defined in RFC2138. |
com.netscape.cmsutil.scep |
This class path includes classes that implement Cisco’s Simple Certificate Enrollment Protocol (SCEP). |
com.netscape.cmsutil.util |
This class path includes classes that implement utility functions that are useful. |
This jar shall be well documented, and serve as the public external utilities for CMS.
Eventually, this jar should totally replace Netscape’s Utility jar.
CMS’s Public Interface Jar [certsrv.jar]#
This jar includes all of the java interfaces and base classes that an external developer may need for writing CMS plug-ins.
This jar includes the following class paths:
Class Path |
Description |
|---|---|
com.netscape.certsrv.acls |
A set of classes that implement interfaces for ACL plug-ins. |
com.netscape.certsrv.apps |
A set of classes that implement interfaces that encapsulates the CMS framework. |
com .netscape.certsrv.authentication |
A set of classes that implement interfaces for authentication plug-ins. |
com.netscape.certsrv.authority |
A set of classes that implement interfaces that encapsulates the authority subsystem. |
co m.netscape.certsrv.authorization |
A set of classes that implement interfaces that encapsulates the authorization framework. |
com.netscape.certsrv.base |
A set of classes that implement basic and common objects for the CMS framework. |
com.netscape.certsrv.ca |
A set of classes that implement interfaces for Certificate Authority (CA). |
com.netscape.certsrv.client |
A set of classes that implement interfaces that encapsulates the administration connection. |
com.netscape.certsrv.common |
A set of classes that implement constants that define the protocol between the console and the server. |
com.netscape.certsrv.connector |
A set of classes that implement interfaces for connectors. |
com.netscape.certsrv.dbs |
A set of classes that implement interfaces for database plug-ins. |
com.netscape.certsrv.evaluators |
A set of classes that implement interfaces for the access control evaluator in the authorization framework. |
com.netscape.certsrv.extensions |
A set of classes that implement interfaces for creating extensions from HTTP input. |
com.netscape.certsrv.jobs |
A set of classes that implement interfaces for job plug-ins. |
com.netscape.certsrv.kra |
A set of classes that implement interfaces for Key Recovery Authority (KRA) (also known as Data Recovery Manager (DRM)). |
com.netscape.certsrv.ldap |
A set of classes that implement interfaces for Lightweight Directory Access Protocol (LDAP) connection pool. |
com.netscape.certsrv.logging |
A set of classes that implement interfaces for logging plug-ins. |
c om.netscape.certsrv.notification |
A set of classes that implement interfaces for notification plug-ins. |
com.netscape.certsrv.ocsp |
A set of classes that implement interfaces for OCSP Authority. |
com.netscape.certsrv.policy |
A set of classes that implement interfaces for policies. |
com.netscape.certsrv.publish |
A set of classes that implement interfaces that encapsulates the LDAP publishing framework. |
com.netscape.certsrv.ra |
A set of classes that implement interfaces for Registration Authority (RA). |
com.netscape.certsrv.request |
A set of classes that implement interfaces for request queue. |
com.netscape.certsrv.security |
A set of classes that implement interfaces that encapsulates the cryptographic tokens and their related data structures. |
com.netscape.certsrv.usrgrp |
A set of classes that implement interfaces for user and group management. |
This jar shall be well documented, and serve as the public external Application Programming Interface (API) for CMS.
CMS’s Servlet Jar [cms.jar]#
This jar includes all the java classes that handle the HTTP requests and resulting User Interface (UI) rendering from users including end-users, agents, and administrators.
This jar includes the following class paths:
Class Path |
Description |
|---|---|
com.netscape.cms.authentication |
This class path includes classes that implement the authentication plug-ins. |
com.netscape.cms.authorization |
This class path includes classes that implement the authorization plug-ins. |
com.netscape.cms.evaluators |
This class path includes classes that implement the evaluator plug-ins of the authorization framework. |
com.netscape.cms.jobs |
This class path includes classes that implement the jobs plug-ins of the notification framework. |
com.netscape.cms.logging |
This class path includes classes that implement the logging plug-ins. |
com.netscape.cms.policy |
This class path includes classes that implement the policy plug-ins. |
com.netscape.cms.publish |
This class path includes classes that implement the publishing mappers and publishers. |
com.netscape.cms.servlet |
This class path includes classes that implement the servlets that handle the incoming HTTP requests. |
com.netscape.cms.servlet.admin |
This class path includes classes for a set of servlets that manage CMS configuration. |
com.netscape.cms.servlet.cert |
This class path includes classes for a set of servlets that manage certificate repository of RA or CA. |
co m.netscape.cms.servlet.cert.scep |
This class path includes classes for a set of servlets that manage certificate repository of RA or CA using SCEP. |
co m.netscape.cms.servlet.connector |
This class path includes classes for a set of servlets that manage the connectors framework. |
com.netscape.cms.servlet.key |
This class path includes classes for a set of servlets that manage the key repository of DRM. |
com.netscape.cms.servlet.ocsp |
This class path includes classes for a set of servlets that manage the OCSP framework. |
com.netscape.cms.servlet.request |
This class path includes classes for a set of servlets that manage the request repository of RA, CA, DRM, or OCSP. |
This jar shall be well documented, and serve as the public external communication interfaces of CMS.
CMS Resource Bundle#
CMS’s Resource Bundle Jar [cmsbundle.jar]#
This jar contains all of the property files for CMS 6.x.
This jar includes the following files:
File |
Description |
|---|---|
LogMessages_en.properties |
This property file includes string tokens that are put in CMS’s log files. |
UserMessages_en.properties |
This property file includes string tokens that are returned to CMS users. |
CMS Private Internal Implementation#
CMS’s Private Implementation Jar [cmscore.jar]#
This jar includes all the private java classes that implement the public interfaces which are built on top of the utility jar. This jar is the core of the CMS implementation.
This jar includes the following class paths:
Class Path |
Description |
|---|---|
com.netscape.cmscore.apps |
A set of classes that implement the CMS framework’s driver. |
com .netscape.cmscore.authentication |
A set of classes that implement authentication plug-ins. |
co m.netscape.cmscore.authorization |
A set of classes that implement the authorization framework. |
com.netscape.cmscore.base |
A set of classes that implement the basic subsystem loading registry. |
com.netscape.cmscore.ca |
A set of classes that implement the CA. |
com.netscape.cmscore.cert |
A set of classes that implement common X.509 certificate manipulation functions. |
com.netscape.cmscore.connector |
A set of classes that implement the connector framework. |
com.netscape.cmscore.crmf |
A set of classes that allow Certificate Request Message Format (CRMF) parsing of the key archival operation. |
com.netscape.cmscore.dbs |
A set clases that implement the database subsystem. |
com.netscape.cmscore.extensions |
A set of classes that implement certificate extensions. |
com.netscape.cmscore.jobs |
A set of classes that implement job plug-ins. |
com.netscape.cmscore.kra |
A set of classes that implement the KRA (or DRM). |
com.netscape.cmscore.ldap |
A set of classes that implement the LDAP publishing framework. |
com.netscape.cmscore.ldapconn |
A set of classes that implement the LDAP connection pool. |
com.netscape.cmscore.listeners |
A set of classes that implement request listener plug-ins. |
com.netscape.cmscore.logging |
A set of classes that implement logging plug-ins. |
c om.netscape.cmscore.notification |
A set of classes that implement notification plug-ins. |
com.netscape.cmscore.ocsp |
A set of classes that implement an OCSP Authority. |
com.netscape.cmscore.policy |
A set of classes that implement policies. |
com.netscape.cmscore.ra |
A set of classes that implement the RA. |
com.netscape.cmscore.request |
A set of classes that implement the request queue. |
com.netscape.cmscore.security |
A set of classes that implement cryptographic related operations. |
com.netscape.cmscore.shares |
A set of classes that implement the Bloom/Shamir secret-sharing algorithm. |
com.netscape.cmscore.time |
A set of classes that implement different time sources when time is generated. |
com.netscape.cmscore.unix |
A set of classes that implement the UNIX specific system functions that are used in CMS. |
com.netscape.cmscore.usrgrp |
A set of classes that implement user and group management. |
com.netscape.cmscore.util |
A set of classes that implement common utility functions. |
Public plug-ins (e. g. - policies) will be implemented under com.netscape.cms.* (where all the public plug-ins are located). Public plug-ins should have no dependencies on the CMS private implementation jar directly, and therefore should be able to be compiled using only the cms public interface (and Netscape and CMS utility jars).
CMS Configuration#
CMS’s Configuration Jar [certsetup.jar]#
This jar contains the configuration framework for CMS 6.x.
This jar includes the following class paths:
Class Path |
Description |
|---|---|
com.netscape.certsetup.base |
This jar includes classes that implement the exceptions and resources used in the configuration framework. |
com.netscape.certsetup.daemon |
This class path includes classes that implement the configuration daemon process that configures CMS. |
CMS Command-Line Tools#
CMS’s Command-Line Tools Jar [cmstools.jar]#
This jar includes all of the java classes that implement command-line tools such as AtoB, BtoA, PrettyPrintCert, and PrettyPrintCrl.
This jar includes the following class paths:
Class Path |
Description |
|---|---|
com.netscape.cmstools |
This class path includes classes that implement command-line tools. |
Glossary#
ACL |
Access Control List |
|
API |
Application Programming Interface |
|
ASN.1 |
Abstract Syntax Notation One. A formal language for describing messages to be exchanged between distributed computer systems. Along with an encoding like BER/DER, ASN.1 can be used to generate and process complex data structures in a standardized and OS-independent manner. For an overview, see A Layman’s Guide to a Subset of ASN.1, BER, and DER. |
|
BER |
Basic Encoding Rules |
|
CA |
Certificate Authority. A service that issues a certificate after verifying the identity of the person or entity the certificate is intended to identify. A CA also renews and revokes certificates and generates CRLs. The entity named in the issuer field of a certificate is always a CA. Certificate authorities can be independent third parties or a person or organization using certificate-issuing server software. |
|
CC |
Common Criteria |
|
certificate |
Digital data, formatted according to the X.509 standard, that specifies the name of an individual, company, or other entity (the subject name of the certificate) and certifies that a public key, which is also included in the certificate, belongs to that entity. A certificate is issued and digitally signed by a certificate authority (CA). A certificate’s validity can be verified by checking the CA’s digital signature using the techniques of public-key cryptography. To be trusted within a public-key infrastructure (PKI), a certificate must be issued and signed by a CA that is trusted by other entities enrolled in the PKI. Also called digital ID, digital passport, public-key certificate, X.509 certificate, and security certificate. |
|
CMMF |
Certificate Management Message Formats. A PKIX format used to convey certificate requests and revocation requests from end entities to certificate authorities and to send a variety of information from certificate authorities to end entities. CMMF is subsumed by another proposed standard, Certificate Management Messages over CMS (CMC). For more information about CMC and related standards, see the `PKIX Charter arters/pkix-charter.html>`__. |
|
CMS |
Netscape Certificate Management System |
|
CRMF |
Certificate Request Message Format. A PKIX format used for messages related to the life-cycle management of X.509 certificates. This format is a subset of CMMF. |
|
CVS |
Concurrent Versions System |
|
DER |
Distinguished Encoding Rules |
|
DRM |
Data Recovery Manager. Synonym for Key Recovery Authority (KRA). |
|
FTP |
File Transfer Protocol. A communications protocol governing the transfer of files from one computer to another over a network. |
|
HTML |
Hypertext Markup Language |
|
HTTP |
Hypertext Transfer Protocol. Protocol used to display HTML. |
|
HTTPS |
Hypertext Transfer Protocol over SSL. Protocol used to display HTML securely. |
|
IETF |
Internet Engineering Task For ce. The Internet standards committee in charge or RFCs. |
|
IMAP |
Internet Message Access Protocol |
|
ITU |
International Telecommunication Union |
|
JSS |
Java Security Services |
|
KRA |
Key Recovery Authority. Synonym for Data Recovery Manager (DRM). |
|
LDAP |
Lightweight Directory Access Protocol |
|
NNTP |
Network News Transfer Protocol |
|
OCSP |
Online Certificate Status Protocol. A PKIX protocol used for determining the current status of a digital certificate. For details, see OCSP. |
|
PKCS |
Public-Key Cryptography Standards |
|
PKCS #5 |
Public-Key Cryptography Standard #5. The standard developed by RSA Laboratories that governs password-based cryptography, for example to encrypt private keys for storage. For details published by RSA, see PKCS #5. |
|
PKCS #7 |
Public-Key Cryptography Standard #7. The standard developed by RSA Laboratories that governs the application of cryptography to data, for example digital signatures. For details published by RSA, see PKCS #7. |
|
PKCS #10 |
Public-Key Cryptography Standard #10. The standard developed by RSA Laboratories that describes syntax for a request for certification of a public key, a name, and possibly a set of attributes. For details published by RSA, see PKCS #10. |
|
PKCS #11 |
Public-Key Cryptography Standard #11. The standard developed by RSA Laboratories that governs communication with cryptographic tokens (such as smart cards). For details published by RSA, see PKCS #11. |
|
PKCS #12 |
Public-Key Cryptography Standard #12. The PKCS standard developed by RSA Laboratories that governs the format used to store or transport private keys, certificates, and other secret material. For details published by RSA, see PKCS #12. |
|
PKI |
Public-Key Infrastructure |
|
PKIX |
Public-Key Infrastructure X.509. A working group of the Internet Engineering Task Force (IETF) that is developing Internet standards needed to support a PKI based on X.509 certificates. For more information, see `PKIX Charter arters/pkix-charter.html>`__. |
|
private key |
One of a pair of keys used in public-key cryptography. The private key is kept secret and is used to decrypt data encrypted with the corresponding public key. |
|
public key |
One of a pair of keys used in public-key cryptography. The public key is distributed freely and published as part of a certificate. It is typically used to encrypt data sent to the public key’s owner, who then decrypts the data with the corresponding private key. |
|
public key cryptography |
A set of well-established techniques and standards that allow an entity to verify its identity electronically or to sign and encrypt electronic data. Two keys are involved: a public key and a private key. A public key is published as part of a certificate, which associates that key with a particular identity. The corresponding private key is kept secret. Data encrypted with the public key can be decrypted only with the private key. |
|
RA |
Registration Authority |
|
RADIUS |
Remote Authentication Dial In User Service. A protocol as defined in RFC2138 |
|
RFC |
Request For Comment. An IETF document. |
|
S/MIME |
Secure/Multipurpose Internet Mail Extensions. A message specification (based on the popular Internet MIME standard) that provides a consistent way to send and receive signed and encrypted MIME data. For complete specifications, see S/MIME version 2 and S/MIME version 3. |
|
SCEP |
Simple Certificate Enrollment Protocol. This protocol is used by Cisco. |
|
SMTP |
Simple Mail Transfer Protocol |
|
SSL |
Secure Sockets Layer. A protocol that allows mutual authentication between a client and server and the establishment of an authenticated and encrypted connection. SSL runs above TCP/IP and below HTTP, LDAP, IMAP, NNTP, and other high-level network protocols. For complete SSL specifications, see SSL v3 and SSL v2. |
|
TCP/IP |
Transmission Control Protocol/Internet Protocol. A protocol for communication between computers, used as a standard for transmitting data over networks and as the basis for standard Internet protocols. |
|
TLS |
Transport Layer Security. A protocol from the IETF based on SSL. It will eventually supersede SSL while remaining backward-compatible with SSL implementations. For more information, see The TLS Protocol. |
|
wTLS |
Wireless Transport Layer Security |
|
X.509 |
A standard defined by the International Telecommunication Union ( ITU) that governs the format of certificates used for authentication in public-key cryptography. |