How to Implement a Provider in the Java CryptographyArchitecture

Introduction

The Java platform defines a set of APIs spanning major securityareas, including cryptography, public key infrastructure,authentication, secure communication, and access control. TheseAPIs allow developers to easily integrate security into theirapplication code. They were designed around the followingprinciples:

1. Implementation independence

   Applications do not need to implement security themselves.Rather, they can request security services from the Java platform.Security services are implemented in providers (see below), whichare plugged into the Java platform via a standard interface. Anapplication may rely on multiple independent providers for securityfunctionality.

2. Implementation interoperability

   Providers are interoperable across applications. Specifically,an application is not bound to a specific provider, and a provideris not bound to a specific application.

3. Algorithm extensibility

   The Java platform includes a number of built-in providers thatimplement a basic set of security services that are widely usedtoday. However, some applications may rely on emerging standardsnot yet implemented, or on proprietary services. The Java platformsupports the installation of custom providers that implement suchservices.

ACryptographic Service Provider (provider) refers to apackage (or a set of packages) that supply a concreteimplementation of a subset of the cryptography aspects of the JDKSecurity API.

Thejava.security.Provider class encapsulates thenotion of a security provider in the Java platform. It specifiesthe provider's name and lists the security services it implements.Multiple providers may be configured at the same time, and arelisted in order of preference. When a security service isrequested, the highest priority provider that implements thatservice is selected.

Figures 1 and 2 illustrate these options for requesting a SHA-256message digest implementation. Both figures show three providersthat implement message digest algorithms. The providers are orderedby preference from left to right (1-3). In Figure 1, an applicationrequests an SHA-256 algorithm implementation without specifying aprovider name. The providers are searched in preference order andthe implementation from the first provider supplying thatparticular algorithm, ProviderB, is returned. In Figure 2, theapplication requests the SHA-256 algorithm implementation from aspecific provider, ProviderC. This time the implementation fromthat provider is returned, even though a provider with a higherpreference order, ProviderB, also supplies a SHA-256implementation.

Figure 1: Provider searching	Figure 2: Specific providerrequested

Each installation has one or more provider packages installed.Clients may configure their runtimes with different providers, andspecify apreference order for each of them. The preferenceorder is the order in which providers are searched for requestedalgorithms when no particular provider is requested.

Sun's version of the Java runtime environment comes standardwith a default provider, named "SUN". Other Java runtimeenvironments may not necessarily supply the "SUN" provider.

Who Should Read This Document

Programmers that only need to use the Java Security API toaccess existing cryptography algorithms and other services donot need to read this document.

This document is intended for experienced programmers wishing tocreate their own provider packages supplying cryptographic serviceimplementations. It documents what you need to do in order tointegrate your provider into Java so that your algorithms and otherservices can be found when Java Security API clients request them.

Related Documentation

This document assumes you have already read theJava Cryptography Architecture ReferenceGuide.

It documents the packages which contain the various classes andinterfaces in the Security API.

• java.security
• java.security.spec
• java.security.interfaces
• javax.crypto
• javax.crypto.spec
• javax.crypto.interfaces

Notes onTerminology

• Prior to JDK 1.4, the JCE was an unbundled product, and assuch, the JCA and JCE were regularly referred to as separate,distinct components. As JCE is now bundled in JDK, the distinctionis becoming less apparent. Since the JCE uses the same architectureas the JCA, the JCE should be more properly thought of as a subsetof the JCA.
• The JCA within the JDK includes two software components:
  • the framework that defines and supports cryptographic servicesfor which providers supply implementations. This framework includespackages such asjava.security,javax.crypto,javax.crypto.spec, andjavax.crypto.interfaces.
  • the actual providers such asSun,SunRsaSign,SunJCE, which contain the actual cryptographicimplementations.

Throughout this document, the termsJCA by itself refersto the JCA framework. Whenever this document notes a specific JCAprovider, it will be referred to explicitly by the providername.

Anengine class defines a cryptographic service in anabstract fashion (without a concrete implementation).

Acryptographic service is always associated with aparticular algorithm or type. It either provides cryptographicoperations (like those for digital signatures or message digests,ciphers or key agreement protocols); generates or supplies thecryptographic material (keys or parameters) required forcryptographic operations; or generates data objects (keystores orcertificates) that encapsulate cryptographic keys (which can beused in a cryptographic operation) in a secure fashion.

For example, here are four engine classes:

• TheSignature class provides access to thefunctionality of a digital signature algorithm.
• A DSAKeyFactory class supplies a DSA private orpublic key (from its encoding or transparent specification) in aformat usable by the initSign or initVerify methods, respectively,of a DSA Signature object.
• TheCipher class provides access to thefunctionality of an encryption algorithm (such as AES)
• theKeyAgreement class provides access to thefunctionality of a key agreement protocol (such asDiffie-Hellman)

The Java Cryptography Architecture encompasses the classescomprising the Security package that relate to cryptography,including the engine classes. Users of the API request and utilizeinstances of the engine classes to carry out correspondingoperations. The JDK defines the following engine classes:

• MessageDigest - used to calculate the messagedigest (hash) of specified data.
• Signature - used to sign data and verify digitalsignatures.
• KeyPairGenerator - used to generate a pair ofpublic and private keys suitable for a specified algorithm.
• KeyFactory - used to convert opaque cryptographickeys of typeKey intokey specifications(transparent representations of the underlying key material), andvice versa.
• KeyStore - used to create and manage akeystore. A keystore is a database of keys. Private keys ina keystore have a certificate chain associated with them, whichauthenticates the corresponding public key. A keystore alsocontains certificates from trusted entities.
• CertificateFactory - used to create public keycertificates and Certificate Revocation Lists (CRLs).
• AlgorithmParameters - used to manage theparameters for a particular algorithm, including parameter encodingand decoding.
• AlgorithmParameterGenerator - used to generate aset of parameters suitable for a specified algorithm.
• SecureRandom - used to generate random orpseudo-random numbers.
• Cipher: used to encrypt or decrypt some specifieddata.
• KeyAgreement: used to execute a key agreement (keyexchange) protocol between 2 or more parties.
• KeyGenerator: used to generate a secret(symmetric) key suitable for a specified algorithm.
• Mac: used to compute themessage authenticationcode of some specified data.
• SecretKeyFactory: used to convert opaquecryptographic keys of typeSecretKey intokeyspecifications (transparent representations of the underlyingkey material), and vice versa.
• ExemptionMechanism: used to provide thefunctionality of an exemption mechanism such askeyrecovery,key weakening,key escrow, or any other(custom) exemption mechanism. Applications or applets that use anexemption mechanism may be granted stronger encryption capabilitiesthan those which don't. However, please note that cryptographicrestrictions are no longer required for most countries, and thusexemption mechanisms may only be useful in those few countrieswhose governments mandate restrictions.

Note: Agenerator creates objects with brand-newcontents, whereas afactory creates objects from existingmaterial (for example, an encoding).

Anengine class provides the interface to thefunctionality of a specific type of cryptographic service(independent of a particular cryptographic algorithm). It definesApplication Programming Interface (API) methods that allowapplications to access the specific type of cryptographic serviceit provides. The actual implementations (from one or moreproviders) are those for specific algorithms. For example, theSignature engine class provides access to the functionality of adigital signature algorithm. The actual implementation supplied inaSignatureSpi subclass (see next paragraph) would bethat for a specific kind of signature algorithm, such as SHA256withDSAor SHA512withRSA.

The application interfaces supplied by an engine class areimplemented in terms of aService Provider Interface (SPI).That is, for each engine class, there is a corresponding abstractSPI class, which defines the Service Provider Interface methodsthat 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 SPImethods of the encapsulated SPI object. An instance of an engineclass (and of its corresponding SPI class) is created by a call tothegetInstance factory method of the engineclass.

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

Each SPI class is abstract. To supply the implementation of aparticular type of service and for a specific algorithm, a providermust subclass the corresponding SPI class and provideimplementations for all the abstract methods.

Another example of an engine class is the MessageDigest class,which provides access to a message digest algorithm. Itsimplementations, in MessageDigestSpi subclasses, may be those ofvarious message digest algorithms such as SHA256 or SHA384.

As a final example, the KeyFactory engine class supports theconversion from opaque keys to transparent key specifications, andvice versa. SeeKey Specification Interfacesand Classes Required by Key Factories for details. The actualimplementation supplied in a KeyFactorySpi subclass would be thatfor a specific type of keys, e.g., DSA public and private keys.

Follow the steps below to implement a provider and integrate itinto the JCA framework:

Step 1: Write your ServiceImplementation Code

The first thing you need to do is to write the code thatprovides algorithm-specific implementations of the cryptographicservices you want to support.

Note that your provider may supply implementations ofcryptographic services already available in one or more of thesecurity components of the JDK.

For cryptographic services not defined in JCA (For example;signatures and message digests), please refer toJava Cryptography Architecture ReferenceGuide.

For each cryptographic service you wish to implement, create asubclass of the appropriate SPI class. JCA defines the followingengine classes:

• SignatureSpi
• MessageDigestSpi
• KeyPairGeneratorSpi
• SecureRandomSpi
• AlgorithmParameterGeneratorSpi
• AlgorithmParametersSpi
• KeyFactorySpi
• CertificateFactorySpi
• KeyStoreSpi
• CipherSpi
• KeyAgreementSpi
• KeyGeneratorSpi
• MacSpi
• SecretKeyFactorySpi
• ExemptionMechanismSpi

(SeeEngine Classes and Corresponding SPIClasses in this document for information on the JCA and othercryptographic classes.)

In your subclass, you need to:

1. Supply implementations for the abstract methods, whose namesusually begin withengine. SeeFurther Implementation Details andRequirements for additional information.
2. Ensure there is a public constructor without any arguments.Here's why: When one of your services is requested, Java Securitylooks up the subclass implementing that service, as specified by aproperty in your "master class" (seeStep 3).Java Security then creates theClass object associatedwith your subclass, and creates an instance of your subclass bycalling thenewInstance method on thatClass object.newInstance requires yoursubclass to have a public constructor without any parameters.
3. A default constructor without arguments will automatically begenerated if your subclass doesn't have any constructors. But ifyour subclass defines any constructors, you must explicitly definea public constructor without arguments.

Step 1.1: Additional JCA ProviderRequirements and Recommendations for EncryptionImplementations

When instantiating a provider's implementation (class) of aCipher, KeyAgreement, KeyGenerator, MAC orSecretKey factory, the framework will determine theprovider's codebase (JAR file) and verify its signature. In thisway, JCA authenticates the provider and ensures that only providerssigned by a trusted entity can be plugged into JCA. Thus, onerequirement for encryption providers is that they must be signed,as described in later steps.

In addition, each provider should perform self-integritychecking to ensure that the JAR file containing its code has notbeen manipulated in an attempt to invoke provider methods directlyrather than through JCA. For further information, seeHow a Provider Can Do Self-IntegrityChecking.

In order for provider classes to become unusable if instantiatedby an application directly, bypassing JCA, providers shouldimplement the following:

• All SPI implementation classes in a provider package should bedeclaredfinal (so that they cannot be subclassed), andtheir (SPI) implementation methods should be declaredprotected.
• All crypto-related helper classes in a provider package shouldhave package-private scope, so that they cannot be accessed fromoutside the provider package.

For providers that may be exported outside the U.S.,CipherSpi implementations must include animplementation of theengineGetKeySize method which,given aKey, returns the key size. If there arerestrictions on available cryptographic strength specified injurisdiction policy files, eachCipher initializationmethod callsengineGetKeySize and then compares theresult with the maximum allowable key size for the particularlocation and circumstances of the applet or application being run.If the key size is too large, the initialization method throws anexception.

Additionaloptional features that providers may implementare

• theengineWrap andengineUnwrapmethods ofCipherSpi. Wrapping a key enables securetransfer of the key from one place to another. Information aboutwrapping and unwrapping keys is provided in theWrapping and Unwrapping Keyssection of theJava Cryptography Architecture ReferenceGuide.
• one or moreexemption mechanisms. An exemption mechanismis something such as key recovery, key escrow, or key weakeningwhich, if implemented and enforced, may enable reducedcryptographic restrictions for an application (or applet) that usesit. For information on the requirements for apps that utilizeexemption mechanisms, seeHowto Make Applications "Exempt" from Cryptographic Restrictionsin theJava Cryptography Architecture Reference Guide.

Step 2: Give your Provider aName

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

Step 3: Write yourMasterClass, a subclass of Provider

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

Your subclass should be afinal class, and itsconstructor should

• callsuper, specifying the provider name (seeStep 2), version number, and a string ofinformation about the provider and algorithms it supports. Forexample:

      super("CryptoX", 1.0, "CryptoX provider v1.0, implementing " +        "RSA encryption and key pair generation, and AES encryption.");

• set the values of various properties that are required for theJava Security API to look up the cryptographic services implementedby the provider. For each service implemented by the provider,there must be a property whose name is the type of service (forexample; Signature, MessageDigest, Cipher, KeyAgreement) Signature, MessageDigest, KeyPairGenerator, SecureRandom,KeyFactory, KeyStore, CertificateFactory,AlgorithmParameterGenerator, AlgorithmParameters, Cipher, KeyAgreement, KeyGenerator, Mac, SecretKeyFactory, orExemptionMechanism) followed by a period and the name of the algorithm to which theservice applies. The property value must specify the fullyqualified name of the class implementing the service.

• The list below shows the various types of JCA services, wherethe actual algorithm name is substitued foralgName:

  • Signature.algName
  • MessageDigest.algName
  • KeyPairGenerator.algName
  • SecureRandom.algName
  • AlgorithmParameterGenerator.algName
  • AlgorithmParameters.algName
  • KeyFactory.algName
  • CertificateFactory.algName
  • KeyStore.algName
  • Cipher.algName
  • KeyAgreement.algName
  • KeyGenerator.algName
  • Mac.algName
  • SecretKeyFactory.algName
  • ExemptionMechanism.algName

  In all of these exceptExemptionMechanism andCipher,algName, certType , orstoreType is the "standard" name of the algorithm,certificate type, or keystore type. SeeAppendix A of the Java CryptographyArchitecture Reference Guide for the standard names that shouldbe used.)

  In the case ofExemptionMechanism,algNamerefers to the name of the exemption mechanism, which can be one ofthe following:KeyRecovery,KeyEscrow, orKeyWeakening. Case doesnot matter.

  In the case ofCipher,algName may actuallyrepresent atransformation, and may be composed of analgorithm name, a particular mode, and a padding scheme. SeeAppendix A of the JavaCryptography Architecture Reference Guide for details.

  The value of each property must be the fully qualified name ofthe class implementing the specified algorithm, certificate type,or keystore type. That is, it must be the package name followed bythe class name, where the two are separated by a period.

  As an example, the default provider namedSUN implementsthe Digital Signature Algorithm (whose standard name isSHA256withDSA) in a class namedDSA in thesun.security.provider package. Its subclass ofProvider (which is the Sun class in thesun.security.provider package) sets theSignature.SHA256withDSA property to have the valuesun.security.provider.DSA via the following:

      put("Signature.SHA256withDSA", "sun.security.provider.DSA")

  The list below shows more properties that can be defined for thevarious types of services, where the actual algorithm name issubstitued foralgName, certificate type forcertType, keystore type forstoreType, and attributename forattrName:

  • Signature.algName[one or more spaces]attrName
  • MessageDigest.algName[one or more spaces]attrName
  • KeyPairGenerator.algName[one or more spaces]attrName
  • SecureRandom.algName[one or more spaces]attrName
  • KeyFactory.algName[one or more spaces]attrName
  • CertificateFactory.certType[one or more spaces]attrName
  • KeyStore.storeType[one or more spaces]attrName
  • AlgorithmParameterGenerator.algName[one or morespaces] attrName
  • AlgorithmParameters.algName[one or more spaces]attrName
  • Cipher.algName[one or more spaces]attrName
  • KeyAgreement.algName[one or more spaces]attrName
  • KeyGenerator.algName[one or more spaces]attrName
  • Mac.algName[one or more spaces]attrName
  • SecretKeyFactory.algName[one or more spaces]attrName
  • ExemptionMechanism.algName[one or more spaces]attrName

In each of these,algName, certType, storeType, orattrName is the "standard" name of the algorithm,certificate type, keystore type, or attribute. (See Appendix A ofthe Java Cryptography Architecture Reference Guide for the standardnames that should be used.)

For a property in the above format, the value of the propertymust be the value for the corresponding attribute. (SeeAppendix A of the Java CryptographyArchitecture API Specification & Reference for the definitionof each standard attribute.)

As an example, the default provider named "SUN" implements theSHA256withDSA Digital Signature Algorithm in software.In the master class for the provider "SUN", it sets theSignature.SHA256withDSA ImplementedIn to have the valueSoftware via the following:

    put("Signature.SHA256withDSA ImplementedIn", "Software")

For further master class property setting examples, see the JDK 7 source codefor the following classes:

• sun.security.provider.Sun
• sun.security.provider.SunEntries
• com.sun.crypto.provider.SunJCE

These files show how theSun andSunJCE providers setproperties.

For each Message Digest and MAC algorithm, indicate whether ornot your implementation is cloneable. This is not technicallynecessary, but it may save clients some time and coding by tellingthem whether or not intermediate Message Digests or MACs may bepossible through cloning. Clients who do not know whether or not aMessageDigest orMac implementation iscloneable can find out by attempting to clone the object andcatching the potential exception, as illustrated by the followingexample:

    try {        // try and clone it        /* compute the MAC for i1 */        mac.update(i1);        byte[] i1Mac = mac.clone().doFinal();        /* compute the MAC for i1 and i2 */        mac.update(i2);        byte[] i12Mac = mac.clone().doFinal();        /* compute the MAC for i1, i2 and i3 */        mac.update(i3);        byte[] i123Mac = mac.doFinal();    } catch (CloneNotSupportedException cnse) {        // have to use an approach not involving cloning    }

where:

• mac is the MAC object they received when theyrequested one via a call toMac.getInstance,
• i1,i2 andi3 are inputbyte arrays, and
• they want to calculate separate hashes for:
  • i1
  • i1 and i2
  • i1, i2, and i3

Key Pair Generators

For a key pair generator algorithm, in case the client does notexplicitly initialize the key pair generator (via a call to aninitialize method), each provider must supply anddocument a default initialization. For example, the Diffie-Hellmankey pair generator supplied by theSunJCE provider uses adefault prime modulus size (keysize) of 1024 bits.

Key Factories

A provider should document all the key specifications supportedby its (secret-)key factory.

Algorithm Parameter Generators

In case the client does not explicitly initialize the algorithmparameter generator (via a call to aninit method intheAlgorithmParameterGenerator engine class), eachprovider must supply and document a default initialization. Forexample, theSunJCE provider uses a default prime modulussize (keysize) of 1024 bits for the generation ofDiffie-Hellman parameters, theSun provider a defaultmodulus prime size of 1024 bits for the generation of DSAparameters.

Signature Algorithms

If you implement a signature algorithm, you should document theformat in which the signature (generated by one of thesign methods) is encoded. For example, the SHA256withDSAsignature algorithm supplied by the "SUN" provider encodes thesignature as a standardASN.1 SEQUENCE of twointegers,r ands.

Random Number Generation (SecureRandom) Algorithms

For a random number generation algorithm, provide informationregarding how "random" the numbers generated are, and the qualityof the seed when the random number generator is self-seeding. Alsonote what happens when a SecureRandom object (and its encapsulatedSecureRandomSpi implementation object) is deserialized: Ifsubsequent calls to thenextBytes method (whichinvokes theengineNextBytes method of the encapsulatedSecureRandomSpi object) of the restored object yield the exact same(random) bytes as the original object would, then let users knowthat if this behaviour is undesirable, they should seed therestored random object by calling itssetSeedmethod.

Certificate Factories

A provider should document what types of certificates (and theirversion numbers, if relevant), can be created by the factory.

Keystores

A provider should document any relevant information regardingthe keystore implementation, such as its underlying dataformat.

Step 12: Make your Class Files andDocumentation Available to Clients

After writing, configuring, testing, installing and documentingyour provider software, make documentation available to yourcustomers.

How a Provider CanDo Self-Integrity Checking

FurtherImplementation Details and Requirements

Alias Names

For many cryptographic algorithms and types, there is a singleofficial "standard name" defined inAppendix A of theJava CryptographyArchitecture Reference Guide.

For example, "MD5" is the standard name for the RSA-MD5 MessageDigest algorithm defined by RSA DSI in RFC 1321.DiffieHellman is the standard for the Diffie-Hellmankey agreement algorithm defined in PKCS3.

In the JDK, there is an aliasing scheme that enables clients touse aliases when referring to algorithms or types, rather thantheir standard names. For example, the "SUN" provider's masterclass (Sun.java) defines the alias "SHA1/DSA" for thealgorithm whose standard name is "SHA1withDSA". Thus, the followingstatements are equivalent:

    Signature sig = Signature.getInstance("SHA1withDSA", "SUN");    Signature sig = Signature.getInstance("SHA1/DSA", "SUN");

Aliases can be defined in your "master class" (seeStep 3). To define an alias, create a propertynamed

Alg.Alias.engineClassName.aliasName

whereengineClassName is the name of an engine class(e.g.,Signature), andaliasName is your aliasname. Thevalue of the property must be the standardalgorithm (or type) name for the algorithm (or type) beingaliased.

As an example, the "SUN" provider defines the alias "SHA1/DSA"for the signature algorithm whose standard name is "SHA1withDSA" bysetting a property namedAlg.Alias.Signature.SHA1/DSAto have the valueSHA1withDSA via the following:

    put("Alg.Alias.Signature.SHA1/DSA", "SHA1withDSA");

Note that aliases defined by one provider are available only tothat provider and not to any other providers. Thus, aliases definedby theSunJCE provider are available only to theSunJCE provider.

ServiceInterdependencies

Some algorithms require the use of other types of algorithms.For example, a PBE algorithm usually needs to use a message digestalgorithm in order to transform a password into a key.

If you are implementing one type of algorithm that requiresanother, 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 theother type of algorithm, as supplied by the defaultSunprovider that is included with every Java SE Platform installation.For example, if you are implementing a PBE algorithm that requiresa message digest algorithm, you can obtain an instance of a classimplementing the SHA256 message digest algorithm by calling

       MessageDigest.getInstance("SHA256", "SUN")
   

3. Let your implementation of one algorithm use an instance of theother type of algorithm, as supplied by another specific provider.This is only appropriate if you are sure that all clients who willuse your provider will also have the other provider installed.
4. Let your implementation of one algorithm use an instance of theother type of algorithm, as supplied by another (unspecified)provider. That is, you can request an algorithm by name, butwithout specifying any particular provider, as in

       MessageDigest.getInstance("SHA256")
   

   This is only appropriate if you are sure that there will be atleast one implementation of the requested algorithm (in this case,SHA256) installed on each Java platform where your provider will beused.

Here are some common types of algorithm interdependencies:

Signature and Message Digest Algorithms

A signature algorithm often requires use of a message digestalgorithm. For example, theSHA256withDSA signature algorithmrequires theSHA256 message digest algorithm.

Signature and (Pseudo-)Random Number Generation Algorithms

A signature algorithm often requires use of a (pseudo-)randomnumber generation algorithm. For example, such an algorithm isrequired in order to generate a DSA signature.

Key Pair Generation and Message Digest Algorithms

A key pair generation algorithm often requires use of a messagedigest algorithm. For example, DSA keys are generated using theSHA-256 message digest algorithm.

Algorithm Parameter Generation and Message DigestAlgorithms

An algorithm parameter generator often requires use of a messagedigest algorithm. For example, DSA parameters are generated usingthe SHA-256 message digest algorithm.

KeyStores and Message Digest Algorithms

A keystore implementation will often utilize a message digestalgorithm to compute keyed hashes (where thekey is auser-provided password) to check the integrity of a keystore andmake sure that the keystore has not been tampered with.

Key Pair Generation Algorithms and Algorithm ParameterGenerators

A key pair generation algorithm sometimes needs to generate anew set of algorithm parameters. It can either generate theparameters directly, or use an algorithm parameter generator.

Key Pair Generation, Algorithm Parameter Generation, and(Pseudo-)Random Number Generation Algorithms

A key pair generation algorithm may require a source ofrandomness in order to generate a new key pair and possibly a newset of parameters associated with the keys. That source ofrandomness is represented by aSecureRandom object.The implementation of the key pair generation algorithm maygenerate the key parameters itself, or may use an algorithmparameter generator to generate them, in which case it may or maynot initialize the algorithm parameter generator with a source ofrandomness.

Algorithm Parameter Generators and Algorithm Parameters

An algorithm parameter generator'sengineGenerateParameters method must return anAlgorithmParameters instance.

Signature and Key Pair Generation Algorithms or KeyFactories

If you are implementing a signature algorithm, yourimplementation'sengineInitSign andengineInitVerify methods will require passed-in keysthat are valid for the underlying algorithm (e.g., DSA keys for theDSS algorithm). You can do one of the following:

1. Also create your own classes implementing appropriateinterfaces (e.g. classes implementing theDSAPrivateKey andDSAPublicKey interfacesfrom the packagejava.security.interfaces), and createyour own key pair generator and/or key factory returning keys ofthose types. Require the keys passed toengineInitSignandengineInitVerify to be the types of keys you haveimplemented, that is, keys generated from your key pair generatoror key factory. Or you can,
2. Accept keys from other key pair generators or other keyfactories, as long as they are instances of appropriate interfacesthat enable your signature implementation to obtain the informationit needs (such as the private and public keys and the keyparameters). For example, theengineInitSign methodfor a DSS Signature class could accept any private keys that areinstances ofjava.security.interfaces.DSAPrivateKey.

KeyStores and Key and Certificate Factories

A keystore implementation will often utilize a key factory toparse the keys stored in the keystore, and a certificate factory toparse the certificates stored in the keystore.

DefaultInitializations

In case the client does not explicitly initialize a key pairgenerator or an algorithm parameter generator, each provider ofsuch a service must supply (and document) a default initialization.For example, theSun provider uses a default modulus size(strength) of 1024 bits for the generation of DSA parameters, andthe "SunJCE" provider uses a default modulus size (keysize) of 1024bits for the generation of Diffie-Hellman parameters.

Default Key PairGenerator Parameter Requirements

If you implement a key pair generator, your implementationshould supply default parameters that are used when clients don'tspecify parameters. The documentation you supply (Step 11) should state what the default parametersare.

For example, the DSA key pair generator in theSunprovider supplies a set of pre-computedp,q, andg default values for thegeneration of 512, 768, and 1024-bit key pairs. The followingp,q, andg values are usedas the default values for the generation of 1024-bit DSA keypairs:

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 d14801c7q = 9760508f 15230bcc b292b982 a2eb840b f0581cf5g = 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

(Thep andq values given here weregenerated by the prime generation standard, using the 160-bit

SEED:  8d515589 4229d5e6 89ee01e6 018a237e 2cae64cd

With this seed, the algorithm foundp andq when the counter was at 92.)

TheProvider.Service Class

Since its introduction, security providers have published theirservice information via appropriately formatted key-value Stringpairs they put in their Hashtable entries. While this mechanism issimple and convenient, it limits the amount customization possible.As a result, JDK 5.0 introduced a second option, theProvider.Service class. It offers an alternative wayfor providers to advertise their services and supports additionalfeatures as described below. Note that this addition is fullycompatible with the older method of using String valued Hashtableentries. A provider on JDK 5.0 can choose either method as itprefers, or even use both at the same time.

AProvider.Service object encapsulates allinformation about a service. This is the provider that offers theservice, its type (e.g.MessageDigest orSignature), the algorithm name, and the name of theclass that implements the service. Optionally, it also includes alist of alternate algorithm names for this service (aliases) andattributes, which are a map of (name, value) String pairs. Inaddition, it defines the methodsnewInstance() andsupportsParameter(). They have defaultimplementations, but can be overridden by providers if needed, asmay be the case with providers that interface with hardwaresecurity tokens.

ThenewInstance() method is used by the securityframework when it needs to construct new implementation instances.The default implementation uses reflection to invoke the standardconstructor for the respective type of service. For all standardservices exceptCertStore, this is the no-argsconstructor. TheconstructorParameter tonewInstance() must be null in theses cases. Forservices of typeCertStore, the constructor that takesaCertStoreParameters object is invoked, andconstructorParameter must be a non-null instance ofCertStoreParameters. A security provider can overridethenewInstance() method to implement instantiation asappropriate for that implementation. It could use direct invocationor call a constructor that passes additional information specificto the Provider instance or token. For example, if multipleSmartcard readers are present on the system, it might passinformation about which reader the newly created service is to beassociated with. However, despite customization all implementationsmust follow the conventions aboutconstructorParameterdescribed above.

ThesupportsParameter() tests whether the Servicecan use the specified parameter. It returns false if this servicecannot use the parameter. It returns true if this service can usethe parameter, if a fast test is infeasible, or if the status isunknown. It is used by the security framework with some types ofservices to quickly exclude non-matching implementations fromconsideration. It is currently only defined for the followingstandard services:Signature,Cipher,Mac, andKeyAgreement. Theparameter must be an instance ofKey in thesecases. For example, forSignature services, theframework tests whether the service can use the supplied Key beforeinstantiating the service. The default implementation examines theattributesSupportedKeyFormats andSupportedKeyClasses as described below. Again, aprovider may override this methods to implement additionaltests.

TheSupportedKeyFormats attribute is a list of thesupported formats for encoded keys (as returned bykey.getFormat()) separated by the "|" (pipe) character.For example,X.509|PKCS#8. TheSupportedKeyClasses attribute is a list of the namesof classes of interfaces separated by the "|" character. A keyobject is considered to be acceptable if it is assignable to atleast one of those classes or interfaces named. In other words, ifthe class of the key object is a subclass of one of the listedclasses (or the class itself) or if it implements the listedinterface. An example value is"java.security.interfaces.RSAPrivateKey|java.security.interfaces.RSAPublicKey".

Four methods have been added to the Provider class for addingand looking up Services. As mentioned earlier, the implementationof those methods and also of the existing Properties methods havebeen specifically designed to ensure compatibility with existingProvider subclasses. This is achieved as follows:

If legacy Properties methods are used to add entries, theProvider class makes sure that the property strings are parsed intoequivalent Service objects prior to lookup viagetService(). Similarly, if theputService()method is used, equivalent property strings are placed into theprovider's hashtable at the same time. If a provider implementationoverrides any of the methods in the Provider class, it has toensure that its implementation does not interfere with thisconversion. To avoid problems, we recommend that implementations donot override any of the methods in theProviderclass.

Signature Formats

If you implement a signature algorithm, the documentation yousupply (Step 11) should specify the format inwhich the signature (generated by one of thesignmethods) is encoded.

For example, theSHA256withDSA signature algorithm suppliedby theSun provider encodes the signature as a standardASN.1 sequence of twoASN.1 INTEGER values:r ands, in that order:

SEQUENCE ::= {        r INTEGER,        s INTEGER }

DSA Interfaces and theirRequired Implementations

The Java Security API contains the following interfaces (in thejava.security.interfaces package) for the convenienceof programmers implementing DSA services:

• DSAKey
• DSAKeyPairGenerator
• DSAParams
• DSAPrivateKey
• DSAPublicKey

The following sections discuss requirements for implementationsof these interfaces.

DSAKeyPairGeneratorImplementation

This interface is obsolete. It used to be needed to enableclients to provide DSA-specific parameters to be used rather thanthe default parameters your implementation supplies. However, inJava it is no longer necessary; a newKeyPairGeneratorinitialize method that takes anAlgorithmParameterSpec parameter enables clients toindicate algorithm-specific parameters.

DSAParamsImplementation

If you are implementing a DSA key pair generator, you need aclass implementingDSAParams for holding and returningthep,q, andgparameters.

ADSAParams implementation is also required if youimplement theDSAPrivateKey andDSAPublicKey interfaces.DSAPublicKey andDSAPrivateKey both extend the DSAKey interface, whichcontains agetParams method that must return aDSAParams object. SeeDSAPrivateKey and DSAPublicKeyImplementations for more information.

Note: there is aDSAParams implementationbuilt into the JDK: thejava.security.spec.DSAParameterSpec class.

DSAPrivateKeyandDSAPublicKeyImplementations

If you implement a DSA key pair generator or key factory, youneed to create classes implementing theDSAPrivateKeyandDSAPublicKey interfaces.

If you implement a DSA key pair generator, yourgenerateKeyPair method (in yourKeyPairGeneratorSpi subclass) will return instances ofyour implementations of those interfaces.

If you implement a DSA key factory, yourengineGeneratePrivate method (in yourKeyFactorySpi subclass) will return an instance ofyourDSAPrivateKey implementation, and yourengineGeneratePublic method will return an instance ofyourDSAPublicKey implementation.

Also, yourengineGetKeySpec andengineTranslateKey methods will expect the passed-inkey to be an instance of aDSAPrivateKey orDSAPublicKey implementation. ThegetParams method provided by the interfaceimplementations is useful for obtaining and extracting theparameters from the keys and then using the parameters, for exampleas parameters to theDSAParameterSpec constructorcalled to create a parameter specification from parameter valuesthat could be used to initialize aKeyPairGeneratorobject for DSA.

If you implement a DSA signature algorithm, yourengineInitSign method (in yourSignatureSpi subclass) will expect to be passed aDSAPrivateKey and yourengineInitVerifymethod will expect to be passed aDSAPublicKey.

Please note: TheDSAPublicKey andDSAPrivateKey interfaces define a very generic,provider-independent interface to DSA public and private keys,respectively. TheengineGetKeySpec andengineTranslateKey methods (in yourKeyFactorySpi subclass) could additionally check ifthe passed-in key is actually an instance of their provider's ownimplementation ofDSAPrivateKey orDSAPublicKey, e.g., to take advantage ofprovider-specific implementation details. The same is true for theDSA signature algorithmengineInitSign andengineInitVerify methods (in yourSignatureSpi subclass).

To see what methods need to be implemented by classes thatimplement theDSAPublicKey andDSAPrivateKey interfaces, first note the followinginterface signatures:

In thejava.security.interfaces package:

   public interface DSAPrivateKey extends DSAKey,                java.security.PrivateKey   public interface DSAPublicKey extends DSAKey,                java.security.PublicKey   public interface DSAKey

In thejava.security package:

   public interface PrivateKey extends Key   public interface PublicKey extends Key   public interface Key extends java.io.Serializable

In order to implement theDSAPrivateKey andDSAPublicKey interfaces, you must implement themethods they define as well as those defined by interfaces theyextend, directly or indirectly.

Thus, for private keys, you need to supply a class thatimplements

• thegetX method from theDSAPrivateKey interface.
• thegetParams method from thejava.security.interfaces.DSAKeyinterface, sinceDSAPrivateKey extendsDSAKey. Note: ThegetParams methodreturns aDSAParams object, so you must also have aDSAParamsimplementation.
• thegetAlgorithm,getEncoded, andgetFormat methods from thejava.security.Keyinterface, sinceDSAPrivateKey extendsjava.security.PrivateKey, andPrivateKeyextendsKey.

  Similarly, for public DSA keys, you need to supply a class thatimplements:

  • thegetY method from theDSAPublicKeyinterface.
  • thegetParams method from thejava.security.interfaces.DSAKeyinterface, sinceDSAPublicKey extends DSAKey. Note:ThegetParams method returns aDSAParamsobject, so you must also have aDSAParams implementation.
  • thegetAlgorithm,getEncoded, andgetFormat methods from thejava.security.Keyinterface, sinceDSAPublicKey extendsjava.security.PublicKey, andPublicKeyextendsKey.

RSA Interfaces and theirRequired Implementations

    public interface RSAPrivateKey extends java.security.PrivateKey    public interface RSAPrivateCrtKey extends RSAPrivateKey    public interface RSAPublicKey extends java.security.PublicKey

    public interface PrivateKey extends Key    public interface PublicKey extends Key    public interface Key extends java.io.Serializable

    public interface DHPrivateKey extends DHKey, java.security.PrivateKey    public interface DHPublicKey extends DHKey, java.security.PublicKey    public interface DHKey

    public interface PrivateKey extends Key    public interface PublicKey extends Key    public interface Key extends java.io.Serializable

    public BigInteger getP()    public BigInteger getQ()    public BigInteger getG()

    put("Alg.Alias.<engine_type>.1.2.3.4.5.6.7.8",        "<algorithm_alias_name>");

    % keytool -genkeypair -sigalg 1.2.3.4.5.6.7.8

    put("Signature.Foo", "com.xyz.MyFooSignatureImpl");    put("Alg.Alias.Signature.1.2.3.4.5.6.7.8", "Foo");

    put("KeyFactory.Foo", "com.xyz.MyFooKeyFactoryImpl");    put("Alg.Alias.KeyFactory.1.2.3.4.5.6.7.8", "Foo");

    put("Alg.Alias.Signature.OID.1.2.3.4.5.6.7.8", "MySigAlg");

<java-home>/lib/security/java.security     [Solaris, Linux, or macOS]<java-home>\lib\security\java.security     [Win32]

## 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: 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.pkcs11.SunPKCS11 \    ${java.home}/lib/security/sunpkcs11-solaris.cfgsecurity.provider.2=sun.security.provider.Sunsecurity.provider.3=sun.security.rsa.SunRsaSignsecurity.provider.4=com.sun.net.ssl.internal.ssl.Providersecurity.provider.5=com.sun.crypto.provider.SunJCEsecurity.provider.6=sun.security.jgss.SunProvidersecurity.provider.7=com.sun.security.sasl.Providersecurity.provider.8=org.jcp.xml.dsig.internal.dom.XMLDSigRIsecurity.provider.9=sun.security.smartcardio.SunPCSC# Rest of file deleted