Concepts

Several concepts are introduced in the API.

Engine Classes and Algorithms

An engine class defines a cryptographic service in an abstract fashion (without a concrete implementation).

A cryptographic service is always associated with a particular algorithm or type, and it either provides cryptographic operations (such as those for digital signatures or message digests), generates or supplies the cryptographic material (keys or parameters) required for cryptographic operations, or generates data objects (keystores or certificates) that encapsulate cryptographic keys (that can be used in a cryptographic operation) in a secure fashion. For example, two of the engine classes are the Signature and KeyFactory classes. The Signature class provides access to the functionality of a digital signature algorithm. A DSA KeyFactory supplies a DSA private or public key (from its encoding or transparent specification) in a format usable by the initSign or initVerify methods, respectively, of a DSA Signature object.

The Java™ Cryptography Architecture encompasses the classes of the Java 2 SDK Security package related to cryptography, including the engine classes. Users of the API request and use instances of the engine classes to carry out corresponding operations. The following engine classes are defined in the Java 2 SDK:

• MessageDigest: used to calculate the message digest (hash) of specified data.
• Signature: used to sign data and verify digital signatures.
• KeyPairGenerator: used to generate a pair of public and private keys suitable for a specified algorithm.
• KeyFactory: used to convert opaque cryptographic keys of type Key into key specifications (transparent representations of the underlying key material), and vice versa.
• CertificateFactory: used to create public key certificates and Certificate Revocation Lists (CRLs).
• KeyStore: used to create and manage a keystore. A keystore is a database of keys. Private keys in a keystore have a certificate chain associated with them, that authenticates the corresponding public key. A keystore also contains certificates from trusted entities.
• AlgorithmParameters: used to manage the parameters for a particular algorithm, including parameter encoding and decoding.
• AlgorithmParameterGenerator: used to generate a set of parameters suitable for a specified algorithm.
• SecureRandom: used to generate random or pseudo-random numbers.

In the 1.4 release of the Java 2 SDK, the following new engines were added and the services are provided by the IBMCertPath provider:

• CertPathBuilder: used to build certificate chains (also known as certification paths).
• CertPathValidator: used to validate certificate chains.
• CertStore: used to retrieve Certificate objects and CRL objects from a repository.

Note: A generator creates objects with brand-new contents, whereas a factory creates objects from existing material (for example, an encoding).

An engine class provides the interface to the functionality of a specific type of cryptographic service (independent of a particular cryptographic algorithm). It defines Application Programming Interface (API) methods that allow applications to access the specific type of cryptographic service it provides. The actual implementations (from one or more providers) are those for specific algorithms. The Signature engine class, for example, provides access to the functionality of a digital signature algorithm. The actual implementation supplied in a SignatureSpi subclass would be that for a specific kind of signature algorithm, such as SHA-1 with DSA, SHA-1 with RSA, or MD5 with RSA.

The application interfaces supplied by an engine class are implemented in terms of a Service Provider Interface (SPI). That is, for each engine class, there is a corresponding abstract SPI class, which defines the SPI methods that cryptographic service providers must implement.

An instance of an engine class, the API object, encapsulates (as a private field) an instance of the corresponding SPI class, the SPI object. All API methods of an API object are declared final and their implementations invoke the corresponding SPI methods of the encapsulated SPI object. An instance of an engine class (and of its corresponding SPI class) is created by a call to the getInstance factory method of the engine class.

The name of each SPI class is the same as that of the corresponding engine class, followed by Spi. For example, the SPI class corresponding to the Signature engine class is the SignatureSpi class.

Each SPI class is abstract. To supply the implementation of a particular type of service, for a specific algorithm, a provider must subclass the corresponding SPI class and provide implementations for all the abstract methods.

Another example of an engine class is the MessageDigest class, which provides access to a message digest algorithm. Its implementations, in MessageDigestSpi subclasses, can be those of various message digest algorithms such as SHA-1, MD5, or MD2.

As a final example, the KeyFactory engine class supports the conversion from opaque keys to transparent key specifications, and vice versa. (See the Key Specification Interfaces and Classes section.) The KeyFactorySpi subclass supplies an actual implementation for a specific type of key, for example, DSA public and private keys.

Implementations and Providers

Implementations for various cryptographic services are provided by JCA Cryptographic Service Providers. Cryptographic service providers are essentially packages that supply one or more cryptographic service implementations. The Engine Classes and Algorithms section includes a list of some of the implementations supplied by IBMJCE.

Other providers might define their own implementations of these services or of other services.

Using Factory Methods to Obtain Implementation Instances

For each engine class in the API, a particular implementation is requested and instantiated by calling a factory method on the engine class. A factory method is a static method that returns an instance of a class.

The basic mechanism for obtaining an appropriate Signature object, for example, is as follows: A user requests such an object by calling the getInstance method in the Signature class, specifying the name of a signature algorithm (such as SHA1withDSA), and, optionally, the name of the provider or the Provider class. The getInstance method finds an implementation that satisfies the supplied algorithm and provider parameters. If no provider is specified, getInstance searches the registered providers, in preference order, for one with an implementation of the specified algorithm. See The Provider Class for more information about registering providers.