The JavaTM Cryptography Extension
(JCE) provides a framework and implementations for encryption, key
generation and key agreement, and Message Authentication Code (MAC)
algorithms. Support for encryption includes symmetric, asymmetric,
block, and stream ciphers. The software also supports secure streams
and sealed objects.
JCE was previously an optional package (extension) to the
JavaTM 2 SDK, Standard Edition
(Java 2 SDK), versions 1.2.x and 1.3.x. JCE has now been integrated into the
Java 2 SDK, v 1.4.
JCE is based on the same design
principles found elsewhere in the Java Cryptography Architecture
framework utilized by all the cryptography-related security components
of the Java 2 platform: implementation independence and, whenever
possible, algorithm independence. It uses the same "provider"
architecture, which uses the notion of a Cryptographic Service
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.
JCE extends the list of cryptographic services of which a provider can
supply implementations. A provider could,
for example, contain an implementation of one or more digital signature
algorithms and one or more cipher algorithms.
A program wishing to use cryptography functionality
may simply request a particular type of object
(such as a Cipher object) implementing a particular
algorithm (such as DES) 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 Java 2 SDK installation has one or more provider packages installed.
Each provider package supplies implementations of cryptographic services
defined in one or more security components of the Java 2 SDK (including JCE).
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.
The Java 2 SDK, v 1.4 release comes standard with
a JCE provider named "SunJCE", which comes pre-installed and
registered and which supplies the following
cryptographic services:
An implementation of the DES (FIPS PUB 46-1), Triple DES, and
Blowfish encryption algorithms in the Electronic Code Book (ECB),
Cipher Block Chaining (CBC), Cipher Feedback (CFB), Output Feedback
(OFB), and Propagating Cipher Block Chaining (PCBC) modes. (Note:
Throughout this document, the terms "Triple DES" and "DES-EDE" will be
used interchangeably.)
Key generators for generating keys suitable for the DES, Triple
DES, Blowfish, HMAC-MD5, and HMAC-SHA1 algorithms.
An implementation of the MD5 with DES-CBC password-based encryption
(PBE) algorithm defined in PKCS #5.
"Secret-key factories" providing bi-directional conversions
between opaque DES, Triple DES and PBE key objects and transparent
representations of their underlying key material.
An implementation of the Diffie-Hellman key agreement algorithm between
two or more parties.
A Diffie-Hellman key pair generator for generating a pair of public and
private values suitable for the Diffie-Hellman algorithm.
A Diffie-Hellman algorithm parameter generator.
A Diffie-Hellman "key factory" providing bi-directional conversions
between opaque Diffie-Hellman key objects and transparent representations of
their underlying key material.
Algorithm parameter managers for Diffie-Hellman, DES, Triple DES,
Blowfish, and PBE parameters.
An implementation of the HMAC-MD5 and HMAC-SHA1 keyed-hashing algorithms
defined in RFC 2104.
An implementation of the padding scheme described in PKCS#5.
A keystore implementation for the proprietary keystore type named "JCEKS".
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.
Programmers that only need to use the Java Security API to
access existing cryptography algorithms and other services
do not need to read this document.
This document is intended for developers of cryptographic service providers.
It documents what you need to do in order
to integrate your provider into Java Security so that
your algorithms and other services can be found when Java
Security API clients request them.
Only providers signed by a trusted entity can be plugged into the JCE framework.
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 these packages:
The JCE within the Java 2 SDK, v 1.4 includes two software components:
the framework that defines and supports cryptographic services
that providers can supply implementations for.
This framework includes everything in
the javax.crypto package.
a provider named "SunJCE"
Throughout this document, the term "JCE" by itself refers to the JCE
framework in the Java 2 SDK, v 1.4. Whenever the JCE provider supplied with
the Java 2 SDK, v 1.4 is mentioned, it will be
referred to explicitly as the "SunJCE" provider.
JCE was previously an optional package (extension) to the
JavaTM 2 SDK, Standard Edition (Java 2 SDK),
versions 1.2.x and 1.3.x. JCE has now been integrated into
the Java 2 SDK, v 1.4. The SunJCE provider is also included and is automatically
registered in the java.security security properties file
included with the Java 2 SDK, v 1.4.
Due to import control restrictions, the jurisdiction policy files
shipped with the Java 2 SDK, v 1.4 allow "strong" but limited cryptography
to be used. An "unlimited" version of these files indicating no restrictions on
cryptographic strengths is available for those living in
eligible countries (which is most countries). You can download this version
and replace the strong cryptography versions supplied with the Java 2 SDK, v 1.4
with the unlimited ones. See
where <java-home> refers to the directory where the
runtime software is installed, which is the top-level directory of the
JavaTM 2 Runtime Environment (JRE)
or the jre directory in the
JavaTM 2 SDK (Java 2 SDK) software.
They have been moved to this standard location so that it is
easy to replace the strong cryptography versions that come with
the Java 2 SDK, v 1.4 with the unlimited ones.
In JCE 1.2.1, providers needed to include code to authenticate
the JCE framework to assure themselves of the integrity and
authenticity of the JCE that they plugged into. Now that JCE
is integrated into the Java 2 SDK, v 1.4, this is no longer necessary.
However, a provider whose framework authentication code
locates the JCE framework via protection
domain instead of following the recommendations in the
aforementioned JCE 1.2.1 JCE provider document will not work
in the Java 2 SDK, v 1.4. Now that JCE has been
integrated into the Java 2 SDK, v 1.4, the JCE framework has a null
code source just like any other class in the Java 2 SDK, v 1.4.
You can either modify your provider to follow the recommended
approach for authenticating the framework, or put in a conditional
so that the framework authentication code is only executed
when the provider is being run with JCE 1.2.1.
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,
and it either provides cryptographic operations
(like those for ciphers or key agreement protocols),
or generates or supplies the
cryptographic material (keys or parameters) required for cryptographic
operations. For example, two of the engine classes are the Cipher
and KeyAgreement classes. The Cipher
class provides access to the functionality of an encryption algorithm
(such as DES), and the
KeyAgreement class provides access to the functionality of a key
agreement protocol (such as Diffie-Hellman).
The Java Cryptography Architecture encompasses the classes of the
J2SE Java Security package related to cryptography, including the
engine classes. Users of the API request and utilize
instances of the engine classes to carry out corresponding operations.
JCE was previously an optional package (extension) to the
JavaTM 2 SDK, Standard Edition (Java 2 SDK),
versions 1.2.x and 1.3.x.
JCE has now been integrated into the Java 2 SDK, v 1.4.
JCE defines the following engine classes:
Cipher: used
to encrypt or decrypt some specified data.
KeyAgreement: used to execute a key agreement (key exchange)
protocol between 2 or more parties.
KeyGenerator: used to generate a secret (symmetric)
key suitable for a specified algorithm.
Mac: used to
compute the message authentication code of some specified data.
SecretKeyFactory: used to
convert opaque cryptographic keys of type SecretKey
into key specifications (transparent representations of the underlying
key material), and vice versa.
ExemptionMechanism: used to
provide the functionality of an exemption mechanism such as
key recovery, key weakening,
key escrow, or any other (custom) exemption mechanism.
Applications or applets that use an
exemption mechanism may be granted
stronger encryption capabilities than those which don't.
However, please note that cryptographic restrictions are no longer
required for most countries, and thus exemption mechanisms may only
be useful in those few countries whose governments mandate
restrictions.
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 Cipher engine
class, for example, provides access to the functionality of a
cipher algorithm. The actual implementation supplied
in a CipherSpi subclass (see next paragraph) would be that
for a specific kind of encryption
algorithm, such as DES or Triple DES.
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 Service Provider
Interface 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 Cipher engine class is the
CipherSpi 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 KeyAgreement class, which
provides access to a key agreement (key exchange) algorithm. Its
implementations, in KeyAgreementSpi subclasses, may be those of various
key agreement algorithms such as Diffie-Hellman.
As a final example, the SecretKeyFactory engine class supports the conversion
from opaque secret keys to transparent key specifications, and vice versa.
(See Key Specification Classes
Required by Key Factories.)
The actual implementation supplied in a SecretKeyFactorySpi subclass
would be that for a specific type of secret keys, e.g., DES keys.
The first thing you need to do is write the code supplying
algorithm-specific implementations of the cryptographic
services you want to support.
Note that your provider may supply implementations of cryptographic
services defined in one or more of the security components of
the Java 2 SDK v 1.4, including JCE.
In JCE in the Java 2 SDK, v 1.4 (as in the previous JCE 1.2.1 release), you can
supply cipher, key agreement and MAC algorithms, as
well as secret-key factories, secret-key generation services, and
exemption mechanism implementations.
For each cryptographic service in the Java 2 SDK (including JCE ones),
you need to create a subclass of the appropriate SPI class.
JCE defines the following engine classes:
CipherSpi, KeyAgreementSpi,
KeyGeneratorSpi, MacSpi,
SecretKeyFactorySpi, and ExemptionMechanismSpi. (See
Engine Classes and Corresponding SPI Classes
in this document for information on the JCE
and other cryptographic classes in the Java 2 SDK, v 1.4.)
Ensure there is a public constructor without any arguments. Here's why:
When one of your services is requested, Java Security looks up
the subclass implementing that service, 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 public
constructor without any parameters.
A default constructor without arguments will automatically be generated
if your subclass doesn't have any constructors. But if your subclass
defines any constructors, you must explicitly define a public
constructor without arguments.
Additional JCE Provider Requirements and Recommendations
When instantiating a provider's implementation (class) of a JCE
service, the JCE framework will determine the provider's codebase
(JAR file) and verify its signature. In this way,
JCE authenticates the
provider and ensures that only providers signed by a trusted entity can be plugged into JCE. Thus,
one requirement for JCE providers is that they must be signed,
as described in later steps.
In addition, each provider should perform self-integrity checking to ensure
that the JAR file containing its code has not been manipulated
in an attempt to invoke provider methods directly rather than
through JCE. For further information, see
How a Provider Can Do Self-Integrity Checking.
In order for provider classes to become unusable if instantiated by an
application directly, bypassing JCE, providers should implement
the following:
All SPI implementation classes in a provider package should be declared final
(so that they cannot be subclassed), and their (SPI) implementation methods
should be declared protected.
All crypto-related helper classes in a provider package should have
package-private
scope, so that they cannot be accessed from outside the provider package.
For providers that may be exported outside the U.S.,
CipherSpi implementations must include an implementation of the
engineGetKeySize method which, given a Key,
returns the key size. If there are restrictions on available
cryptographic strength specified in jurisdiction policy files,
each Cipher initialization method calls
engineGetKeySize and then compares the result with
the maximum allowable key size for the particular location and
circumstances of the applet or application being run.
If the key size is too large, the initialization method throws
an exception.
Additional optional features that providers may implement
are
the engineWrap and engineUnwrap methods of
CipherSpi. Wrapping a key enables secure
transfer of the key from one place to another. Information
about wrapping and unwrapping keys is provided in the
Wrapping and Unwrapping Keys
section of the Java Cryptography Extension (JCE) Reference Guide.
one or more exemption mechanisms. An exemption mechanism
is something such as key recovery, key escrow, or key weakening
which, if implemented and enforced, may enable
reduced cryptographic restrictions for an application
(or applet) that uses it.
For information on the requirements for apps that
utilize exemption mechanisms, see
How to Make Applications "Exempt"
from Cryptographic Restrictions
in the Java Cryptography Extension (JCE) Reference Guide.
The third step is to create a subclass of the
java.security.Provider class.
Your subclass should be a final class, and its
constructor should
call super, specifying the provider name (see
Step 2), version number,
and a string of information about the provider and algorithms it
supports. For example:
super("CryptoX", 1.0, "CryptoX provider v1.0, implementing " +
"RSA encryption and key pair generation, and DES encryption.");
set the values of various properties that are required
for the Java Security API to look up the cryptographic services
implemented by the provider.
For each service implemented by the provider, there must be a
property whose name is the type of service (Cipher,
KeyAgreement, KeyGenerator,
Mac, SecretKeyFactory, or
ExemptionMechanism),
followed by a period and the name of the
algorithm to which the service applies. The property value must
specify the fully qualified name of the class implementing the service.
The list below
shows the various types of properties that must be defined for
the various types of JCE services, where the actual algorithm
name is substitued for algName:
Cipher.algName
KeyAgreement.algName
KeyGenerator.algName
Mac.algName
SecretKeyFactory.algName
ExemptionMechanism.algName
In all of these except ExemptionMechanism and
Cipher, algName is the standard name of the
algorithm.
In the case of ExemptionMechanism, algName
refers to the name of the exemption mechanism, which can be one of the
following: KeyRecovery, KeyEscrow,
or KeyWeakening. Case does
not matter.
In the case of Cipher, algName may actually
represent a transformation, and may be composed of an algorithm
name, a particular mode, and a padding scheme.
(See Appendix A
of the Java Cryptography Extension (JCE) Reference Guide
for the standard algorithm names that should be used.)
The value of each property must be
the fully qualified name of the class implementing the
specified algorithm. That is, it must be the package name
followed by the class name, where the two are separated by
a period.
As an example, the "SunJCE" provider implements the
Diffie-Hellman key agreement algorithm in a class named
DHKeyAgreement
in the com.sun.crypto.provider package. Its subclass of
Provider (which is the SunJCE class in the
com.sun.crypto.provider package) sets the
KeyAgreement.DiffieHellman property to have the value
com.sun.crypto.provider.DHKeyAgreement via the following:
For further master class property setting examples, see
Appendix A to view the current
SunJCE.java source file. This shows
how the SunJCE class constructor sets all the properties
for the "SunJCE" provider.
As mentioned above, in the case of a Cipher property,
algName may actually represent a transformation.
A transformation is a string that describes the operation (or set
of operations) to be performed by a Cipher object on some given input.
A transformation always includes the name of a cryptographic
algorithm (e.g., DES), and may be followed by a mode
and a padding scheme.
A transformation is of the form:
algorithm/mode/padding, or
algorithm
(In the latter case,
provider-specific default values for the mode and padding scheme are used).
For example, the following is a valid transformation:
Cipher c = Cipher.getInstance("DES/CBC/PKCS5Padding");
When requesting a block cipher in stream cipher mode (e.g.,
DES in CFB or OFB mode), a client
may optionally specify the number of bits to be processed at a time,
by appending this number to the mode name as shown in the following sample
transformations:
If a number does not follow a stream cipher mode, a provider-specific
default is used. (For example, the "SunJCE" provider uses a default of
64 bits.)
A provider may supply a separate class for each combination
of algorithm/mode/padding. Alternatively, a provider may decide to provide more generic
classes representing sub-transformations corresponding to
algorithm or algorithm/mode or algorithm//padding
(note the double slashes);
in this case the requested mode and/or padding are set automatically by
the getInstance methods of Cipher, which invoke the
engineSetMode and engineSetPadding methods of the
provider's subclass of CipherSpi.
That is, a Cipher property in a provider master class may have one of
the formats shown in the table below.
Cipher Property Format
Description
Cipher.algName
A provider's subclass of CipherSpi implements algName
with pluggable mode and padding
Cipher.algName/mode
A provider's subclass of CipherSpi implements algName
in the specified mode, with pluggable padding
Cipher.algName//padding
A provider's subclass of CipherSpi implements algName
with the specified padding, with pluggable mode
Cipher.algName/mode/padding
A provider's subclass of CipherSpi implements algName
with the specified mode and padding
(See Appendix A
of the Java Cryptography Extension (JCE) Reference Guide for the
standard algorithm names, modes, and padding schemes
that should be used.)
For example, a provider may supply a subclass of CipherSpi
that implements DES/ECB/PKCS5Padding, one that implements
DES/CBC/PKCS5Padding, one that implements
DES/CFB/PKCS5Padding, and yet another one that implements
DES/OFB/PKCS5Padding. That provider would have the following
Cipher properties in its master class:
Cipher.DES/ECB/PKCS5Padding
Cipher.DES/CBC/PKCS5Padding
Cipher.DES/CFB/PKCS5Padding
Cipher.DES/OFB/PKCS5Padding
Another provider may implement a class for each of the above modes
(i.e., one class for ECB, one for CBC, one for CFB,
and one for OFB), one class for PKCS5Padding,
and a generic DES class that subclasses from CipherSpi.
That provider would have the following
Cipher properties in its master class:
Cipher.DES
The getInstance factory method of the Cipher
engine class follows these rules in order to instantiate a provider's
implementation of CipherSpi for a
transformation of the form "algorithm":
Check if the provider has registered a subclass of CipherSpi
for the specified "algorithm".
If the answer is YES, instantiate this
class, for whose mode and padding scheme default values (as supplied by
the provider) are used.
If the answer is NO, throw a NoSuchAlgorithmException
exception.
The getInstance factory method of the Cipher
engine class follows these rules in order to instantiate a provider's
implementation of CipherSpi for a
transformation of the form "algorithm/mode/padding":
Check if the provider has registered a subclass of CipherSpi
for the specified "algorithm/mode/padding" transformation.
If the answer is YES, instantiate it.
If the answer is NO, go to the next step.
Check if the provider has registered a subclass of CipherSpi
for the sub-transformation "algorithm/mode".
If the answer is YES, instantiate it, and call
engineSetPadding(padding) on the new instance.
If the answer is NO, go to the next step.
Check if the provider has registered a subclass of CipherSpi
for the sub-transformation "algorithm//padding" (note the double
slashes).
If the answer is YES, instantiate it, and call
engineSetMode(mode) on the new instance.
If the answer is NO, go to the next step.
Check if the provider has registered a subclass of CipherSpi
for the sub-transformation "algorithm".
If the answer is YES, instantiate it, and call
engineSetMode(mode) and
engineSetPadding(padding) on the new instance.
If the answer is NO, throw a NoSuchAlgorithmException
exception.
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.
The next step is to request a code-signing certificate so that
you can use it to sign your provider prior to testing. The certificate
will be good for both testing and production. It will be valid for
5 years.
Below are the steps you should use to get a
code-signing certificate.
For more information on the keytool tool, see keytool
(for Solaris)
(for Microsoft Windows).
(Note: This must be typed as a single line. Multiple lines
and indentation are used in the examples so that they are legible.)
This will generate a DSA keypair (a public key and an associated
private key) and store it in an entry in
the specified keystore.
The public key is stored in a self-signed certificate.
The keystore entry can subsequently be accessed using the specified
alias.
The option values in angle brackets ("<" and ">") represent the
actual values that must be supplied. For example, <alias> must be
replaced with whatever alias name you wish to be used to refer to the
newly-generated keystore entry in the future, and
<keystore file name>
must be replaced with the name of the keystore to be used.
Note: Do not surround actual values
with angle brackets. For example, if you want your alias to be
myTestAlias, specify the -alias
option as follows:
-alias myTestAlias
If you specify a keystore that doesn't yet exist, it will be created.
Note: If command lines you type are not allowed to be as long as
the keytool -genkey command you want to execute (for example,
if you are typing to a Microsoft Windows DOS prompt),
you can create and execute a plain-text
batch file containing the command. That is, create a new text file that
contains nothing but the full
keytool -genkey command. (Remember to type it all on one line.)
Save the file with a .bat extension.
Then in your DOS window, type the file name (with its path, if necessary).
This will cause the command in the batch file
to be executed.
Use keytool to generate a certificate signing request.
Here, <alias> is the alias for the DSA keypair entry created in
the previous step.
This command generates a Certificate Signing Request (CSR),
using the PKCS#10 format. It stores the CSR in the file whose
name is specified in <csr file name>.
Send the CSR, contact information, and other required documentation
to the JCE Code Signing Certification Authority.
Send, via email, the CSR and contact information (see below) to
javasoft-cert-request@sun.com.
Put the following in the Subject line of your email message:
Request a Certificate for Signing a JCE Provider
Put the contact information in the body of the
message and send the CSR file as a plain text attachment to the message.
If your mail tool has an option for specifying the encoding format
to be used for attachments, select the "MIME" option.
Note: The CSR file is just a
plain text file, in Base 64 encoding. Only the first and last lines
are human-readable.
Include the following contact information in the body of your message:
Company Name
Street Address (Not a post office box)
City
State/Province
Country
Company Telephone Number
Company Fax Number
Requester Name
Requester Telephone Number
Requester Email Address
Brief description of your company (size,
line of business, etc.)
All of the above information is required.
After the JCE Code Signing Certification Authority has received
your email message, they will send you a request number via email.
Once you receive this request number, you should print, fill out
and mail the
Certification Form for CSPs.
This form should be mailed to the address below. Be sure to
include the request number on the form so that your hardcopy mailing
can be matched to the email message containing your CSR and contact
information.
Sun Microsystems, Inc.
International Trade Services/Export Compliance
Attn: Encryption Export
4120 Network Circle MS: USCA12-204
Santa Clara, CA 95054
U.S.A.
After the JCE Code Signing Certification Authority has received
both your email message and the required form,
they will authenticate you,
the requester. Then they will create and sign
a code-signing certificate valid for 5 years.
You will receive an email message containing two
plain-text file attachments: one file containing this
code-signing certificate and another file containing
its own CA certificate, which authenticates its public key.
Use keytool to import the certificates received from the CA.
Once you have received the two certificates from the
JCE Code Signing Certification Authority, you can use keytool
to import them into your keystore.
First import
the CA's certificate as a "trusted certificate":
keytool -import -alias <alias for the CA cert>
-file <CA cert file name>
-keystore <keystore file name>
-storepass <keystore password>
Here, <alias> is the same alias as that which you created in
step 1 where you generated a DSA keypair. This command replaces
the self-signed certificate in the keystore entry specified by
<alias> with the one signed by the JCE Code Signing
Certification Authority.
Now that you have in your keystore a certificate from
an entity trusted by JCE (the JCE Code Signing Certification Authority),
you can place your provider code in a JAR file
(Step 5b) and then use that certificate to
sign the JAR file (Step 5c).
Place your provider code in a JAR file, in preparation
for signing it in the next step.
For more information on the jar tool, see jar
(for Solaris)
(for Microsoft Windows).
jar cvf <JAR file name> <list of classes, separated by spaces>
This command creates a JAR file with the specified name containing
the specified classes.
Sign the JAR file created in the previous step
with the code-signing certificate obtained
in Step 5a.
For more information on the jarsigner tool, see jarsigner
(for Solaris)
(for Microsoft Windows).
Here, <alias> is the alias into the keystore for the
entry containing the code-signing certificate received from the
JCE Code Signing Certification Authority (the same alias as that
specified in the commands in Step 5a).
You can test verification of the signature via the following:
jarsigner -verify <JAR file name>
The text "jar verified" will be displayed if the verification
was successful.
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.
Installing a provider is done in two steps: installing the provider
package classes, and configuring the provider.
The first thing you must do is make your classes available
so that they can be found when requested.
You ship your provider classes as a JAR (Java ARchive) file.
There are a two possible ways to install provider classes:
Install the JAR file containing the provider classes as an
"installed" or "bundled" extension.
Place the JAR file containing the provider classes
in your CLASSPATH.
The provider JAR file will be considered an installed
extension if it is placed in
the standard place for the JAR files of an installed extension:
Here <java-home> refers to the directory where the
runtime software is installed, which is the top-level directory of the
JavaTM 2 Runtime Environment (JRE)
or the jre directory in the
JavaTM 2 SDK (Java 2 SDK) software.
For example, if you have the Java 2 SDK, v 1.4
installed on Solaris in a directory named /home/user1/J2SDK1.4.0,
or on Microsoft Windows in a directory named C:\J2SDK1.4.0, then you
need to install the JAR file in the following directory:
Similarly, if you have the JRE, v 1.4
installed on Solaris in a directory named /home/user1/j2re1.4.0,
or on Microsoft Windows in a directory named C:\j2re1.4.0,
you need to install the JAR file in the following directory:
Here <java-home> refers to the directory where the JRE
was installed. For example, if you have the Java 2 SDK v 1.4
installed on Solaris in a directory named /home/user1/J2SDK1.4.0,
or on Microsoft indows in a directory named C:\J2SDK1.4.0, then you
need to edit the following file:
Similarly, if you have the Java 2 Runtime Environment, v 1.4
installed on Solaris in a directory named /home/user1/j2re1.4.0,
or on Windows in a directory named C:\j2re1.4.0, then you
need to edit this file:
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.
The Java 2 SDK, v 1.4 comes standard with a provider named "SUN", which is
automatically configured as a static provider in the
java.security properties file, as follows:
security.provider.1=sun.security.provider.Sun
(The "SUN" provider's master class is the
Sun class in the sun.security.provider
package.)
The JCE provider "SunJCE" and other security-related providers
shipped with the Java 2 platform are
also automatically configured as static providers.
To utilize another JCE provider, add a line registering the
alternate provider, giving it whatever preference order you prefer
(and making corresponding adjustments to the other providers'
orders, if needed).
Suppose that your master class is the CryptoX class in the
com.cryptox.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, and increment the preference order numbers for all other
providers whose numbers were greater than or equal to 2 before
your addition:
security.provider.2=com.cryptox.provider.CryptoX
Note: Providers may also be registered dynamically. To do so,
a program (such as your test program, to be written in
Step 6)
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 code which is granted the following permission:
where {name} is replaced by the actual provider name.
For example, if the provider name is "MyJCE" and if the
provider's code is in the myjce_provider.jar file in the
/localWork directory, then here is a sample policy file
grant statement granting that permission:
grant codeBase "file:/localWork/myjce_provider.jar" {
permission java.security.SecurityPermission
"insertProvider.MyJCE";
};
Whenever JCE providers are not installed extensions,
permissions must be granted for when applets or applications using JCE
are run while a security manager is installed.
There is typically a security manager installed whenever an applet is
running, and a security manager may be installed for an application
either via code in the application itself or via a command-line argument.
Permissions do not need to be granted to installed extensions,
since the default system
policy file
grants all permissions to installed extensions.
Whenever a client does not install your provider as an installed
extension, your provider may need the following
permissions granted to it in the client environment:
java.lang.RuntimePermission to get class protection domains.
The provider may need to get its own protection domain in the process
of doing self-integrity checking.
java.security.SecurityPermission to set provider properties.
To ensure your provider works when a security manager is
installed and the provider is not an installed extension,
you need to test such an installation and execution environment.
In addition, prior to testing you need to grant appropriate permissions to your provider
and to any other providers it uses. For example,
a sample statement granting permissions to a provider whose
name is "MyJCE" and whose code is in myjce_provider.jar appears
below. Such a statement could appear in a
policy file. In this example, the
myjce_provider.jar file is assumed
to be in the /localWork directory.
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 encrypted.
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 services are found.
For instance, if you implemented the DES encryption
algorithm, you could check to ensure it's found when requested by
using the following code (again substituting your
provider name for "MyPro"):
Cipher c = Cipher.getInstance("DES", "MyPro");
System.out.println("My Cipher algorithm name is " + c.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.
If your provider implements an exemption mechanism, you should
write a test applet or application that uses the exemption mechanism.
Such an applet/application also needs to be signed, and needs to have
a "permission policy file" bundled with it. See
How to Make Applications "Exempt"
from Cryptographic Restrictions
in the Java Cryptography Extension (JCE) Reference Guide
for complete information on
creating and testing such an application.
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.
Be sure to include testing of your programs using different
installation options (e.g. making the provider an installed extension
or placing it on the class path) and execution environments
(with or without a security manager running). Installation options
are discussed in Step 5d.
In particular, you need to ensure your provider works when a security manager is
installed and the provider is not an installed extension --
and thus the provider must have permissions granted to it; therefore,
you need to test such an installation and execution environment,
after granting required permissions to your provider
and to any other providers it uses, as described in
Step 5e.
If you find during testing that your code needs modification,
make the changes, recompile (Step 4),
place the updated provider code in a JAR file
(Step 5b), sign the JAR file
(Step 5c), re-install the provider
(Step 5d), if needed fix or add to the
permissions (Step 5e), and then re-test
your programs. Repeat these steps as needed.
All U.S. vendors whose providers may be exported outside
the U.S. should apply to the Bureau of Export Administration
in the U.S. Department of Commerce for export approval.
Please consult your export
counsel for more information.
Note: If your provider calls Cipher.getInstance()
and the returned Cipher object needs to perform strong cryptography
regardless of what
cryptographic strength is allowed by the user's downloaded
jurisdiction policy files, you should include a copy of the
cryptoPerms permission policy file which you intend
to bundle in the JAR file for your provider and which
specifies an appropriate permission for the required cryptographic strength.
The necessity for this file is just like the requirement that applets and
applications "exempt" from cryptographic restrictions must include
a cryptoPerms permission policy file in their
JAR file. For more information on the creation and inclusion of
such a file, see
How to Make Applications "Exempt"
from Cryptographic Restrictions
in the Java Cryptography Extension (JCE) Reference Guide.
The next step is to write documentation for your clients. At the
minimum, you need to specify:
the name programs should use to refer to your provider.
Note: As of this writing, provider name searches are
case-sensitive. That is, if your master class
specifies your provider name as "CryptoX" but a user requests
"CRYPTOx", your provider will not be found. This behavior may
change in the future, but for now be sure to warn your
clients to use the exact case you specify.
the types of algorithms and other services implemented by your provider.
instructions for installing the provider, similar to those provided
in Step 5d, except that the information and
examples should be specific to your provider.
the permissions your provider will require if it is not installed
as an installed extension and if a security manager is run,
as described in Step 5e.
In addition, your documentation should specify anything else of
interest to clients, such as any default algorithm parameters.
MACs
For each MAC 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 "message authentication codes" (MACs)
may be possible through
cloning. Clients who do not know whether or not a MAC implementation is
cloneable can find out by attempting
to clone the Mac object and catching the
potential exception, as illustrated by the following example:
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 they requested one via a call to
Mac.getInstance,
i1,
i2 and i3 are input byte 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 not explicitly initialize the key pair generator
(via a call to an initialize method),
each provider must supply and document a default initialization.
For example, the Diffie-Hellman key pair generator supplied by the "SunJCE"
provider uses a default prime modulus size (keysize) of 1024 bits.
Key Factories
A provider should document all the key specifications supported by its
(secret-)key factory.
Algorithm Parameter Generators
In case the client does not explicitly initialize the algorithm
parameter generator (via a call to an init method in the
AlgorithmParameterGenerator engine class), each provider must supply
and document a default initialization. For example, the "SunJCE"
provider uses a default prime modulus size (keysize) of 1024 bits for
the generation of Diffie-Hellman parameters.
Each provider should do self-integrity checking to ensure that the JAR file
containing its code has not been tampered with, for example in an attempt
to invoke provider methods directly rather than through JCE. Providers that
provide implementations for JCE services must be digitally signed and should
be signed with a certificate issued by "trusted" Certification Authorities.
Currently, the following two Certification Authorities are considered
"trusted":
Sun Microsystems' JCE Code Signing CA, and
IBM JCE Code Signing CA.
Please refer to Step 5b
for detailed information on how to get a
code-signing certificate from Sun Microsystems'
JCE Code Signing CA and the certificate of that CA.
After getting the signing certificate from above Certification Authority,
provider packages should embed within themselves the bytes for its own
signing certificate, for example in an array like the
bytesOfProviderCert array referred to in the
Identifying Each of the Signers and
Determining If One is Trusted section below.
At runtime, the embedded certificate will be used in
determining whether or not the provider code is authentic.
The basic approach a provider can use to check its own
integrity is:
Determine the URL of the JAR file containing the provider code, and
Verify the JAR file's digital signatures to
ensure that at least one signer of each entry of
the JAR file is trusted.
Each of these steps is described in the following sections:
Note: The sample code
MyJCE.java
is a complete code example that implements these steps.
You can download this code for your reference. The
Notes on the Sample Code
section traces how these concepts are implemented in the sample code.
IMPORTANT NOTE:
In JCE 1.2.1, providers needed to include code to authenticate
the JCE framework to assure themselves of the integrity and
authenticity of the JCE that they plugged into. Now that JCE
is integrated into the Java 2 SDK, v 1.4, this is no longer necessary.
One implication is that a provider written just for JCE 1.2.1
will not work in the Java 2 SDK, v 1.4 because the provider's JCE
framework authentication check will not work; the JCE framework
code is no longer where the provider expects it to be.
If you want your provider to work only with the Java 2 SDK, v 1.4,
it should not have code to authenticate the JCE framework.
On the other hand, if you want your provider to work both with
JCE 1.2.1 and with the JCE in the Java 2 SDK, v 1.4, then add a
conditional statement. This way the provider
code to authenticate the JCE framework is executed only when
the provider is run with JCE 1.2.1.
The following is sample code:
The URL for the provider's JAR file can be
obtained by determining the provider's CodeSource and then
calling the getLocation method on the CodeSource.
Once you have the URL for the provider's JAR file, you can
create a java.util.jar.JarFile
referring to the JAR file.
This instance is needed in the
step for verifying the Provider JAR file.
To create the JAR file, first open a connection
to the specified URL by calling its openConnection
method. Since the URL is a JAR URL, the type is
java.net.JarURLConnection. Here's the basic code:
// Prep the url with the appropriate protocol.
jarURL =
url.getProtocol().equalsIgnoreCase("jar") ?
url :
new URL("jar:" + url.toString() + "!/");
// Retrieve the jar file using JarURLConnection
JarFile jf = (JarFile) AccessController.doPrivileged(
new PrivilegedExceptionAction() {
public Object run() throws Exception {
JarURLConnection conn =
(JarURLConnection) jarURL.openConnection();
...
Now that you have a JarURLConnection, you can call its
getJarFile method to get the JAR file:
// Always get a fresh copy, so we don't have to
// worry about the stale file handle when the
// cached jar is closed by some other application.
conn.setUseCaches(false);
jf = conn.getJarFile();
Once you have determined the URL for your provider
JAR file and you have created a JarFile
referring to the JAR file, as shown in the steps above,
you can then verify the file.
The basic approach is:
Ensure that at least one of each entry's signer's
certificates is equal to the provider's own code signing certificate.
Go through all the entries in the JAR file and ensure the
signature on each one verifies correctly.
Ensure that at least one of each entry's signer's certificates can be
traced back to a trusted Certification Authority.
Sample code for each of these steps is presented
and described in the following sections:
Our approach is to define a class JarVerifier to
handle the retrieval of a JAR file from a given URL and verify
whether the JAR file is signed with the specified certificate.
The constructor of JarVerifier takes the provider
URL as a parameter which will be used to retrieve the JAR file later.
The actual jar verification is implemented in the
verify method which takes the provider code signing
certificate as a parameter.
public void verify(X509Certificate targetCert)
throws IOException {
// variable 'jarFile' is a JarFile object created
// from the provider's Jar URL.
...
Vector entriesVec = new Vector();
Basically the
verify method will go through the JAR file
entries twice:
the first time checking the signature on each entry
and the second time verifying the signer is trusted.
Note: In our code snippets the jarFile variable
is the JarFile object of
the provider's jar file.
An authentic provider JAR file is signed. So the JAR file
has been tampered with if it isn't signed:
// Ensure the jar file is signed.
Manifest man = jarFile.getManifest();
if (man == null) {
throw new SecurityException("The provider is not signed");
}
The next step is to go through all the entries in the JAR file
and ensure the signature on each one verifies correctly.
One possible way to verify the signature on a JAR file entry
is to simply read the file. If a JAR file is signed,
the read method itself automatically
performs the signature verification. Here is sample code:
// Ensure all the entries' signatures verify correctly
byte[] buffer = new byte[8192];
Enumeration entries = jarFile.entries();
while (entries.hasMoreElements()) {
JarEntry je = (JarEntry) entries.nextElement();
// Skip directories.
if (je.isDirectory()) continue;
entriesVec.addElement(je);
InputStream is = jarFile.getInputStream(je);
// Read in each jar entry. A security exception will
// be thrown if a signature/digest check fails.
int n;
while ((n = is.read(buffer, 0, buffer.length)) != -1) {
// Don't care
}
is.close();
}
The code in the previous section verified the
signatures of all the provider JAR file entries. The
fact that they all verify correctly is a requirement,
but it is not sufficient to verify the authenticity
of the JAR file. A final requirement is that the signatures were
generated by the same entity as the one that developed this provider.
To test that the signatures are trusted, we can again go through each entry
in the JAR file (this time using the entriesVec
built in the previous step), and for each entry that
must be signed (that is, each entry that is not a directory
and that is not in the META-INF directory):
Get the list of signer certificates for the entry.
Identify each of the certificate chains and determine
whether any of the certificate chains are
trusted. At least one of the certificate chains must be trusted.
The loop setup is the following:
Enumeration e = entriesVec.elements();
while (e.hasMoreElements()) {
JarEntry je = (JarEntry) e.nextElement();
...
}
The certificates for the signers of a JAR file entry
JarEntry can be obtained simply by calling the
JarEntrygetCertificates method:
Certificate[] certs = je.getCertificates();
Adding this line of code to the previous loop setup code, and
adding code to ignore directories and files in the
META-INF directory gives us:
while (e.hasMoreElements()) {
JarEntry je = (JarEntry) e.nextElement();
// Every file must be signed except files in META-INF.
Certificate[] certs = je.getCertificates();
if ((certs == null) || (certs.length == 0)) {
if (!je.getName().startsWith("META-INF"))
throw new SecurityException("The provider " +
"has unsigned " +
"class files.");
} else {
// Check whether the file is signed by the expected
// signer. The jar may be signed by multiple signers.
// See if one of the signers is 'targetCert'.
...
}
...
The certificate array returned by the JarEntrygetCertificates method contains one or more
certificate chains.
There is one chain per signer of the entry. Each chain contains
one or more certificates. Each certificate in a chain authenticates
the public key in the previous certificate.
The first certificate in a chain is the signer's certificate which contains
the public key corresponding to the private key actually used to sign the
entry. Each subsequent certificate is a certificate for the issuer of the
previous certificate. Since the self-integrity check is based on whether
the JAR file is signed with the provider's signing cert, the trust decision
will be made upon only the first certificate, the signer's
certificate.
We need to go through the array of certificate chains and
check each chain and the associated signers
until we find a trusted entity. For each JAR
file entry, at least one of the signers must be trusted.
A signer is considered "trusted" if and only if its certificate is
equals to the embedded provider signing certificate.
The following sample code loops through all the certificate chains,
compares the first certificate in a chain to the embedded provider
signing certificate, and only returns true if a match is found.
int startIndex = 0;
X509Certificate[] certChain;
boolean signedAsExpected = false;
while ((certChain = getAChain(certs, startIndex)) != null) {
if (certChain[0].equals(targetCert)) {
// Stop since one trusted signer is found.
signedAsExpected = true;
break;
}
// Proceed to the next chain.
startIndex += certChain.length;
}
if (!signedAsExpected) {
throw new SecurityException("The provider " +
"is not signed by a " +
"trusted signer");
}
The getAChain method is defined as follows:
/**
* Extracts ONE certificate chain from the specified certificate array
* which may contain multiple certificate chains, starting from index
* 'startIndex'.
*/
private static X509Certificate[] getAChain(Certificate[] certs,
int startIndex) {
if (startIndex > certs.length - 1)
return null;
int i;
// Keep going until the next certificate is not the
// issuer of this certificate.
for (i = startIndex; i < certs.length - 1; i++) {
if (!((X509Certificate)certs[i + 1]).getSubjectDN().
equals(((X509Certificate)certs[i]).getIssuerDN())) {
break;
}
}
// Construct and return the found certificate chain.
int certChainSize = (i-startIndex) + 1;
X509Certificate[] ret = new X509Certificate[certChainSize];
for (int j = 0; j < certChainSize; j++ ) {
ret[j] = (X509Certificate) certs[startIndex + j];
}
return ret;
}
Notes on the Sample Code
The sample code, MyJCE.java, is
a sample provider which has a method selfIntegrityChecking
which performs self-integrity checking. It first determines the URL
of its own provider JAR file and then verifies that the provider JAR file
is signed with the embedded code-signing certificate.
Note: The method selfIntegrityChecking should be
called by all the constructors of its cryptographic engine classes
to ensure that its integrity is not compromised.
Provider MyJCE performs self-integrity checking in the
following steps:
Determine the URL to access the provider JAR file using its
own class, MyJCE.class.
Instantiate a JarVerifier object with the
provider URL in Step 1.
Create a X509Certificate object from the
embedded byte array bytesOfProviderCert.
Call the JarVerifier.verify method to verify all
entries in the provider JAR file are signed and are signed with the
same certificate instantiated in Step 3.
Note: The class JarVerifier will retrieve
the JAR file from the given URL, make sure the JAR file is signed,
all entries have valid signatures, and that entries are signed
with the specified X509Certificate.
A security exception is thrown by JarVerifier.verify
in several cases:
The certificate passed to verify is null (invalid).
When unable to retrieve JAR file from the given URL.
The provider is not signed. (The jar has no manifest.)
The provider has unsigned class files.
The provider is not signed with the specified certificate.
The MyJCE.java sample code is
comprised of the code snippets shown above. In addition, it
includes error handling, sample code signing certificate bytes, and code for
instantiating a X509Certificate object from the embedded
sample code signing certificate bytes.
Regarding the use of
AccessController.doPrivileged, please see
API For Privileged Blocks
for information on the use of doPrivileged.
For many cryptographic algorithms, there is a single official "standard name."
The standard names defined by JCE in the Java 2 SDK, v 1.4 are listed in
Appendix A
of the Java Cryptography Extension (JCE) Reference Guide.
For example, DiffieHellman is the standard name for the
Diffie-Hellman key agreement algorithm defined in PKCS #3.
JCE uses the same aliasing scheme for algorithm names as the rest of
the security products in the Java 2 SDK, v 1.4.
That scheme enables clients to use
aliases when referring to algorithms, rather than their standard names.
For example, the "SunJCE" provider's master class
(SunJCE.java) defines the alias "DH" for the key agreement whose
standard name is DiffieHellman. Thus, the following statements are
equivalent:
KeyAgreement ka = KeyAgreement.getInstance("DiffieHellman", "SunJCE");
KeyAgreement ka = KeyAgreement.getInstance("DH", "SunJCE");
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 Cipher,
KeyAgreement, KeyGenerator,
Mac, SecretKeyFactory, or
ExemptionMechanism, and
aliasName is your alias name. For all but
ExemptionMechanism, the value of the property
must be the standard algorithm name for the algorithm being aliased.
For ExemptionMechanism, the value is the exemption mechanism
name (KeyRecovery, KeyEscrow, or
KeyWeakening).
As an example, the "SunJCE" provider
defines the alias "DH" for the key agreement
algorithm whose standard name is "DiffieHellman" by setting a property
named Alg.Alias.KeyAgreement.DH to have the value
DiffieHellman via the following:
Currently, aliases defined by the "SunJCE" provider are available to
all clients, no matter which provider clients request. For example, if
you create a provider named "MyPro" that implements the
Diffie-Hellman algorithm,
then even if you don't define
any aliases for it, the "DH" alias defined by "SunJCE" can be used
to refer to your provider's Diffie-Hellman implementation as follows:
KeyAgreement ka = KeyAgreement.getInstance("DH", "MyPro");
Some algorithms require the use of other types of algorithms.
For example, a PBE algorithm usually needs to use a message
digest algorithm in order to transform a password into a key.
If you are implementing one type of algorithm that requires
another, you can do one of the following:
Provide your own implementations for both.
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 Java 2 Platform installation. For example, if you
are implementing a PBE 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")
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.
Let your implementation of one algorithm
use an instance of the other type of algorithm, as supplied by
another (unspecified) provider. That is, you can request an algorithm
by name, but without specifying any particular provider, as in
MessageDigest.getInstance("MD5")
This is only appropriate if you are sure that there will be at
least one implementation of the requested algorithm (in this case,
MD5) installed on each Java platform where
your provider will be used.
In case the client does not explicitly initialize a key pair generator
or an algorithm parameter generator, each provider of such a service must
supply (and document) a default initialization.
For example, the "SunJCE" provider uses a default modulus size (keysize)
of 1024 bits for the generation of Diffie-Hellman parameters.
JCE contains the following interfaces
(in the javax.crypto.interfaces package)
for the convenience of programmers implementing Diffie-Hellman services:
If you implement a Diffie-Hellman key pair generator or key factory, you
need to create classes implementing the DHPrivateKey and
DHPublicKey interfaces.
If you implement a Diffie-Hellman key pair generator, your
generateKeyPair method (in your
KeyPairGeneratorSpi subclass) will return instances
of your implementations of those interfaces.
If you implement a Diffie-Hellman key factory, your
engineGeneratePrivate method (in your
KeyFactorySpi subclass) will return an instance
of your DHPrivateKey implementation, and your
engineGeneratePublic method will return an instance
of your DHPublicKey implementation.
Also, your engineGetKeySpec and
engineTranslateKey methods
will expect the passed-in key to be an instance of
a DHPrivateKey or DHPublicKey implementation.
The getParams method provided by the interface
implementations is useful for obtaining and extracting the
parameters from the keys. You can then use the parameters, for example,
as parameters to the DHParameterSpec
constructor called to create a parameter specification from
parameter values used to initialize a
KeyPairGenerator object for Diffie-Hellman.
If you implement the Diffie-Hellman key agreement algorithm, your
engineInit method (in your
KeyAgreementSpi subclass) will expect to be passed a
DHPrivateKey and your engineDoPhase method
will expect to be passed a DHPublicKey.
Note: The DHPublicKey and DHPrivateKey interfaces
define a very generic, provider-independent interface to Diffie-Hellman public
and private keys, respectively. The engineGetKeySpec and
engineTranslateKey methods (in your KeyFactorySpi
subclass) could additionally check if the passed-in key is actually
an instance of their provider's own implementation
of DHPrivateKey or DHPublicKey, e.g., to take advantage of provider-specific
implementation details. The same is true for the Diffie-Hellman
algorithm
engineInit and engineDoPhase methods (in your
KeyAgreementSpi subclass).
To see what methods need to be implemented by classes that
implement the DHPublicKey and DHPrivateKey interfaces, first
note the following interface signatures:
In the javax.crypto.interfaces package:
public interface DHPrivateKey extends DHKey,
java.security.PrivateKey
public interface DHPublicKey extends DHKey,
java.security.PublicKey
public interface DHKey
In the java.security package:
public interface PrivateKey extends Key
public interface PublicKey extends Key
public interface Key extends java.io.Serializable
To implement the DHPrivateKey and
DHPublicKey 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 getAlgorithm, getEncoded, and
getFormat methods from the
java.security.Key interface, since DHPrivateKey
extends java.security.PrivateKey, and PrivateKey
extends Key.
Similarly, for public Diffie-Hellman keys, you need to supply a class that
implements:
the getAlgorithm, getEncoded, and
getFormat methods from the
java.security.Key interface, since DHPublicKey
extends java.security.PublicKey, and PublicKey
extends Key.
An algorithm parameter specification is a transparent representation of
the sets of parameters used with an algorithm.
A transparent representation of parameters means that you can access
each value individually, through one of the "get" methods defined
in the corresponding specification class (e.g., DHParameterSpec
defines getP, getG, and
getL methods, to access the p, g,
and l parameters, respectively).
This is contrasted with an opaque representation, as supplied by the
AlgorithmParameters engine class, in which
you have no direct access to the key material values;
you can only get the name of the algorithm associated with the
parameter set (via getAlgorithm) and some kind of encoding for
the
parameter set (via getEncoded).
If you supply an AlgorithmParametersSpi,
AlgorithmParameterGeneratorSpi,
or KeyPairGeneratorSpi implementation, you must utilize the
AlgorithmParameterSpec interface, since each of those classes
contain methods that take an AlgorithmParameterSpec parameter.
Such methods need to determine which actual implementation of
that interface has been passed in, and act accordingly.
JCE contains a number of AlgorithmParameterSpec implementations for
the most frequently used cipher and key agreement algorithm parameters.
If you are operating on
algorithm parameters that should be for a different type of
algorithm not provided by JCE, you will need to supply your own
AlgorithmParameterSpec
implementation appropriate for that type of algorithm.
JCE defines the following algorithm parameter specification
classes in the javax.crypto.spec package:
This class (which implements the AlgorithmParameterSpec interface)
specifies the set of parameters used with a password-based encryption (PBE)
algorithm.
This class (which implements the AlgorithmParameterSpec interface)
specifies the set of parameters used with
the Diffie-Hellman algorithm.
Methods in DHParameterSpec
Method
Description
BigInteger getG()
Returns the base generator g.
int getL()
Returns the size in bits, l, of the random exponent (private value).
BigInteger getP()
Returns the prime modulus p.
Many types of Diffie-Hellman services will find this class useful; for
example, it is used by the Diffie-Hellman key agreement, key pair
generator, algorithm parameter generator, and algorithm parameters classes
implemented by the "SunJCE" provider. As a specific example, an
algorithm parameters implementation must include an implementation
for the getParameterSpec method, which returns an
AlgorithmParameterSpec. The Diffie-Hellman algorithm parameters implementation
supplied by "SunJCE" returns an instance of the DHParameterSpec class.
This class implements the
KeySpec
interface. A user-chosen password can be used with password-based
encryption (PBE); the password can be viewed as a type of raw key
material. An encryption mechanism that uses this class can
derive a cryptographic key from the raw key material.
Methods in PBEKeySpec
Method
Description
void clearPassword
Clears the internal copy of the password.
int getIterationCount
Returns the iteration count or 0 if not specified.
int getKeyLength
Returns the to-be-derived key length or 0 if not specified.
char[] getPassword
Returns a copy of the password.
byte[] getSalt
Returns a copy of the salt or null if not specified.
This class implements the KeySpec
interface. Since it also implements the
SecretKey interface, it
can be used to construct a SecretKey object in a
provider-independent fashion, i.e., without having to go through a
provider-based SecretKeyFactory.
Methods in SecretKeySpec
Method
Description
boolean equals (Object obj)
Indicates whether some other object is "equal to" this one.
String getAlgorithm()
Returns the name of the algorithm associated with this secret key.
byte[] getEncoded()
Returns the key material of this secret key.
String getFormat()
Returns the name of the encoding format for this secret key.
If you provide a secret-key generator (subclass of
javax.crypto.KeyGeneratorSpi) for a particular secret-key
algorithm, you may return the generated secret-key object (which must
be an instance of javax.crypto.SecretKey, see engineGenerateKey)
in one of the following ways:
You implement a class whose instances represent secret-keys
of the algorithm associated with your key generator. Your key
generator implementation returns instances of that class. This
approach is useful if the keys generated by your key generator have
provider-specific properties.
Your key generator returns an instance of SecretKeySpec,
which already implements the javax.crypto.SecretKey
interface. You pass the (raw) key bytes and the name of the
secret-key algorithm associated with your key generator to the
SecretKeySpec constructor. This approach is useful if the
underlying (raw) key bytes can be represented as a byte array and have
no key-parameters associated with them.
A key feature of JCE is the exportability
of the JCE framework and of the provider cryptography implementations
if certain conditions are met.
Due to import control restrictions by the governments of a few
countries, the jurisdiction policy files shipped with the Java 2 SDK, v 1.4 from
Sun Microsystems specify that "strong" but limited cryptography may be used.
An "unlimited" version of these files indicating no restrictions on
cryptographic strengths is available for those living in
eligible countries (which is most countries). But only the
"strong" version can be imported into those countries whose
governments mandate restrictions.
The JCE framework will enforce the restrictions specified in
the installed jurisdiction policy files.
As noted elsewhere, you can write just one version of your provider
software, implementing cryptography of maximum strength.
It is up to JCE, not your provider, to enforce
any jurisdiction policy file-mandated
restrictions regarding the cryptographic algorithms
and maximum cryptographic strengths
available to applets/applications in different locations.
The conditions that must be met by your provider in order to
enable it to be plugged into JCE in the Java 2 SDK, v 1.4 are the following:
The provider code should be written in such a way
that provider classes become unusable if instantiated by an
application directly, bypassing JCE. See
Step 1: Write Your Service Implementation Code
in the Steps to Implement
and Integrate a Provider section.
The provider package must be signed by an entity trusted by the
JCE framework. (See Step 5a through
Step 5c.) U.S. vendors whose providers may be
exported outside the U.S. first need to apply for U.S. government
export approval. (See Step 8.)
Below is an edited version of the SunJCE.java file,
which contains a class named SunJCE that is the
master class for the provider named "SunJCE".
As with all master classes, this class is a subclass
of Provider. It specifies the class names and package locations
of all the cryptographic service implementations
supplied by the "SunJCE" provider. This information is used by the
getInstance methods of the engine classes
to look up the various algorithms and other services
when they are requested.
This code is supplied as an example of a provider master class.
Below is an example of an EMProvider.java file,
which contains a class named EMProvider that is the
master class for the provider named "EMProvider".
As with all master classes, this class is a subclass
of Provider. It specifies the class names and package locations
of all the cryptographic service implementations
supplied by the "EMProvider" provider. This information is used by the
getInstance methods of the engine classes
to look up the various algorithms and other services
when they are requested.
This code is supplied as an example of a master class for a
provider that implements an
exemption mechanism.
It is included
in addition to the Appendix A showing the master class
for the "SunJCE" provider because the "SunJCE" provider does
not include any exemption mechanism implementations.
Note: A provider can implement both cryptographic services and
exemption mechanism services.
package com.abc.crypto.provider;
import java.security.AccessController;
import java.security.Provider;
/**
* The "EMProvider" Cryptographic Service Provider.
*
* @version 1.00, 03/15/2000
*/
/**
* Defines the "EMProvider" provider.
*
* Supported algorithm(s) and their name(s):
*
* - Key Recovery
*/
public final class EMProvider extends Provider {
private static String info = "EMProvider Exemption Mechanism Provider " +
"(implements KeyRecovery)";
public EMProvider() {
/* We are the "EMProvider" provider */
super("EMProvider", 1.2, info);
AccessController.doPrivileged(new java.security.PrivilegedAction() {
public Object run() {
/*
* Algorithm Parameter engines
*/
put("AlgorithmParameters.KeyRecovery",
"com.abc.crypto.provider.KeyRecoveryParameters");
put("Alg.Alias.AlgorithmParameters.KR", "KeyRecovery");
/*
* ExemptionMechanism
*/
put("ExemptionMechanism.KeyRecovery",
"com.abc.crypto.provider.KeyRecovery");
put("Alg.Alias.ExemptionMechanism.KR", "KeyRecovery");
return null;
}
});
}
}
Here <java-home> refers to the directory where the JRE
was installed. Thus, if you have the Java 2 SDK v 1.4
installed on Solaris in a directory named /home/user1/J2SDK1.4.0,
or on Microsoft Windows in a directory named C:\J2SDK1.4.0, then
the file would be
Similarly, if you have Java 2 Runtime Environment v 1.4
installed on Solaris in a directory named /home/user1/j2re1.4.0,
or on Windows in a directory named C:\j2re1.4.0, then
the file would be
See Step 5d for an example of adding information
about your provider to 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
security.provider.2=com.sun.net.ssl.internal.ssl.Provider
security.provider.3=com.sun.rsajca.Provider
security.provider.4=com.sun.crypto.provider.SunJCE
security.provider.5=sun.security.jgss.SunProvider
#
# Select the source of seed data for SecureRandom. By default an
# attempt is made to use the entropy gathering device specified by
# the securerandom.source property. If an exception occurs when
# accessing the URL then the traditional system/thread activity
# algorithm is used.
#
securerandom.source=file:/dev/random
#
# The entropy gathering device is described as a URL and can
# also be specified with the property "java.security.egd". For example,
# -Djava.security.egd=file:/dev/urandom
# Specifying this property will override the securerandom.source setting.
#
# Class to instantiate as the javax.security.auth.login.Configuration
# provider.
#
login.configuration.provider=com.sun.security.auth.login.ConfigFile
#
# Default login configuration file
#
#login.config.url.1=file:${user.home}/.java.login.config
#
# Class to instantiate as the system Policy. This is the name of the class
# that will be used as the Policy object.
#
policy.provider=sun.security.provider.PolicyFile
# The default is to have a single system-wide policy file,
# and a policy file in the user's home directory.
policy.url.1=file:${java.home}/lib/security/java.policy
policy.url.2=file:${user.home}/.java.policy
# whether or not we expand properties in the policy file
# if this is set to false, properties (${...}) will not be expanded in policy
# files.
policy.expandProperties=true
# whether or not we allow an extra policy to be passed on the command line
# with -Djava.security.policy=somefile. Comment out this line to disable
# this feature.
policy.allowSystemProperty=true
# whether or not we look into the IdentityScope for trusted Identities
# when encountering a 1.1 signed JAR file. If the identity is found
# and is trusted, we grant it AllPermission.
policy.ignoreIdentityScope=false
#
# Default keystore type.
#
keystore.type=jks
#
# Class to instantiate as the system scope:
#
system.scope=sun.security.provider.IdentityDatabase
#
# List of comma-separated packages that start with or equal this string
# will cause a security exception to be thrown when
# passed to checkPackageAccess unless the
# corresponding RuntimePermission ("accessClassInPackage."+package) has
# been granted.
package.access=sun.
#
# List of comma-separated packages that start with or equal this string
# will cause a security exception to be thrown when
# passed to checkPackageDefinition unless the
# corresponding RuntimePermission ("defineClassInPackage."+package) has
# been granted.
#
# by default, no packages are restricted for definition, and none of
# the class loaders supplied with the JDK call checkPackageDefinition.
#
#package.definition=
#
# Determines whether this properties file can be appended to
# or overridden on the command line via -Djava.security.properties
#
security.overridePropertiesFile=true
#
# Determines the default key and trust manager factory algorithms for
# the javax.net.ssl package.
#
ssl.KeyManagerFactory.algorithm=SunX509
ssl.TrustManagerFactory.algorithm=SunX509
#
# Determines the default SSLSocketFactory and SSLServerSocketFactory
# provider implementations for the javax.net.ssl package. If, due to
# export and/or import regulations, the providers are not allowed to be
# replaced, changing these values will produce non-functional
# SocketFactory or ServerSocketFactory implementations.
#
#ssl.SocketFactory.provider=
#ssl.ServerSocketFactory.provider=
#
# The Java-level namelookup cache policy for successful lookups:
#
# any negative value: caching forever
# any positive value: the number of seconds to cache an address for
# zero: do not cache
#
# default value is forever (FOREVER). For security reasons, this
# caching is made forever when a security manager is set.
#
# NOTE: Setting this value to anything other than the default value
# can have serious security implications. Do not set it unless
# you are sure you are not exposed to DNS spoofing attack.
#
#networkaddress.cache.ttl=-1
# The Java-level namelookup cache policy for failed lookups:
#
# any negative value: cache forever
# any positive value: the number of seconds to cache negative lookup results
# zero: do not cache
#
# In some Microsoft Windows networking environments that employ
# the WINS name service in addition to DNS, name service lookups
# that fail may take a noticeably long time to return (approx. 5 seconds).
# For this reason the default caching policy is to maintain these
# results for 10 seconds.
#
#
networkaddress.cache.negative.ttl=10