Key Specification Interfaces and Classes

Key specifications are transparent representations of the key material that constitutes a key. If the key is stored on a hardware device, its specification might contain information that helps identify the key on the device.

A transparent representation of keys means that you can access each key material value individually, through one of the get methods defined in the corresponding specification class. For example, DSAPrivateKeySpec defines getX, getP, getQ, and getG methods, to access the private key x, and the DSA algorithm parameters used to calculate the key: the prime p, the sub-prime q, and the base g.

This representation is contrasted with an opaque representation, as defined by the Key interface, in which you have no direct access to the key material fields. In other words, an opaque representation gives you limited access to the key - just the three methods defined by the Key interface: getAlgorithm, getFormat, and getEncoded.

A key can be specified in an algorithm-specific way or in an algorithm-independent encoding format (such as ASN.1). For example, a DSA private key can be specified by its components x, p, q, and g (see DSAPrivateKeySpec), or it may be specified using its DER encoding (see PKCS8EncodedKeySpec).

The key specification interfaces and classes in the java.security.spec package are:

The KeySpec Interface

This interface contains no methods or constants. Its only purpose is to group and provide type safety for all key specifications. All key specifications must implement this interface.

The DSAPrivateKeySpec Class

This class (which implements the KeySpec interface) specifies a DSA private key with its associated parameters. DSAPrivateKeySpec has the following methods:

BigInteger getX()
BigInteger getP()
BigInteger getQ()
BigInteger getG()

These methods return the private key x, and the DSA algorithm parameters used to calculate the key: the prime p, the sub-prime q, and the base g.

The DSAPublicKeySpec Class

This class (which implements the KeySpec interface) specifies a DSA public key with its associated parameters. DSAPublicKeySpec has the following methods:

BigInteger getY()
BigInteger getP()
BigInteger getQ()
BigInteger getG()

These methods return the public key y, and the DSA algorithm parameters used to calculate the key: the prime p, the sub-prime q, and the base g.

The RSAPrivateKeySpec Class

This class (which implements the KeySpec interface) specifies an RSA private key. RSAPrivateKeySpec has the following methods:

BigInteger getModulus()
BigInteger getPrivateExponent()

These methods return the RSA modulus n and private exponent d values that constitute the RSA private key.

The RSAPrivateCrtKeySpec Class

This class (which extends the RSAPrivateKeySpec class) specifies an RSA private key, as defined in the PKCS #1 standard, using the Chinese Remainder Theorem (CRT) information values. RSAPrivateCrtKeySpec has the following methods (in addition to the methods inherited from its superclass RSAPrivateKeySpec):

BigInteger getPublicExponent()
BigInteger getPrimeP()
BigInteger getPrimeQ()
BigInteger getPrimeExponentP()
BigInteger getPrimeExponentQ()
BigInteger getCrtCoefficient()

These methods return the public exponent e and the CRT information integers: the prime factor p of the modulus n, the prime factor q of n, the exponent d mod (p-1), the exponent d mod (q-1), and the Chinese Remainder Theorem coefficient (inverse of q) mod p.

An RSA private key logically consists of only the modulus and the private exponent. The presence of the CRT values is intended for efficiency.

The RSAMultiPrimePrivateCrtKeySpec Class

This class (which extends the RSAPrivateKeySpec class) specifies an RSA multi-prime private key, as defined in the PKCS #1 v2.1, using the Chinese Remainder Theorem (CRT) information values. RSAMultiPrimePrivateCrtKeySpec has the following methods (in addition to the methods inherited from its superclass RSAPrivateKeySpec):

BigInteger getPublicExponent()
BigInteger getPrimeP()
BigInteger getPrimeQ()
BigInteger getPrimeExponentP()
BigInteger getPrimeExponentQ()
BigInteger getCrtCoefficient()
RSAOtherPrimeInfo[] getOtherPrimeInfo()

These methods return the public exponent e and the CRT information integers: the prime factor p of the modulus n, the prime factor q of n, the exponent d mod (p-1), the exponent d mod (q-1), and the Chinese Remainder Theorem coefficient (inverse of q) mod p.

Method getOtherPrimeInfo returns a copy of the otherPrimeInfo (defined in PKCS #1) or null if there are only two prime factors (p and q).

An RSA private key logically consists of only the modulus and the private exponent. The presence of the CRT values is intended for efficiency.

The RSAPublicKeySpec Class

This class (which implements the KeySpec interface) specifies an RSA public key. RSAPublicKeySpec has the following methods:

BigInteger getModulus()
BigInteger getPublicExponent()

These methods return the RSA modulus n and public exponent e values that constitute the RSA public key.

The EncodedKeySpec Class

This abstract class (which implements the KeySpec interface) represents a public or private key in encoded format. Its getEncoded method returns the encoded key:

abstract byte[] getEncoded();

and its getFormat method returns the name of the encoding format:

abstract String getFormat();

See the next sections for the concrete implementations PKCS8EncodedKeySpec, X509EncodedKeySpec, and RFC5915ECPrivateKeyEncodedKeySpec.

The PKCS8EncodedKeySpec Class

This class, which is a subclass of EncodedKeySpec, represents the DER encoding of a private key, according to the format specified in the PKCS #8 standard. Its getEncoded method returns the key bytes, encoded according to the PKCS #8 standard. Its getFormat method returns the string PKCS#8.

The X509EncodedKeySpec Class

This class, which is a subclass of EncodedKeySpec, represents the DER encoding of a public key, according to the format specified in the X.509 standard. Its getEncoded method returns the key bytes, encoded according to the X.509 standard. Its getFormat method returns the string X.509.

The ibm.security.internal.spec.RFC5915ECPrivateKeyEncodedKeySpec Class

This class, which is a subclass of EncodedKeySpec, represents the DER encoding of an EC private key, according to the format specified in the RFC5915 document. Its getEncoded method returns the key bytes, encoded according to the RFC5915 document. Its getFormat method returns the string RFC5915.