1 /*
   2  * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.security.interfaces;
  27 
  28 import java.security.*;
  29 
  30 /**
  31  * An interface to an object capable of generating DSA key pairs.
  32  *
  33  * <p>The {@code initialize} methods may each be called any number
  34  * of times. If no {@code initialize} method is called on a
  35  * DSAKeyPairGenerator, the default is to generate 1024-bit keys, using
  36  * precomputed p, q and g parameters and an instance of SecureRandom as
  37  * the random bit source.
  38  *
  39  * <p>Users wishing to indicate DSA-specific parameters, and to generate a key
  40  * pair suitable for use with the DSA algorithm typically
  41  *
  42  * <ol>
  43  *
  44  * <li>Get a key pair generator for the DSA algorithm by calling the
  45  * KeyPairGenerator {@code getInstance} method with "DSA"
  46  * as its argument.
  47  *
  48  * <li>Initialize the generator by casting the result to a DSAKeyPairGenerator
  49  * and calling one of the
  50  * {@code initialize} methods from this DSAKeyPairGenerator interface.
  51  *
  52  * <li>Generate a key pair by calling the {@code generateKeyPair}
  53  * method from the KeyPairGenerator class.
  54  *
  55  * </ol>
  56  *
  57  * <p>Note: it is not always necessary to do algorithm-specific
  58  * initialization for a DSA key pair generator. That is, it is not always
  59  * necessary to call an {@code initialize} method in this interface.
  60  * Algorithm-independent initialization using the {@code initialize} method
  61  * in the KeyPairGenerator
  62  * interface is all that is needed when you accept defaults for algorithm-specific
  63  * parameters.
  64  *
  65  * <p>Note: Some earlier implementations of this interface may not support
  66  * larger sizes of DSA parameters such as 2048 and 3072-bit.
  67  *
  68  * @since 1.1
  69  * @see java.security.KeyPairGenerator
  70  */
  71 public interface DSAKeyPairGenerator {
  72 
  73     /**
  74      * Initializes the key pair generator using the DSA family parameters
  75      * (p,q and g) and an optional SecureRandom bit source. If a
  76      * SecureRandom bit source is needed but not supplied, i.e. null, a
  77      * default SecureRandom instance will be used.
  78      *
  79      * @param params the parameters to use to generate the keys.
  80      *
  81      * @param random the random bit source to use to generate key bits;
  82      * can be null.
  83      *
  84      * @exception InvalidParameterException if the {@code params}
  85      * value is invalid, null, or unsupported.
  86      */
  87    public void initialize(DSAParams params, SecureRandom random)
  88    throws InvalidParameterException;
  89 
  90     /**
  91      * Initializes the key pair generator for a given modulus length
  92      * (instead of parameters), and an optional SecureRandom bit source.
  93      * If a SecureRandom bit source is needed but not supplied, i.e.
  94      * null, a default SecureRandom instance will be used.
  95      *
  96      * <p>If {@code genParams} is true, this method generates new
  97      * p, q and g parameters. If it is false, the method uses precomputed
  98      * parameters for the modulus length requested. If there are no
  99      * precomputed parameters for that modulus length, an exception will be
 100      * thrown. It is guaranteed that there will always be
 101      * default parameters for modulus lengths of 512 and 1024 bits.
 102      *
 103      * @param modlen the modulus length in bits. Valid values are any
 104      * multiple of 64 between 512 and 1024, inclusive, 2048, and 3072.
 105      *
 106      * @param random the random bit source to use to generate key bits;
 107      * can be null.
 108      *
 109      * @param genParams whether or not to generate new parameters for
 110      * the modulus length requested.
 111      *
 112      * @exception InvalidParameterException if {@code modlen} is
 113      * invalid, or unsupported, or if {@code genParams} is false and there
 114      * are no precomputed parameters for the requested modulus length.
 115      */
 116     public void initialize(int modlen, boolean genParams, SecureRandom random)
 117     throws InvalidParameterException;
 118 }