KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > crypto > spec > PBEKeySpec


1 /*
2  * @(#)PBEKeySpec.java 1.11 04/06/03
3  *
4  * Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7   
8 /*
9  * NOTE:
10  * Because of various external restrictions (i.e. US export
11  * regulations, etc.), the actual source code can not be provided
12  * at this time. This file represents the skeleton of the source
13  * file, so that javadocs of the API can be created.
14  */
15
16 package javax.crypto.spec;
17
18 import java.security.spec.KeySpec;
19
20 /**
21  * A user-chosen password that can be used with password-based encryption
22  * (<i>PBE</i>).
23  *
24  * <p>The password can be viewed as some kind of raw key material, from which
25  * the encryption mechanism that uses it derives a cryptographic key.
26  *
27  * <p>Different PBE mechanisms may consume different bits of each password
28  * character. For example, the PBE mechanism defined in
29  * <a HREF="http://www.ietf.org/rfc/rfc2898.txt">
30  * PKCS #5</a> looks at only the low order 8 bits of each character, whereas
31  * PKCS #12 looks at all 16 bits of each character.
32  *
33  * <p>You convert the password characters to a PBE key by creating an
34  * instance of the appropriate secret-key factory. For example, a secret-key
35  * factory for PKCS #5 will construct a PBE key from only the low order 8 bits
36  * of each password character, whereas a secret-key factory for PKCS #12 will
37  * take all 16 bits of each character.
38  *
39  * <p>Also note that this class stores passwords as char arrays instead of
40  * <code>String</code> objects (which would seem more logical), because the
41  * String class is immutable and there is no way to overwrite its
42  * internal value when the password stored in it is no longer needed. Hence,
43  * this class requests the password as a char array, so it can be overwritten
44  * when done.
45  *
46  * @author Jan Luehe
47  * @author Valerie Peng
48  *
49  * @version 1.17, 06/03/04
50  *
51  * @see javax.crypto.SecretKeyFactory
52  * @see PBEParameterSpec
53  * @since 1.4
54  */
55 public class PBEKeySpec implements KeySpec
56 {
57
58     /**
59      * Constructor that takes a password. An empty char[] is used if
60      * null is specified.
61      *
62      * <p> Note: <code>password</code> is cloned before it is stored in
63      * the new <code>PBEKeySpec</code> object.
64      *
65      * @param password the password.
66      */
67     public PBEKeySpec(char[] password) { }
68
69     /**
70      * Constructor that takes a password, salt, iteration count, and
71      * to-be-derived key length for generating PBEKey of variable-key-size
72      * PBE ciphers. An empty char[] is used if null is specified for
73      * <code>password</code>.
74      *
75      * <p> Note: the <code>password</code> and <code>salt</code>
76      * are cloned before they are stored in
77      * the new <code>PBEKeySpec</code> object.
78      *
79      * @param password the password.
80      * @param salt the salt.
81      * @param iterationCount the iteration count.
82      * @param keyLength the to-be-derived key length.
83      * @exception NullPointerException if <code>salt</code> is null.
84      * @exception IllegalArgumentException if <code>salt</code> is empty,
85      * i.e. 0-length, <code>iterationCount</code> or
86      * <code>keyLength</code> is not positive.
87      */
88     public PBEKeySpec(char[] password, byte[] salt, int iterationCount, int
89         keyLength)
90     { }
91
92     /**
93      * Constructor that takes a password, salt, iteration count for
94      * generating PBEKey of fixed-key-size PBE ciphers. An empty
95      * char[] is used if null is specified for <code>password</code>.
96      *
97      * <p> Note: the <code>password</code> and <code>salt</code>
98      * are cloned before they are stored in the new
99      * <code>PBEKeySpec</code> object.
100      *
101      * @param password the password.
102      * @param salt the salt.
103      * @param iterationCount the iteration count.
104      * @exception NullPointerException if <code>salt</code> is null.
105      * @exception IllegalArgumentException if <code>salt</code> is empty,
106      * i.e. 0-length, or <code>iterationCount</code> is not positive.
107      */
108     public PBEKeySpec(char[] password, byte[] salt, int iterationCount) { }
109
110     /**
111      * Clears the internal copy of the password.
112      *
113      */
114     public final void clearPassword() { }
115
116     /**
117      * Returns a copy of the password.
118      *
119      * <p> Note: this method returns a copy of the password. It is
120      * the caller's responsibility to zero out the password information after
121      * it is no longer needed.
122      *
123      * @exception IllegalStateException if password has been cleared by
124      * calling <code>clearPassword</code> method.
125      * @return the password.
126      */
127     public final char[] getPassword() {
128         return null;
129     }
130
131     /**
132      * Returns a copy of the salt or null if not specified.
133      *
134      * <p> Note: this method should return a copy of the salt. It is
135      * the caller's responsibility to zero out the salt information after
136      * it is no longer needed.
137      *
138      * @return the salt.
139      */
140     public final byte[] getSalt() {
141         return null;
142     }
143
144     /**
145      * Returns the iteration count or 0 if not specified.
146      *
147      * @return the iteration count.
148      */
149     public final int getIterationCount() {
150         return 0;
151     }
152
153     /**
154      * Returns the to-be-derived key length or 0 if not specified.
155      *
156      * <p> Note: this is used to indicate the preference on key length
157      * for variable-key-size ciphers. The actual key size depends on
158      * each provider's implementation.
159      *
160      * @return the to-be-derived key length.
161      */
162     public final int getKeyLength() {
163         return 0;
164     }
165 }
166
Popular Tags