PKI Interface Design (Legacy)

From Dogtag
Jump to: navigation, search

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

Imported Binary Jars

  • Netscape's Utility Jar [nsutil.jar]

CMS Public External Interfaces and Utilities

  • CMS's Utility Jar [cmsutil.jar]
  • CMS's Public Interface Jar [certsrv.jar]
  • CMS's Servlet Jar [cms.jar]

CMS Resource Bundle

  • CMS's Resource Bundle Jar [cmsbundle.jar]

CMS Private Internal Implementation

  • CMS's Private Implementation Jar [cmscore.jar]

CMS Configuration

  • CMS's Configuration Jar [certsetup.jar]

CMS Command-Line Tools

  • 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.
com.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.
com.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.
com.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.
com.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.
com.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.
com.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.
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 Force. 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.
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.

Bibliography