1   /* $RCSfile: DESede3KeySecretKeyGeneratorEngine.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   * DESede3KeySecretKeyGeneratorEngine Class provides the functionality
44   * of a DESede key generator for two keys (means 168 or 192 bit key length).
45   * This key generator generates only keys for the "DESede3Key" 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 DESede3KeySecretKeyGeneratorEngine throuh the JCE in the following 
54   * way:
55   *
56   * import javax.crypto.KeyGenerator;
57   * import javax.crypto.SecretKey;
58   * import java.security.SecureRandom;
59   *
60   * KeyGenerator kg = new KeyGenerator.getInstance("DESede3Key", "JHBCI");
61   * kg.init(new SecureRandom());
62   * SecretKey key = kg.generateKey();
63   *
64   * //Use key further in a DESede3Key Cipher from the JHBCI provider.
65   * //Or do some other useful things with this nicely generated SecretKey.
66   *
67   * </pre>
68   *
69   *
70   * In this case you does not explicitly initialize the KeyGenerator Object
71   * (in our example code that means <code>kg.init(new SecureRandom());</code>)
72   * we initialize the KeyGenerator Object with <code>new SecureRandom()</code>.
73   * So you can omit the line <code>kg.init(new SecureRandom());</code>.
74   * With this code we will get a SecureRandom implementation of the
75   * higest-priority installed provider. If no one of the installed
76   * providers supply an implementation of SecureRandom, a system provided
77   * source of randomness will be used.
78   * <pre>
79   *
80   * See the changed example:
81   *
82   * import javax.crypto.KeyGenerator;
83   * import javax.crypto.SecretKey;
84   * import java.security.SecureRandom;
85   *
86   * KeyGenerator kg = new KeyGenerator.getInstance("DESede3Key", "JHBCI");
87   * SecretKey key = kg.generateKey();
88   *
89   * //Use key further in a DESede3Key Cipher from the JHBCI provider.
90   * //Or do some other useful things with this nicely generated SecretKey.
91   *
92   * </pre>
93   * @author  <a href=mailto:uwe@cscc.de>Uwe G&uuml;nther</a>
94   * @version $Revision: 1.10 $
95   */
96  public final class DESede3KeySecretKeyGeneratorEngine extends KeyGeneratorSpi {
97  
98      /** The delegate for this wrapper object */
99      private DESede3KeySecretKeyGeneratorImpl generator = 
100     new DESede3KeySecretKeyGeneratorImpl();
101     
102     /** 
103      * Creates new DESede3KeySecretKeyGeneratorEngine.
104      * Mostly used of the static function
105      * <code>KeyGenerator.getInstance(...)</code>.
106      *
107      * @throws SecurityException if the provider self integrity check fails. 
108      */
109     public DESede3KeySecretKeyGeneratorEngine() {
110         if (JHBCI.selfIntegrityChecking() == false) {
111             throw new SecurityException("JHBCI-Provider is tampered.");
112         }      
113     }
114 
115     /** 
116      * Returns a string representation of the object.
117      *
118      * @return a string representation of the object.
119      */
120     public String toString() {
121         return this.generator.toString();
122     }
123     
124     /** 
125      * Initializes the key generator.
126      *
127      * @param random the source of randomness for this generator.
128      */
129     protected void engineInit(SecureRandom random) {
130         this.generator.init(random);
131     }
132     
133     /** 
134      * Initializes this key generator for a certain keysize, using the given
135      * source of randomness. We support only 168 bit and 192 bit keysize,
136      * which means the refers to the same result.
137      *
138      * @param keysize the keysize. This is an algorithm-specific metric,
139      * specified in number of bits.
140      * @param random the source of randomness for this key generator.
141      * @throws InvalidParameterException if keysize is wrong or not supported.
142      */
143     protected void engineInit(int keysize, SecureRandom random) 
144             throws InvalidParameterException {
145         this.generator.init(keysize, random);
146     }
147     
148     /** 
149      * Initializes the key generator with the specified parameter
150      * set and a user-provided source of randomness. The JHBCI
151      * key generator implementation don't use any AlgorithmParameterSpec's.
152      * This means if you want to init the KeyGenerator Object with this
153      * method <CODE>params</CODE> have to be null or
154      * InvalidAlgorithmParameterException will be thrown.
155      *
156      * @param params the key generation parameters.
157      * @param random the source of randomness for this key generator.
158      * @throws InvalidAlgorithmParameterException if <code>params</code> is
159      * inappropriate for this key generator. We only support <code>null</code>
160      * as parameter for <CODE>params</CODE>.
161      */
162     protected void engineInit(AlgorithmParameterSpec params, SecureRandom random) 
163             throws InvalidAlgorithmParameterException {
164         this.generator.init(params, random);
165     }
166     
167     /** 
168      * Generates a secret key. This method can re-used more than once
169      * for the KeyGenerator Object to generate a lot of SecretKey's.
170      *
171      * @return the new key.
172      */
173     protected SecretKey engineGenerateKey() {
174         return this.generator.generateKey();
175     }
176 }
177