001 /* PBEKeySpec.java -- Wrapper for password-based keys.
002 Copyright (C) 2004, 2006 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038
039 package javax.crypto.spec;
040
041 import java.security.spec.KeySpec;
042
043 /**
044 * A wrapper for a password-based key, used for password-based
045 * encryption (PBE).
046 *
047 * <p>Examples of password-based encryption algorithms include:
048 *
049 * <ul>
050 * <li><a href="http://www.rsasecurity.com/rsalabs/pkcs/pkcs-5/">PKCS #5
051 * - Password-Based Cryptography Standard</a></li>
052 * <li><a href="http://www.rsasecurity.com/rsalabs/pkcs/pkcs-12/">PKCS
053 * #12 - Personal Information Exchange Syntax Standard</a></li>
054 * </ul>
055 *
056 * @author Casey Marshall (csm@gnu.org)
057 * @since 1.4
058 * @see javax.crypto.SecretKeyFactory
059 * @see PBEParameterSpec
060 */
061 public class PBEKeySpec implements KeySpec
062 {
063
064 // Fields.
065 // ------------------------------------------------------------------------
066
067 /** The iteration count. */
068 private int iterationCount;
069
070 /** The generated key length. */
071 private int keyLength;
072
073 /** The password. */
074 private char[] password;
075
076 /** The salt. */
077 private byte[] salt;
078
079 /** The password state */
080 private boolean passwordValid = true;
081
082 // Constructors.
083 // ------------------------------------------------------------------------
084
085 /**
086 * Create a new PBE key spec with just a password.
087 * <p>
088 * A copy of the password argument is stored instead of the argument itself.
089 *
090 * @param password The password char array.
091 */
092 public PBEKeySpec(char[] password)
093 {
094 setPassword(password);
095
096 // load the default values for unspecified variables.
097 salt = null;
098 iterationCount = 0;
099 keyLength = 0;
100 }
101
102 /**
103 * Create a PBE key spec with a password, salt, and iteration count.
104 * <p>
105 * A copy of the password and salt arguments are stored instead of the
106 * arguments themselves.
107 *
108 * @param password The password char array.
109 * @param salt The salt bytes.
110 * @param iterationCount The iteration count.
111 * @throws NullPointerException If salt is null
112 * @throws IllegalArgumentException If salt is an empty array, or
113 * iterationCount is negative
114 */
115 public PBEKeySpec(char[] password, byte[] salt, int iterationCount)
116 {
117 setPassword(password);
118 setSalt(salt);
119 setIterationCount(iterationCount);
120
121 // load default values into unspecified variables.
122 keyLength = 0;
123 }
124
125 /**
126 * Create a PBE key spec with a password, salt, iteration count, and key
127 * length.
128 * <p>
129 * A copy of the password and salt arguments are stored instead of the
130 * arguments themselves.
131 *
132 * @param password The password char array.
133 * @param salt The salt bytes.
134 * @param iterationCount The iteration count.
135 * @param keyLength The generated key length.
136 * @throws NullPointerException If salt is null
137 * @throws IllegalArgumentException If salt is an empty array, if
138 * iterationCount or keyLength is negative
139 */
140 public PBEKeySpec(char[] password, byte[] salt, int iterationCount,
141 int keyLength)
142 {
143 setPassword(password);
144 setSalt(salt);
145 setIterationCount(iterationCount);
146 setKeyLength(keyLength);
147 }
148
149 // Instance methods.
150 // ------------------------------------------------------------------------
151
152 /**
153 * Clear the password array by filling it with null characters.
154 * <p>
155 * This clears the stored copy of the password, not the original char array
156 * used to create the password.
157 */
158 public final void clearPassword()
159 {
160 if (password == null)
161 return;
162 for (int i = 0; i < password.length; i++)
163 password[i] = '\u0000';
164
165 // since the password is cleared, it is no longer valid
166 passwordValid = false;
167 }
168
169 /**
170 * Get the iteration count, or 0 if it has not been specified.
171 *
172 * @return The iteration count, or 0 if it has not been specified.
173 */
174 public final int getIterationCount()
175 {
176 return iterationCount;
177 }
178
179 /**
180 * Get the generated key length, or 0 if it has not been specified.
181 *
182 * @return The key length, or 0 if it has not been specified.
183 */
184 public final int getKeyLength()
185 {
186 return keyLength;
187 }
188
189 /**
190 * Get the password character array copy.
191 * <p>
192 * This returns a copy of the password, not the password itself.
193 *
194 * @return a clone of the password.
195 * @throws IllegalStateException If {@link #clearPassword()} has already been
196 * called.
197 */
198 public final char[] getPassword()
199 {
200 if (! passwordValid)
201 throw new IllegalStateException("clearPassword() has been called, the "
202 + "password is no longer valid");
203 return (char[]) password.clone();
204 }
205
206 /**
207 * Get the salt bytes array copy.
208 * <p>
209 * This returns a copy of the salt, not the salt itself.
210 *
211 * @return The salt.
212 */
213 public final byte[] getSalt()
214 {
215 if (salt != null)
216 return (byte[]) salt.clone();
217 return null;
218 }
219
220 /**
221 * Set the password char array.
222 * <p>
223 * A copy of the password argument is stored instead of the argument itself.
224 *
225 * @param password The password to be set
226 */
227 private void setPassword(char[] password)
228 {
229 if (password != null)
230 this.password = (char[]) password.clone();
231 else
232 this.password = new char[0];
233
234 passwordValid = true;
235 }
236
237 /**
238 * Set the salt byte array.
239 * <p>
240 * A copy of the salt arguments is stored instead of the argument itself.
241 *
242 * @param salt The salt to be set.
243 * @throws NullPointerException If the salt is null.
244 * @throws IllegalArgumentException If the salt is an empty array.
245 */
246 private void setSalt(byte[] salt)
247 {
248 if (salt.length == 0)
249 throw new IllegalArgumentException("salt MUST NOT be an empty byte array");
250
251 this.salt = (byte[]) salt.clone();
252 }
253
254 /**
255 * Set the iterationCount.
256 *
257 * @param iterationCount The iteration count to be set.
258 * @throws IllegalArgumentException If the iterationCount is negative.
259 */
260 private void setIterationCount(int iterationCount)
261 {
262 if (iterationCount < 0)
263 throw new IllegalArgumentException("iterationCount MUST be positive");
264
265 this.iterationCount = iterationCount;
266 }
267
268 /**
269 * Set the keyLength.
270 *
271 * @param keyLength The keyLength to be set.
272 * @throws IllegalArgumentException if the keyLength is negative.
273 */
274 private void setKeyLength(int keyLength)
275 {
276 if (keyLength < 0)
277 throw new IllegalArgumentException("keyLength MUST be positive");
278
279 this.keyLength = keyLength;
280 }
281 }