1   /* $RCSfile: DES1KeySecretKeyGeneratorEngine.java,v $
2    * $Revision: 1.10 $
3    * $Date: 2003/10/04 19:18:38 $
4    * $Author: uwe_guenther $
5    * $State: Exp $
6    *
7    * Created on August 13, 2001 2:51 PM
8    *
9    * Copyright (C) 2001 Uwe Guenther <uwe@cscc.de>
10   *
11   * This file is part of the jhbci JCE-ServiceProvider. The jhbci JCE-
12   * ServiceProvider is a library, written in JavaTM, that should be 
13   * used in HBCI banking applications (clients and may be servers),
14   * to do cryptographic operations.
15   *
16   * The jhbci library is free software; you can redistribute it and/or
17   * modify it under the terms of the GNU Lesser General Public
18   * License as published by the Free Software Foundation; either
19   * version 2.1 of the License, or (at your option) any later version.
20   *
21   * The jhbci library is distributed in the hope that it will be useful,
22   * but WITHOUT ANY WARRANTY; without even the implied warranty of
23   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
24   * Lesser General Public License for more details.
25   *
26   * You should have received a copy of the GNU Lesser General Public
27   * License along with this library; if not, write to the Free Software
28   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
29   *
30   */
31  
32  package de.cscc.crypto.provider;
33  
34  import java.security.InvalidAlgorithmParameterException;
35  import java.security.InvalidParameterException;
36  import java.security.SecureRandom;
37  import java.security.spec.AlgorithmParameterSpec;
38  
39  import javax.crypto.KeyGeneratorSpi;
40  import javax.crypto.SecretKey;
41  
42  /**
43   * DES1KeySecretKeyGeneratorEngine Class provides the functionality
44   * of a DESede key generator for two keys (means 56 or 64 bit key length).
45   * This key generator generates only keys for the "DES1Key" algorithm in
46   * the JHBCI crypto provider.
47   *
48   * This KeyGenerator Object is re-useable, i.e., after a key has been generated,
49   * the same KeyGenerator Object  can be re-used to generate further keys.
50   *
51   * <pre>
52   *
53   * Use the DES1KeySecretKeyGeneratorEngine through the JCE in the following way:
54   *
55   * import javax.crypto.KeyGenerator;
56   * import javax.crypto.SecretKey;
57   * import java.security.SecureRandom;
58   *
59   * KeyGenerator kg = new KeyGenerator.getInstance("DES1Key", "JHBCI");
60   * kg.init(new SecureRandom());
61   * SecretKey key = kg.generateKey();
62   *
63   * //Use key further in a DES1Key Cipher from the JHBCI provider.
64   * //Or do some other useful things with this nicely generated SecretKey.
65   *
66   * </pre>
67   *
68   *
69   * In this case you does not explicitly initialize the KeyGenerator Object
70   * (in our example code that means <code>kg.init(new SecureRandom());</code>)
71   * we initialize the KeyGenerator Object with <code>new SecureRandom()</code>.
72   * So you can omit the line <code>kg.init(new SecureRandom());</code>.
73   * With this code we will get a SecureRandom implementation of the
74   * highest-priority installed provider. If no one of the installed
75   * providers supply an implementation of SecureRandom, a system provided
76   * source of randomness will be used.
77   * <pre>
78   *
79   * See the changed example:
80   *
81   * import javax.crypto.KeyGenerator;
82   * import javax.crypto.SecretKey;
83   * import java.security.SecureRandom;
84   *
85   * KeyGenerator kg = new KeyGenerator.getInstance("DES1Key", "JHBCI");
86   * SecretKey key = kg.generateKey();
87   *
88   * //Use key further in a DES1Key Cipher from the JHBCI provider.
89   * //Or do some other useful things with this nicely generated SecretKey.
90   *
91   * </pre>
92   * @author  <a href=mailto:uwe@cscc.de>Uwe G&uuml;nther</a>
93   * @version $Revision: 1.10 $
94   */
95  public final class DES1KeySecretKeyGeneratorEngine extends KeyGeneratorSpi {
96  
97      /** The delegate for this wrapper object */
98      private DES1KeySecretKeyGeneratorImpl generator = 
99      new DES1KeySecretKeyGeneratorImpl();
100     
101     /** 
102      * Creates new DES1KeySecretKeyGeneratorEngine.
103      * Mostly used of the static function
104      * <code>KeyGenerator.getInstance(...)</code>.
105      *
106      * @throws SecurityException if the provider self integrity check fails.
107      */
108     public DES1KeySecretKeyGeneratorEngine() {
109         if (JHBCI.selfIntegrityChecking() == false) {
110             throw new SecurityException("JHBCI-Provider is tampered.");
111         }         
112     }
113     
114     /** 
115      * Returns a string representation of the object.
116      *
117      * @return a string representation of the object.
118      */
119     public String toString() {
120         return this.generator.toString();
121     }
122     
123     /** 
124      * Initializes the key generator.
125      *
126      * @param random the source of randomness for this generator
127      */
128     protected void engineInit(SecureRandom random) {
129         this.generator.init(random);
130     }
131     
132     /** 
133      * Initializes this key generator for a certain keysize, using the given
134      * source of randomness. We support only 56 bit and 64 bit keysize,
135      * which means the refers to the same result. 
136      *
137      * @param keysize the keysize. This is an algorithm-specific metric,
138      * specified in number of bits.
139      * @param random the source of randomness for this key generator.
140      * @throws InvalidParameterException if keysize is wrong or not supported.
141      */
142     protected void engineInit(int keysize, SecureRandom random) 
143             throws InvalidParameterException {
144         this.generator.init(keysize, random);
145     }
146     
147     /** 
148      * Initializes the key generator with the specified parameter
149      * set and a user-provided source of randomness. The JHBCI
150      * key generator implementation don't use any AlgorithmParameterSpec's.
151      * This means if you want to init the KeyGenerator Object with this
152      * method <code>params</code> have to be null or
153      * InvalidAlgorithmParameterException will be thrown.
154      *
155      * @param params the key generation parameters
156      * @param random the source of randomness for this key generator.
157      * @exception InvalidAlgorithmParameterException if <code>params</code> is
158      *             inappropriate for this key generator. We only support 
159      *             <CODE>null</CODE> as parameter for <CODE>params</CODE>.
160      */
161     protected void engineInit(AlgorithmParameterSpec params, SecureRandom random)
162             throws InvalidAlgorithmParameterException {
163         this.generator.init(params, random);
164     }
165     
166     /** 
167      * Generates a secret key. This method can re-used more than once
168      * for the KeyGenerator Object to generate a lot of SecretKey's.
169      *
170      * @return the new key.
171      */
172     protected SecretKey engineGenerateKey() {
173         return this.generator.generateKey();
174     }
175     
176 }
177