Keypairs
========

The following class diagram shows the most important classes in the library that collaborate to implement the keypair generation functionality:

Figure 10: Keypair generation class diagram

The next figure is a sequence diagram showing the entities and messages involved in using those classes:

Figure 11: Keypair generation sequence diagram

Algorithm-Specific Attributes
=============================

Diffie-Hellman
--------------

Each of these constants are defined in the gnu.crypto.key.dh.GnuDHKeyPairGenerator class.

 -- Variable: java.lang.String SOURCE_OF_RANDOMNESS
     Property name for the source of random bits to use when generating keys. The value mapped by this property must be of type gnu.crypto.prng.IRandom which must have been previously initialized. If undefined, then a default PRNG is used.

 -- Variable: java.lang.String DH_PARAMETERS
     Property name for an optional javax.crypto.spec.DHGenParameterSpec instance to use for this generator.

 -- Variable: java.lang.String PRIME_SIZE
     Property name of the size in bits (an instance of java.lang.Integer) of the public prime P.

 -- Variable: java.lang.String EXPONENT_SIZE
     Property name of the size in bits (an instance of java.lang.Integer) of the private exponent X.

DSS
---

Each of these constants are defined in the gnu.crypto.key.dss.DSSKeyPairGenerator class.

 -- Variable: java.lang.String SOURCE_OF_RANDOMNESS
     Property name for the source of random bits to use when generating keys. The value mapped by this property must be of type gnu.crypto.prng.IRandom which must have been previously initialized. If undefined, then a default PRNG is used.

 -- Variable: java.lang.String DSS_PARAMETERS
     Property name of an optional java.security.spec.DSAParameterSpec instance to use for this generator's P, Q, and G values. The default is to generate these values or use pre-computed ones, depending on the value of the USE_DEFAULTS attribute.

 -- Variable: java.lang.String MODULUS_LENGTH
     Property name for the modulus length, in bits. The value mapped by this property must be of type java.lang.Integer.

 -- Variable: java.lang.String USE_DEFAULTS
     Property name of an instance of java.lang.Boolean indicating wether or not to use pre-computed default values for the algorithm parameters. Three sets of such parameters are also provided covering 512-bit (KEY_PARAMS_512, 768-bit (KEY_PARAMS_768) and 1024-bit (KEY_PARAMS_512) keylength.

RSA
---

Each of these constants are defined in the gnu.crypto.key.rsa.RSAPSSKeyPairGenerator class.

 -- Variable: java.lang.String SOURCE_OF_RANDOMNESS
     Property name for the source of random bits to use. The value mapped by this property must be of type gnu.crypto.prng.IRandom, which must have been previously initialized. If undefined, then a default PRNG is used.

 -- Variable: java.lang.String MODULUS_LENGTH
     Property name for the length, in bits, of the modulus. The value mapped by this property must be of type java.lang.Integer.

 -- Variable: java.lang.String RSA_PARAMETERS
     Property name for the optional values of E and N. The value mapped by this property must be of type java.security.spec.RSAKeyGenParameterSpec Random or default values will be used instead if this parameter is not specified.

SRP6
----

Each of these constants are defined in the gnu.crypto.key.srp6.SRPKeyPairGenerator class.

 -- Variable: java.lang.String SOURCE_OF_RANDOMNESS
     Property name for the source of random bits to use. The value mapped by this property must be of type gnu.crypto.prng.IRandom, which must have been previously initialized. If undefined, then a default PRNG is used.

 -- Variable: java.lang.String MODULUS_LENGTH
     Property name of the length (an instance of java.lang.Integer) of the modulus N of an SRP key.

 -- Variable: java.lang.String SHARED_MODULUS
     Property name of the value of the modulus N of an SRP key. The value mapped by this property, if/when defined, must be of type java.math.BigInteger. It is an optional parameter. If undefined, then a new value is generated, unless USE_DEFAULTS is set to TRUE.

 -- Variable: java.lang.String GENERATOR
     Property name of the value of the generator G of an SRP key. The value mapped by this property, if/when defined, must be of type java.math.BigInteger. It is an optional parameter. If undefined, then a new value is generated, unless USE_DEFAULTS is set to TRUE.

 -- Variable: java.lang.String USE_DEFAULTS
     Property name of an instance of java.lang.Boolean indicating wether or not to use pre-computed default values for the algorithm parameters. Seven sets of such parameters are also provided covering 512-bit (N_512, 640-bit (N_640), 768-bit (N_768), 1024-bit (N_1024), 1280-bit (N_1280), 1536-bit (N_1536) and 2048-bit (N_2048) shared modulus length.

The IKeyPairGenerator Interface
===============================

All signature algorithms in GNU Crypto have their corresponding key pair generators, which implement this interface and provide the following methods:

 -- Function: void setup (java.util.Map ATTRIBUTES) throws java.lang.IllegalArgumentException
     Initializes this key pair generator with the given attrubutes. The property names used are algorithm-dependent, and are described in the next section. This method throws a java.lang.IllegalArgumentException if the given attributes are incorrect or incomplete.

 -- Function: java.security.KeyPair generate ()
     Generates and returns a new key pair based on the attributes used to configure this instance.

 -- Function: java.lang.String name ()
     Returns the canonical name of the algorithm this class generates key pairs for.

The KeyPairGeneratorFactory Class
=================================

 -- Function: IKeyPairGenerator getInstance (java.lang.String ALGORITHM)
     Returns an instance of a key pair generator for ALGORITHM, or null if no such generator is available.

 -- Function: java.util.Set getNames ()
     Returns an unmodifiable set of all available key pair generator algorithms, each entry a java.lang.String.

The IKeyPairCodec Interface
===========================

A key pair codec is used to externalize and de-externalize the key pairs used in GNU Crypto. There is no factory class, but rather the implementations have public, zero-argument constructors. The available codecs are:

  * gnu.crypto.key.dh.DHKeyPairRawCodec, for encoding and decoding Diffie-Hellman key pairs.

  * gnu.crypto.key.dss.DSSKeyPairRawCodec, for encoding and decoding DSS key pairs.

  * gnu.crypto.key.rsa.RSAKeyPairRawCodec, for encoding and decoding RSA key pairs.

  * gnu.crypto.key.srp6.SRPKeyPairRawCodec, for encoding and decoding SRP key pairs.

 -- Variable: int RAW_FORMAT
     Constant identifying the ``raw'' format used by GNU Crypto.

 -- Function: java.security.PrivateKey decodePrivateKey (byte[] ENCODED)
     Decodes a private key from its external representation, returning it as an appropriate instance of java.security.PrivateKey. This function will throw a java.lang.IllegalArgumentException if the encoded bytes cannot be decoded or are incorrect.

 -- Function: java.security.PublicKey decodePublicKey (byte[] ENCODED)
     Decodes a public key from its external representation, returning it as an appropriate instance of java.security.PublicKey. This function will throw a java.lang.IllegalArgumentException if the encoded bytes cannot be decoded or are incorrect.

 -- Function: byte[] encodePrivateKey (java.security.PrivateKey KEY)
     Encodes a private key to its external representation, returning the encoded bytes. This function will throw a java.lang.IllegalArgumentException if the key cannot be encoded by this instance.

 -- Function: byte[] encodePublicKey (java.security.PublicKey KEY)
     Encodes a public key to its external representation, returning the encoded bytes. This function will throw a java.lang.IllegalArgumentException if the key cannot be encoded by this instance.

 -- Function: int getFormatID ()
     Returns the format identifier of this codec, such as RAW_FORMAT.

Example
=======

The following example demonstrates how to generate a DSS keypair.

     IKeyPairGenerator kpg = KeyPairGeneratorFactory.getInstance(Registry.DSS_KPG);
     HashMap map = new HashMap();
     map.put(DSSKeyPairGenerator.MODULUS_LENGTH, new Integer(512));
     map.put(DSSKeyPairGenerator.USE_DEFAULTS, new Boolean(false));
     kpg.setup(map);
     KeyPair kp = kpg.generate();

     BigInteger p1 = ((DSAPublicKey) kp.getPublic()).getParams().getP();
     BigInteger p2 = ((DSAPrivateKey) kp.getPrivate()).getParams().getP();

     BigInteger q1 = ((DSAPublicKey) kp.getPublic()).getParams().getQ();
     BigInteger q2 = ((DSAPrivateKey) kp.getPrivate()).getParams().getQ();

     BigInteger g1 = ((DSAPublicKey) kp.getPublic()).getParams().getG();
     BigInteger g2 = ((DSAPrivateKey) kp.getPrivate()).getParams().getG();