How to Integrate Your Cryptography Algorithms into JavaTM Security


Last Modified: 27 June 1997

Introduction
Who Should Read This Document
Related Documentation


Steps to Implement and Integrate a Provider
Step 1: Write your Algorithm Implementation Code
Step 2: Give your Provider a Name
Step 3: Write your "Master Class," a subclass of Provider
Step 4: Compile your Code
Step 5: Prepare for Testing: Install the Provider
Step 6: Write and Compile Test Programs
Step 7: Run your Test Programs
Step 8: Document your Provider and its Supported Algorithms
Step 9: Make your Class Files and Documentation Available to Clients


Further Implementation Details and Requirements
Algorithm Aliases
Algorithm Interdependencies
Key Pair Generator and Signature Algorithm Requirements


Appendix A: The "SUN" Provider's Master Class

Appendix B: The java.security File

Introduction

JDK 1.1 introduced the notion of a Cryptography Package Provider, or "provider" for short. This term refers to a package (or a set of packages) that supply a concrete implementation of a subset of the cryptography aspects of the Java Security API. A provider may, for example, contain an implementation of one or more digital signature algorithms, message digest algorithms, and key generation algorithms.

A program wishing to use cryptography functionality may simply request a particular type of object (such as a Signature object) implementing a particular algorithm (such as DSS) and get an implementation from one of the installed providers. If an implementation from a particular provider is desired, the program can request that provider by name, along with the algorithm desired.

Each JDK installation has one or more provider packages installed. Clients may configure their runtimes with different providers, and specify a preference order for each of them. The preference order is the order in which providers are searched for requested algorithms when no particular provider is requested.

JDK 1.1 comes standard with a default provider, named "SUN". The "SUN" provider package includes:

New providers may be added statically or dynamically. Clients may also query which providers are currently installed.

The different implementations may have different characteristics. Some may be software-based, while others may be hardware-based. Some may be platform-independent, while others may be platform-specific. Some provider source code may be available for review and evaluation, while some may not.

Who Should Read This Document

This document is intendend for experienced programmers wishing to create their own provider packages supplying cryptography algorithm implementations. It documents what you need to do in order to integrate your provider into Java Security so that your algorithms can be found when Java Security API clients request them. Programmers that only need to use the Java Security API to access existing cryptography algorithms do not need to read this document.

Related Documentation

This document assumes you have already read the Java Cryptography Architecture API Specification and Reference.

It also discusses various classes and interfaces in the Java Security API. The complete reference documentation for the relevant Security API packages can be found in:

Steps to Implement and Integrate a Provider

The steps required in order to implement a provider and integrate it into Java Security are the following:

Step 1: Write your Algorithm Implementation Code

The first thing you need to do is write the code supplying implementations of the algorithm(s) you want to support.

There are three types of cryptography algorithms you can supply for JDK 1.1: signature, message digest, and key pair generation algorithms.

For each algorithm, you need to create a subclass of the appropriate "engine" class (Signature, MessageDigest, or KeyPairGenerator). (See "Engine Classes" in the Java Cryptography Architecture API Specification and Reference.)

In your subclass, you need to

  1. supply implementations for the abstract methods, whose names usually begin with "engine".

  2. include a constructor without any arguments. Here's why: When one of your algorithms is requested, Java Security looks up the subclass implementing that algorithm, as specified by a property in your "master class" (see Step 3). Java Security then creates the Class object associated with your subclass, and creates an instance of your subclass by calling the newInstance method on that Class object. newInstance requires your subclass to have a constructor without any arguments.

    Note that each engine class (which you are subclassing) has a constructor that takes a single algorithm argument: protected KeyPairGenerator(String algorithm) protected MessageDigest(String algorithm) protected Signature(String algorithm)

    Each subclass constructor without any arguments should call super("algName") where "algName" is the name of the algorithm implemented by the subclass. With such a call, client invocations of the getAlgorithm method (inherited from the superclass) result in the return of the correct algorithm name. Without it, a null String is returned when getAlgorithm is called.

    As an example, suppose a class named AcmeMD5 implements the message digest algorithm named "MD5". This class must be a subclass of MessageDigest, and should contain a constructor like the following: public AcmeMD5() { super("MD5"); ... }

If you are implementing a signature algorithm that requires a message digest algorithm, the name specified for your algorithm should include both the message digest and signature algorithm names. For example, an implementation of RSA that uses the MD2 message digest algorithm should have the name "MD2/RSA". See Appendix A of the Java Cryptography Architecture API Specification & Reference for the standard algorithm names that can be used.

See Further Implementation Details and Requirements for additional information.

Step 2: Give your Provider a Name

Decide on a name for your provider. This is the name to be used by client applications to refer to your provider.

Step 3: Write your "Master Class", a subclass of Provider

The third step is to create a subclass of the Provider class.

Your subclass should be a final class, and its constructor should

For further master class property setting examples, see Appendix A to view the current JDK 1.1 Sun.java source file. This shows how the Sun class constructor sets all the properties for the "SUN" provider.

Note: The Provider subclass can get its information from wherever it wants. Thus, the information can be hard-wired in, or retrieved at runtime, e.g., from a file.

Step 4: Compile your Code

After you have created your implementation code (Step 1), given your provider a name (Step 2), and created the master class (Step 3), use the Java compiler to compile your files.

Step 5: Prepare for Testing: Install the Provider

In order to prepare for testing your provider, you must install it in the same manner as will be done by clients wishing to use it. The installation enables Java Security to find your algorithm implementations when clients request them.

There are two parts to installing a provider: installing the provider package classes, and configuring the provider.

Installing the Provider Classes

The first thing you must do is make your classes available so that they can be found when requested. There are a few possible ways of doing this:

Configuring the Provider

The next step is to add the provider to your list of approved providers. This is done statically by editing the java.security file in the lib/security (lib\security on Windows) directory of the JDK. Thus, if the JDK is installed in a directory called jdk1.1.1, the file is

For each provider, this file should have a statement of the following form: security.provider.n=masterClassName

This declares a provider, and specifies its preference order n. The preference order is the order in which providers are searched for requested algorithms when no specific provider is requested. The order is 1-based; 1 is the most preferred, followed by 2, and so on.

masterClassName must specify the fully qualified name of the provider's "master class", which you implemented in Step 3. This class is always a subclass of the Provider class.

Whenever the JDK is installed, it contains one built-in (default) provider, the provider referred to as "SUN". The java.security file has just the following provider specification: security.provider.1=sun.security.provider.Sun (Recall that the "SUN" provider's master class is the Sun class in the sun.security.provider package.)

Suppose that your master class is the Acme class in the COM.acme.provider package, and that you would like to make your provider the second preferred provider. To do so, add the following line to the java.security file below the line for the "SUN" provider: security.provider.2=COM.acme.provider.Acme Note: Providers may also be registered dynamically. To do so, a program (such as your test program, to be written in Step 7) can call either the addProvider or insertProviderAt method in the Security class. This type of registration is not persistent and can only be done by "trusted" programs. See the Security class section of the Java Cryptography Architecture API Specification and Reference.

Step 6: Write and Compile your Test Programs

Write and compile one or more test programs that test your provider's incorporation into the Security API as well as the correctness of its algorithm(s). Create any supporting files needed, such as those for test data to be hashed or signed.

The first tests your program should perform are ones to ensure that your provider is found, and that its name, version number, and additional information is as expected. To do so, you could write code like the following, substituting your provider name for "MyPro": import java.security.*; Provider p = Security.getProvider("MyPro"); System.out.println("MyPro provider name is " + p.getName()); System.out.println("MyPro provider version # is " + p.getVersion()); System.out.println("MyPro provider info is " + p.getInfo());

Next, you should ensure that your algorithms are found. For instance, if you implemented an SHA-1 message digest algorithm, you could check to ensure it's found when requested by using the following code (again substituting your provider name for "MyPro"): MessageDigest sha = MessageDigest.getInstance("SHA-1", "MyPro"); System.out.println("My MessageDigest algorithm name is " + sha.getAlgorithm());

If you don't specify a provider name in the call to getInstance, all registered providers will be searched, in preference order (see Configuring the Provider), until one implementing the algorithm is found.

Step 7: Run your Test Programs

Run your test program(s). Debug your code and continue testing as needed. If the Java Security API cannot seem to find one of your algorithms, review the steps above and ensure they are all completed.

Step 8: Document your Provider and its Supported Algorithms

The next-to-last step is to write documentation for your clients. At the minimum, you need to specify In addition, your documentation should specify anything else of interest to clients, such as any default algorithm parameters.

For each message digest algorithm, tell whether or not your implementation is cloneable. This is not technically necessary, but it may save clients some time and coding by telling them whether or not intermediate hashes may be possible through cloning. Clients who do not know whether or not a message digest implementation is cloneable can find out by calling boolean cloneable = sha instanceof Cloneable; where sha is the message digest object they received when they requested one via a call to MessageDigest.getInstance.

For a signature algorithm, specify which parameters can be set (or gotten) via a call to the setParameter (or getParameter) method in the Signature class. Tell the Strings that can be used for the param argument to setParameter or getParameter to indicate which parameter should be set or gotten. Also tell what parameter values can be specified in the setParameter value argument. See the Signature class documentation for further information about setParameter and getParameter.

For a key pair generator algorithm, if you have defined and implemented an algorithm-specific initialization interface (see DSAKeyPairGenerator for a sample interface), document the interface and the parameters that can be specified in its initialize method(s).

Step 9: Make your Class Files and Documentation Available to Clients

The final step is to make your class files and documentation available to clients in whatever form (.class files, zip files, JAR files, ...) and methods (web download, floppy, mail, ...) you feel are appropriate.

Further Implementation Details and Requirements

Algorithm Aliases

For many signature, message digest, and key pair generator algorithms, there is a single official "standard name" defined in Appendix A of the Java Cryptography Architecture API Specification & Reference.

For example, "MD5" is the standard name for the RSA-MD5 Message Digest algorithm defined by RSA DSI in RFC 1321.

In JDK 1.1, there is an aliasing scheme that enables clients to use aliases when referring to algorithms rather than their standard names. For example, the "SUN" provider's master class (Sun.java) defines the alias "SHA-1/DSA" for the algorithm whose standard name is "DSA". Thus, the following statements are equivalent: Signature sig = Signature.getInstance("DSA", "SUN"); Signature sig = Signature.getInstance("SHA-1/DSA", "SUN"); Aliases can be defined in your "master class" (see Step 3). To define an alias, create a property named Alg.Alias.engineClassName.aliasName

where engineClassName is either Signature, MessageDigest, or KeyPairGenerator, and aliasName is your alias name. The value of the property must be the standard algorithm name for the algorithm being aliased.

As an example, the "SUN" provider defines the alias "SHA-1/DSA" for the signature algorithm whose standard name is "DSA" by setting a property named Alg.Alias.Signature.SHA-1/DSA to have the value DSA via the following: put("Alg.Alias.Signature.SHA-1/DSA", "DSA");

Currently, aliases defined by the "SUN" provider are available to all clients, no matter which provider clients request. For example, if you create a provider named "MyPro" that implements the DSA algorithm, then even if you don't define any aliases for it, the "SHA-1/DSA" alias defined by "SUN" can be used to refer to your DSA implementation as follows: Signature sig = Signature.getInstance("SHA-1/DSA", "MyPro");

WARNING: The aliasing scheme may be changed or eliminated in future releases.

Algorithm Interdependencies

Some algorithms require the use of other types of algorithms. For example, a signature algorithm usually needs to use a message digest algorithm in order to sign and verify data.

If you are implementing one type of algorithm that requires another, you can do one of the following:

  1. Provide your own implementations for both.

  2. Let your implementation of one algorithm use an instance of the other type of algorithm, as supplied by the default "SUN" provider that is included with every JDK installation. For example, if you are implementing a signature algorithm that requires a message digest algorithm, you can obtain an instance of a class implementing the MD5 message digest algorithm by calling MessageDigest.getInstance("MD5", "SUN").

  3. Let your implementation of one algorithm use an instance of the other type of algorithm, as supplied by another specific provider. This is only appropriate if you are sure that all clients who will use your provider will also have the other provider installed.

Here are some common types of algorithm interdependencies:

Signature and Message Digest Algorithms

For example, the DSA signature algorithm requires the SHA-1 message digest algorithm.

Key Pair Generation and Message Digest Algorithms

For example, DSA keys are generated using the SHA-1 message digest algorithm.

Signature and Key Pair Generation Algorithms

If you are implementing a signature algorithm, your implementation's engineInitSign and engineInitVerify methods will require passed-in keys that are valid for the underlying algorithm (e.g., DSA keys for the DSS algorithm). You can either

  1. also implement your own key pair generation algorithm and require the keys to have been generated from that key pair generator, or

  2. accept keys from other key pair generators, as long as they are instances of appropriate interfaces that enable your signature implementation to obtain the information it needs (such as the private and public keys and the key parameters). For example, the engineInitSign method for a DSS Signature class could accept any private keys that are instances of java.security.interfaces.DSAPrivateKey.
IMPORTANT NOTE: In JDK 1.1, it is not possible to instantiate a key, given key information. If you generate a key pair, you can use it, for example for generating a signature, during the same program execution. But you cannot save your keys and then use them during another program execution; there is no way to instantiate a key object using the saved key information. This restriction will be fixed in JDK 1.2; there will be features for importing and exporting keys in various formats.

Key Pair Generator and Signature Algorithm Requirements

DSA Key Pair Generators and Signature Algorithms

Default Parameter Requirements

If you implement a DSA key pair generator, your implementation should supply default parameters that are used when clients don't specify parameters. The documentation you supply (Step 8) should state what the default parameters are.

For example, the DSA key pair generator in the "SUN" provider supplies a set of pre-computed p, q, and g default values for the generation of 512, 768, and 1024-bit key pairs. The following p, q, and g values are used as the default values for the generation of 1024-bit DSA key pairs: p = fd7f5381 1d751229 52df4a9c 2eece4e7 f611b752 3cef4400 c31e3f80 b6512669 455d4022 51fb593d 8d58fabf c5f5ba30 f6cb9b55 6cd7813b 801d346f f26660b7 6b9950a5 a49f9fe8 047b1022 c24fbba9 d7feb7c6 1bf83b57 e7c6a8a6 150f04fb 83f6d3c5 1ec30235 54135a16 9132f675 f3ae2b61 d72aeff2 2203199d d14801c7 q = 9760508f 15230bcc b292b982 a2eb840b f0581cf5 g = f7e1a085 d69b3dde cbbcab5c 36b857b9 7994afbb fa3aea82 f9574c0b 3d078267 5159578e bad4594f e6710710 8180b449 167123e8 4c281613 b7cf0932 8cc8a6e1 3c167a8b 547c8d28 e0a3ae1e 2bb3a675 916ea37f 0bfa2135 62f1fb62 7a01243b cca4f1be a8519089 a883dfe1 5ae59f06 928b665e 807b5525 64014c3b fecf492a

(The p and q values given here were generated by the prime generation standard, using the 160-bit SEED: 8d515589 4229d5e6 89ee01e6 018a237e 2cae64cd With this seed, the algorithm found p and q when the counter was at 92.)

DSA Interfaces

The Java Security API contains the following interfaces for the convenience of programmers implementing DSA algorithms: The following sections discuss requirements for implementations of these interfaces.

DSAKeyPairGenerator Implementation

If you are implementing a DSA key pair generator, your subclass of KeyPairGenerator should implement java.security.interfaces.DSAKeyPairGenerator. The DSAKeyPairGenerator interface contains initialize methods that clients call when they want to provide DSA-specific parameters to be used rather than the default parameters your implementation supplies.

DSAParams Implementation

If you are implementing a DSA key pair generator or the DSS signature algorithm, you will need to create a class implementing java.security.interfaces.DSAParams for holding and returning the p, q, and g parameters. All that is needed is a simple implementation such as the following: import java.math.BigInteger; class myDSAParams implements java.security.interfaces.DSAParams { BigInteger p, q, g; myDSAParams(BigInteger p, BigInteger q, BigInteger g) { this.p = p; this.q = q; this.g = g; } public BigInteger getP() { return p; } public BigInteger getQ() { return q; } public BigInteger getG() { return g; } }

DSAPrivateKey and DSAPublicKey Implementations

If you implement a DSA key pair generator, you need to create classes implementing the DSAPrivateKey and DSAPublicKey interfaces from the package java.security.interfaces. Your generateKeyPair method (in your KeyPairGenerator subclass) will return instances of those classes.

Note the following interface signatures: public interface DSAPrivateKey extends DSAKey, java.security.PrivateKey public interface DSAPublicKey extends DSAKey, java.security.PublicKey public interface DSAKey public interface PrivateKey extends Key public interface PublicKey extends Key public interface Key extends java.io.Serializable

In order to implement the DSAPrivateKey and DSAPublicKey interfaces, you must implement the methods they define as well as those defined by interfaces they extend, directly or indirectly.

Thus, for private keys, you need to supply a class that implements

  • the getX method from the DSAPrivateKey interface

  • the getParams method from the java.security.interfaces.DSAKey interface, since DSAPrivateKey extends DSAKey

  • the getAlgorithm, getEncoded, and getFormat methods from the java.security.Key interface, since DSAPrivateKey extends java.security.PrivateKey, and PrivateKey extends Key Similarly, for public DSA keys, you need to supply a class that implements
    • the getY method from the DSAPublicKey interface

    • the getParams method from the java.security.interfaces.DSAKey interface, since DSAPublicKey extends DSAKey

    • the getAlgorithm, getEncoded, and getFormat methods from the java.security.Key interface, since DSAPublicKey extends java.security.PublicKey, and PublicKey extends Key

Non-DSA Key Pair Generators

As noted above, the Java Security API contains interfaces for the convenience of programmers implementing DSA algorithms. The API does not at this time contain similar interfaces for any other type of algorithm. Thus, you need to define your own.

If you are implementing a non-DSA key pair generator, you should create an interface with one or more initialize methods that clients can call when they want to provide algorithm-specific parameters to be used rather than the default parameters your implementation supplies. Your subclass of KeyPairGenerator should implement this interface.

For private and public keys for non-DSA algorithms, there are currently no java.security.interfaces interfaces corresponding to the DSAPrivateKey and DSAPublicKey ones for DSA. It is recommended that you create similar interfaces and provide implementation classes. Your public key interface should extend the PublicKey interface. Similarly, your private key interface should extend the PrivateKey interface.

Appendix A: The "SUN" Provider's Master Class

Below is an edited version of the Sun.java file, which contains a class named Sun that is the master class for the provider named "SUN". (This provider is supplied with every JDK installation.) As with all master classes, this class is a subclass of Provider. It specifies the class names and package locations of all the algorithm implementations supplied by the "SUN" provider. Java Security uses this information to look up the various algorithms when they are requested.

This code is supplied as an example of a master class. /* * @(#)Sun.java 1.15 97/02/03 * * Copyright (c) 1995, 1996 Sun Microsystems, Inc. All Rights Reserved. * * This software is the confidential and proprietary information of Sun * Microsystems, Inc. ("Confidential Information"). You shall not * disclose such Confidential Information and shall use it only in * accordance with the terms of the license agreement you entered into * with Sun. * * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING * THIS SOFTWARE OR ITS DERIVATIVES. * * CopyrightVersion 1.1_beta * */ package sun.security.provider; import java.io.*; import java.util.*; import java.security.*; /** * The SUN Security Provider. * * @version 1.15, 02/03/97 * @author Benjamin Renaud */ /** * Defines the "SUN" provider. * * Algorithms supported, and their names: * * - SHA-1 is the message digest scheme decribed in FIPS 180-1. * An alias for SHA-1 is SHA. * * - DSA is the signature scheme described in FIPS 186. (SHA used in * DSA is SHA-1: FIPS 186 with Change No 1.) Aliases for DSA are * SHA/DSA, SHA-1/DSA, DSS and the object identifier (OID) string * "OID:1.3.14.3.2.13". * * - DSA is the key generation scheme as described in FIPS 186. * Aliases for DSA include the OID string "OID:1.3.14.3.2.12". * * - MD5 is the message digest scheme described in RFC 1321. * There are no aliases for MD5. * * Notes: The name of the algorithm described in FIPS-180 is SHA-0, and * it is not supported by the SUN provider.) * * @author Benjamin Renaud * @version 1.15, 97/02/04 */ public final class Sun extends Provider { private static String info = "SUN Security Provider v1.0, " + "DSA signing and key generation, SHA-1 and MD5 message digests."; public Sun() { /* We are the SUN provider */ super("SUN", 1.0, info); /* * Signature engines */ put("Signature.DSA", "sun.security.provider.DSA"); put("Alg.Alias.Signature.SHA/DSA", "DSA"); put("Alg.Alias.Signature.SHA-1/DSA", "DSA"); put("Alg.Alias.Signature.DSS", "DSA"); put("Alg.Alias.Signature.OID:1.3.14.3.2.13", "DSA"); /* * Key Pair Generator engines */ put("KeyPairGenerator.DSA", "sun.security.provider.DSAKeyPairGenerator"); put("Alg.Alias.KeyPairGenerator.OID:1.3.14.3.2.12", "DSA"); /* * Digest engines */ put("MessageDigest.MD5", "sun.security.provider.MD5"); put("MessageDigest.SHA-1", "sun.security.provider.SHA"); put("Alg.Alias.MessageDigest.SHA", "SHA-1"); } }

Appendix B: The java.security File

Below is an edited copy of the java.security file that appears in every JDK installation. (The edits simply add more comments.) This file appears in the lib/security (lib\security on Windows) directory of the JDK. Thus, if the JDK is installed in a directory called jdk1.1.1, the file would be

See Step 5 for an example of adding information about your provider to this file.

See The System Identity Scope of the Java Cryptography Architecture API Specification & Reference for information about the system scope mentioned at the end of this file.

# # This is the "master security properties file". # # In this file, various security properties are set for use by # java.security classes. This is where users can statically register # Cryptography Package Providers ("providers" for short). The term # "provider" refers to a package or set of packages that supply a # concrete implementation of a subset of the cryptography aspects of # the Java Security API. A provider may, for example, implement one or # more digital signature algorithms or message digest algorithms. # # Each provider must implement a subclass of the Provider class. # To register a provider in this master security properties file, # specify the Provider subclass name and priority in the format # # security.provider.n=className # # This declares a provider, and specifies its preference # order n. The preference order is the order in which providers are # searched for requested algorithms (when no specific provider is # requested). The order is 1-based; 1 is the most preferred, followed # by 2, and so on. # # className must specify the subclass of the Provider class whose # constructor sets the values of various properties that are required # for the Java Security API to look up the algorithms or other # facilities implemented by the provider. # # There must be at least one provider specification in java.security. # There is a default provider that comes standard with the JDK. It # is called the "SUN" provider, and its Provider subclass # named Sun appears in the sun.security.provider package. Thus, the # "SUN" provider is registered via the following: # # security.provider.1=sun.security.provider.Sun # # (The number 1 is used for the default provider.) # # Note: Statically registered Provider subclasses are instantiated # when the system is initialized. Providers can be dynamically # registered instead by calls to either the addProvider or # insertProviderAt method in the Security class. # # List of providers and their preference orders (see above): # security.provider.1=sun.security.provider.Sun # # Class to instantiate as the system scope: # system.scope=sun.security.provider.IdentityDatabase

Copyright © 1996, 1997 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA 94043-1100 USA. All rights reserved.

Please send comments to: java-security@java.sun.com