KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > crypto > Cipher


1 /*
2  * @(#)Cipher.java 1.13 04/03/31
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;
17
18 import java.util.*;
19 import java.util.regex.*;
20 import java.security.*;
21 import javax.crypto.spec.*;
22 import sun.security.jca.*;
23
24 import java.security.Provider.Service;
25 import java.security.spec.AlgorithmParameterSpec;
26 import java.security.spec.InvalidParameterSpecException;
27 import java.security.cert.Certificate;
28 import java.security.cert.X509Certificate;
29 import java.nio.ByteBuffer;
30 import java.nio.ReadOnlyBufferException;
31 import sun.security.util.Debug;
32 import sun.security.jca.GetInstance.Instance;
33
34 /**
35  * This class provides the functionality of a cryptographic cipher for
36  * encryption and decryption. It forms the core of the Java Cryptographic
37  * Extension (JCE) framework.
38  *
39  * <p>In order to create a Cipher object, the application calls the
40  * Cipher's <code>getInstance</code> method, and passes the name of the
41  * requested <i>transformation</i> to it. Optionally, the name of a provider
42  * may be specified.
43  *
44  * <p>A <i>transformation</i> is a string that describes the operation (or
45  * set of operations) to be performed on the given input, to produce some
46  * output. A transformation always includes the name of a cryptographic
47  * algorithm (e.g., <i>DES</i>), and may be followed by a feedback mode and
48  * padding scheme.
49  *
50  * <p> A transformation is of the form:<p>
51  *
52  * <ul>
53  * <li>"<i>algorithm/mode/padding</i>" or
54  * <p>
55  * <li>"<i>algorithm</i>"
56  * </ul>
57  *
58  * <P> (in the latter case,
59  * provider-specific default values for the mode and padding scheme are used).
60  * For example, the following is a valid transformation:<p>
61  *
62  * <pre>
63  * Cipher c = Cipher.getInstance("<i>DES/CBC/PKCS5Padding</i>");
64  * </pre>
65  *
66  * <p>When requesting a block cipher in stream cipher mode (e.g.,
67  * <code>DES</code> in <code>CFB</code> or <code>OFB</code> mode), the user may
68  * optionally specify the number of bits to be
69  * processed at a time, by appending this number to the mode name as shown in
70  * the "<i>DES/CFB8/NoPadding</i>" and "<i>DES/OFB32/PKCS5Padding</i>"
71  * transformations. If no such number is specified, a provider-specific default
72  * is used. (For example, the "SunJCE" provider uses a default of 64 bits.)
73  *
74  * @author Jan Luehe
75  *
76  * @version 1.123, 03/31/04
77  *
78  * @see KeyGenerator
79  * @see SecretKey
80  * @since 1.4
81  */
82 public class Cipher
83 {
84     /**
85      * Constant used to initialize cipher to encryption mode.
86      */
87     public static final int ENCRYPT_MODE = 1;
88
89     /**
90      * Constant used to initialize cipher to decryption mode.
91      */
92     public static final int DECRYPT_MODE = 2;
93
94     /**
95      * Constant used to initialize cipher to key-wrapping mode.
96      */
97     public static final int WRAP_MODE = 3;
98
99     /**
100      * Constant used to initialize cipher to key-unwrapping mode.
101      */
102     public static final int UNWRAP_MODE = 4;
103
104     /**
105      * Constant used to indicate the to-be-unwrapped key is a "public key".
106      */
107     public static final int PUBLIC_KEY = 1;
108
109     /**
110      * Constant used to indicate the to-be-unwrapped key is a "private key".
111      */
112     public static final int PRIVATE_KEY = 2;
113
114     /**
115      * Constant used to indicate the to-be-unwrapped key is a "secret key".
116      */
117     public static final int SECRET_KEY = 3;
118
119     /**
120      * Creates a Cipher object.
121      *
122      * @param cipherSpi the delegate
123      * @param provider the provider
124      * @param transformation the transformation
125      */
126     protected Cipher(CipherSpi cipherSpi, Provider provider, String
127         transformation)
128     { }
129
130     /**
131      * Generates a <code>Cipher</code> object that implements the specified
132      * transformation.
133      *
134      * <p>If the default provider package supplies an implementation of the
135      * requested transformation, an instance of <code>Cipher</code> containing
136      * that implementation is returned.
137      * If the transformation is not available in the default provider package,
138      * other provider packages are searched.
139      *
140      * @param transformation the name of the transformation, e.g.,
141      * <i>DES/CBC/PKCS5Padding</i>.
142      * See Appendix A in the
143      * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppA">
144      * Java Cryptography Extension Reference Guide</a>
145      * for information about standard transformation names.
146      *
147      * @return a cipher that implements the requested transformation
148      *
149      * @exception NoSuchAlgorithmException if <code>transformation</code>
150      * is null, empty, in an invalid format, or not available from the
151      * current installed providers.
152      * @exception NoSuchPaddingException if <code>transformation</code>
153      * contains a padding scheme that is not available.
154      */
155     public static final Cipher getInstance(String transformation)
156         throws NoSuchAlgorithmException, NoSuchPaddingException
157     { }
158
159     /**
160      * Creates a <code>Cipher</code> object that implements the specified
161      * transformation, as supplied by the specified provider.
162      *
163      * @param transformation the name of the transformation,
164      * e.g., <i>DES/CBC/PKCS5Padding</i>.
165      * See Appendix A in the
166      * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppA">
167      * Java Cryptography Extension Reference Guide</a>
168      * for information about standard transformation names.
169      * @param provider the name of the provider
170      *
171      * @return a cipher that implements the requested transformation
172      *
173      * @exception NoSuchAlgorithmException if <code>transformation</code>
174      * is null, empty, in an invalid format, or not available from the
175      * specified provider.
176      * @exception NoSuchProviderException if the specified provider has not
177      * been configured.
178      * @exception NoSuchPaddingException if <code>transformation</code>
179      * contains a padding scheme that is not available.
180      * @exception IllegalArgumentException if the <code>provider</code>
181      * is null.
182      */
183     public static final Cipher getInstance(String transformation, String
184         provider)
185         throws NoSuchAlgorithmException, NoSuchProviderException,
186         NoSuchPaddingException
187     { }
188
189     /**
190      * Creates a <code>Cipher</code> object that implements the specified
191      * transformation, as supplied by the specified provider. Note: the
192      * <code>provider</code> doesn't have to be registered.
193      *
194      * @param transformation the name of the transformation,
195      * e.g., <i>DES/CBC/PKCS5Padding</i>.
196      * See Appendix A in the
197      * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppA">
198      * Java Cryptography Extension Reference Guide</a>
199      * for information about standard transformation names.
200      * @param provider the provider
201      *
202      * @return a cipher that implements the requested transformation
203      *
204      * @exception NoSuchAlgorithmException if <code>transformation</code>
205      * is null, empty, in an invalid format, or not available from the
206      * specified provider.
207      * @exception NoSuchPaddingException if <code>transformation</code>
208      * contains a padding scheme that is not available.
209      * @exception IllegalArgumentException if the <code>provider</code>
210      * is null.
211      */
212     public static final Cipher getInstance(String transformation, Provider
213         provider) throws NoSuchAlgorithmException, NoSuchPaddingException
214     { }
215
216     /**
217      * Returns the provider of this <code>Cipher</code> object.
218      *
219      * @return the provider of this <code>Cipher</code> object
220      */
221     public final Provider getProvider() { }
222
223     /**
224      * Returns the algorithm name of this <code>Cipher</code> object.
225      *
226      * <p>This is the same name that was specified in one of the
227      * <code>getInstance</code> calls that created this <code>Cipher</code>
228      * object..
229      *
230      * @return the algorithm name of this <code>Cipher</code> object.
231      */
232     public final String getAlgorithm() { }
233
234     /**
235      * Returns the block size (in bytes).
236      *
237      * @return the block size (in bytes), or 0 if the underlying algorithm is
238      * not a block cipher
239      */
240     public final int getBlockSize() { }
241
242     /**
243      * Returns the length in bytes that an output buffer would need to be in
244      * order to hold the result of the next <code>update</code> or
245      * <code>doFinal</code> operation, given the input length
246      * <code>inputLen</code> (in bytes).
247      *
248      * <p>This call takes into account any unprocessed (buffered) data from a
249      * previous <code>update</code> call, and padding.
250      *
251      * <p>The actual output length of the next <code>update</code> or
252      * <code>doFinal</code> call may be smaller than the length returned by
253      * this method.
254      *
255      * @param inputLen the input length (in bytes)
256      *
257      * @return the required output buffer size (in bytes)
258      *
259      * @exception IllegalStateException if this cipher is in a wrong state
260      * (e.g., has not yet been initialized)
261      */
262     public final int getOutputSize(int inputLen) { }
263
264     /**
265      * Returns the initialization vector (IV) in a new buffer.
266      *
267      * <p>This is useful in the case where a random IV was created,
268      * or in the context of password-based encryption or
269      * decryption, where the IV is derived from a user-supplied password.
270      *
271      * @return the initialization vector in a new buffer, or null if the
272      * underlying algorithm does not use an IV, or if the IV has not yet
273      * been set.
274      */
275     public final byte[] getIV() { }
276
277     /**
278      * Returns the parameters used with this cipher.
279      *
280      * <p>The returned parameters may be the same that were used to initialize
281      * this cipher, or may contain a combination of default and random
282      * parameter values used by the underlying cipher implementation if this
283      * cipher requires algorithm parameters but was not initialized with any.
284      *
285      * @return the parameters used with this cipher, or null if this cipher
286      * does not use any parameters.
287      */
288     public final AlgorithmParameters getParameters() { }
289
290     /**
291      * Returns the exemption mechanism object used with this cipher.
292      *
293      * @return the exemption mechanism object used with this cipher, or
294      * null if this cipher does not use any exemption mechanism.
295      */
296     public final ExemptionMechanism getExemptionMechanism() { }
297
298     /**
299      * Initializes this cipher with a key.
300      *
301      * <p>The cipher is initialized for one of the following four operations:
302      * encryption, decryption, key wrapping or key unwrapping, depending
303      * on the value of <code>opmode</code>.
304      *
305      * <p>If this cipher requires any algorithm parameters that cannot be
306      * derived from the given <code>key</code>, the underlying cipher
307      * implementation is supposed to generate the required parameters itself
308      * (using provider-specific default or random values) if it is being
309      * initialized for encryption or key wrapping, and raise an
310      * <code>InvalidKeyException</code> if it is being
311      * initialized for decryption or key unwrapping.
312      * The generated parameters can be retrieved using
313      * {@link #getParameters() getParameters} or
314      * {@link #getIV() getIV} (if the parameter is an IV).
315      *
316      * <p>If this cipher (including its underlying feedback or padding scheme)
317      * requires any random bytes (e.g., for parameter generation), it will get
318      * them using the {@link SecureRandom <code>SecureRandom</code>}
319      * implementation of the highest-priority
320      * installed provider as the source of randomness.
321      * (If none of the installed providers supply an implementation of
322      * SecureRandom, a system-provided source of randomness will be used.)
323      *
324      * <p>Note that when a Cipher object is initialized, it loses all
325      * previously-acquired state. In other words, initializing a Cipher is
326      * equivalent to creating a new instance of that Cipher and initializing
327      * it.
328      *
329      * @param opmode the operation mode of this cipher (this is one of
330      * the following:
331      * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>,
332      * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>)
333      * @param key the key
334      *
335      * @exception InvalidKeyException if the given key is inappropriate for
336      * initializing this cipher, or if this cipher is being initialized for
337      * decryption and requires algorithm parameters that cannot be
338      * determined from the given key, or if the given key has a keysize that
339      * exceeds the maximum allowable keysize (as determined from the
340      * configured jurisdiction policy files).
341      */
342     public final void init(int opmode, Key key) throws InvalidKeyException { }
343
344     /**
345      * Initializes this cipher with a key and a source of randomness.
346      *
347      * <p>The cipher is initialized for one of the following four operations:
348      * encryption, decryption, key wrapping or key unwrapping, depending
349      * on the value of <code>opmode</code>.
350      *
351      * <p>If this cipher requires any algorithm parameters that cannot be
352      * derived from the given <code>key</code>, the underlying cipher
353      * implementation is supposed to generate the required parameters itself
354      * (using provider-specific default or random values) if it is being
355      * initialized for encryption or key wrapping, and raise an
356      * <code>InvalidKeyException</code> if it is being
357      * initialized for decryption or key unwrapping.
358      * The generated parameters can be retrieved using
359      * {@link #getParameters() getParameters} or
360      * {@link #getIV() getIV} (if the parameter is an IV).
361      *
362      * <p>If this cipher (including its underlying feedback or padding scheme)
363      * requires any random bytes (e.g., for parameter generation), it will get
364      * them from <code>random</code>.
365      *
366      * <p>Note that when a Cipher object is initialized, it loses all
367      * previously-acquired state. In other words, initializing a Cipher is
368      * equivalent to creating a new instance of that Cipher and initializing
369      * it.
370      *
371      * @param opmode the operation mode of this cipher (this is one of the
372      * following:
373      * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>,
374      * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>)
375      * @param key the encryption key
376      * @param random the source of randomness
377      *
378      * @exception InvalidKeyException if the given key is inappropriate for
379      * initializing this cipher, or if this cipher is being initialized for
380      * decryption and requires algorithm parameters that cannot be
381      * determined from the given key, or if the given key has a keysize that
382      * exceeds the maximum allowable keysize (as determined from the
383      * configured jurisdiction policy files).
384      */
385     public final void init(int opmode, Key key, SecureRandom random)
386         throws InvalidKeyException
387     { }
388
389     /**
390      * Initializes this cipher with a key and a set of algorithm
391      * parameters.
392      *
393      * <p>The cipher is initialized for one of the following four operations:
394      * encryption, decryption, key wrapping or key unwrapping, depending
395      * on the value of <code>opmode</code>.
396      *
397      * <p>If this cipher requires any algorithm parameters and
398      * <code>params</code> is null, the underlying cipher implementation is
399      * supposed to generate the required parameters itself (using
400      * provider-specific default or random values) if it is being
401      * initialized for encryption or key wrapping, and raise an
402      * <code>InvalidAlgorithmParameterException</code> if it is being
403      * initialized for decryption or key unwrapping.
404      * The generated parameters can be retrieved using
405      * {@link #getParameters() getParameters} or
406      * {@link #getIV() getIV} (if the parameter is an IV).
407      *
408      * <p>If this cipher (including its underlying feedback or padding scheme)
409      * requires any random bytes (e.g., for parameter generation), it will get
410      * them using the {@link SecureRandom <code>SecureRandom</code>}
411      * implementation of the highest-priority
412      * installed provider as the source of randomness.
413      * (If none of the installed providers supply an implementation of
414      * SecureRandom, a system-provided source of randomness will be used.)
415      *
416      * <p>Note that when a Cipher object is initialized, it loses all
417      * previously-acquired state. In other words, initializing a Cipher is
418      * equivalent to creating a new instance of that Cipher and initializing
419      * it.
420      *
421      * @param opmode the operation mode of this cipher (this is one of the
422      * following:
423      * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>,
424      * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>)
425      * @param key the encryption key
426      * @param params the algorithm parameters
427      *
428      * @exception InvalidKeyException if the given key is inappropriate for
429      * initializing this cipher, or its keysize exceeds the maximum allowable
430      * keysize (as determined from the configured jurisdiction policy files).
431      * @exception InvalidAlgorithmParameterException if the given algorithm
432      * parameters are inappropriate for this cipher,
433      * or this cipher is being initialized for decryption and requires
434      * algorithm parameters and <code>params</code> is null, or the given
435      * algorithm parameters imply a cryptographic strength that would exceed
436      * the legal limits (as determined from the configured jurisdiction
437      * policy files).
438      */
439     public final void init(int opmode, Key key, AlgorithmParameterSpec params)
440         throws InvalidKeyException, InvalidAlgorithmParameterException
441     { }
442
443     /**
444      * Initializes this cipher with a key, a set of algorithm
445      * parameters, and a source of randomness.
446      *
447      * <p>The cipher is initialized for one of the following four operations:
448      * encryption, decryption, key wrapping or key unwrapping, depending
449      * on the value of <code>opmode</code>.
450      *
451      * <p>If this cipher requires any algorithm parameters and
452      * <code>params</code> is null, the underlying cipher implementation is
453      * supposed to generate the required parameters itself (using
454      * provider-specific default or random values) if it is being
455      * initialized for encryption or key wrapping, and raise an
456      * <code>InvalidAlgorithmParameterException</code> if it is being
457      * initialized for decryption or key unwrapping.
458      * The generated parameters can be retrieved using
459      * {@link #getParameters() getParameters} or
460      * {@link #getIV() getIV} (if the parameter is an IV).
461      *
462      * <p>If this cipher (including its underlying feedback or padding scheme)
463      * requires any random bytes (e.g., for parameter generation), it will get
464      * them from <code>random</code>.
465      *
466      * <p>Note that when a Cipher object is initialized, it loses all
467      * previously-acquired state. In other words, initializing a Cipher is
468      * equivalent to creating a new instance of that Cipher and initializing
469      * it.
470      *
471      * @param opmode the operation mode of this cipher (this is one of the
472      * following:
473      * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>,
474      * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>)
475      * @param key the encryption key
476      * @param params the algorithm parameters
477      * @param random the source of randomness
478      *
479      * @exception InvalidKeyException if the given key is inappropriate for
480      * initializing this cipher, or its keysize exceeds the maximum allowable
481      * keysize (as determined from the configured jurisdiction policy files).
482      * @exception InvalidAlgorithmParameterException if the given algorithm
483      * parameters are inappropriate for this cipher,
484      * or this cipher is being initialized for decryption and requires
485      * algorithm parameters and <code>params</code> is null, or the given
486      * algorithm parameters imply a cryptographic strength that would exceed
487      * the legal limits (as determined from the configured jurisdiction
488      * policy files).
489      */
490     public final void init(int opmode, Key key, AlgorithmParameterSpec params,
491         SecureRandom random)
492         throws InvalidKeyException, InvalidAlgorithmParameterException
493     { }
494
495     /**
496      * Initializes this cipher with a key and a set of algorithm
497      * parameters.
498      *
499      * <p>The cipher is initialized for one of the following four operations:
500      * encryption, decryption, key wrapping or key unwrapping, depending
501      * on the value of <code>opmode</code>.
502      *
503      * <p>If this cipher requires any algorithm parameters and
504      * <code>params</code> is null, the underlying cipher implementation is
505      * supposed to generate the required parameters itself (using
506      * provider-specific default or random values) if it is being
507      * initialized for encryption or key wrapping, and raise an
508      * <code>InvalidAlgorithmParameterException</code> if it is being
509      * initialized for decryption or key unwrapping.
510      * The generated parameters can be retrieved using
511      * {@link #getParameters() getParameters} or
512      * {@link #getIV() getIV} (if the parameter is an IV).
513      *
514      * <p>If this cipher (including its underlying feedback or padding scheme)
515      * requires any random bytes (e.g., for parameter generation), it will get
516      * them using the {@link SecureRandom <code>SecureRandom</code>}
517      * implementation of the highest-priority
518      * installed provider as the source of randomness.
519      * (If none of the installed providers supply an implementation of
520      * SecureRandom, a system-provided source of randomness will be used.)
521      *
522      * <p>Note that when a Cipher object is initialized, it loses all
523      * previously-acquired state. In other words, initializing a Cipher is
524      * equivalent to creating a new instance of that Cipher and initializing
525      * it.
526      *
527      * @param opmode the operation mode of this cipher (this is one of the
528      * following: <code>ENCRYPT_MODE</code>,
529      * <code>DECRYPT_MODE</code>, <code>WRAP_MODE</code>
530      * or <code>UNWRAP_MODE</code>)
531      * @param key the encryption key
532      * @param params the algorithm parameters
533      *
534      * @exception InvalidKeyException if the given key is inappropriate for
535      * initializing this cipher, or its keysize exceeds the maximum allowable
536      * keysize (as determined from the configured jurisdiction policy files).
537      * @exception InvalidAlgorithmParameterException if the given algorithm
538      * parameters are inappropriate for this cipher,
539      * or this cipher is being initialized for decryption and requires
540      * algorithm parameters and <code>params</code> is null, or the given
541      * algorithm parameters imply a cryptographic strength that would exceed
542      * the legal limits (as determined from the configured jurisdiction
543      * policy files).
544      */
545     public final void init(int opmode, Key key, AlgorithmParameters params)
546         throws InvalidKeyException, InvalidAlgorithmParameterException
547     { }
548
549     /**
550      * Initializes this cipher with a key, a set of algorithm
551      * parameters, and a source of randomness.
552      *
553      * <p>The cipher is initialized for one of the following four operations:
554      * encryption, decryption, key wrapping or key unwrapping, depending
555      * on the value of <code>opmode</code>.
556      *
557      * <p>If this cipher requires any algorithm parameters and
558      * <code>params</code> is null, the underlying cipher implementation is
559      * supposed to generate the required parameters itself (using
560      * provider-specific default or random values) if it is being
561      * initialized for encryption or key wrapping, and raise an
562      * <code>InvalidAlgorithmParameterException</code> if it is being
563      * initialized for decryption or key unwrapping.
564      * The generated parameters can be retrieved using
565      * {@link #getParameters() getParameters} or
566      * {@link #getIV() getIV} (if the parameter is an IV).
567      *
568      * <p>If this cipher (including its underlying feedback or padding scheme)
569      * requires any random bytes (e.g., for parameter generation), it will get
570      * them from <code>random</code>.
571      *
572      * <p>Note that when a Cipher object is initialized, it loses all
573      * previously-acquired state. In other words, initializing a Cipher is
574      * equivalent to creating a new instance of that Cipher and initializing
575      * it.
576      *
577      * @param opmode the operation mode of this cipher (this is one of the
578      * following: <code>ENCRYPT_MODE</code>,
579      * <code>DECRYPT_MODE</code>, <code>WRAP_MODE</code>
580      * or <code>UNWRAP_MODE</code>)
581      * @param key the encryption key
582      * @param params the algorithm parameters
583      * @param random the source of randomness
584      *
585      * @exception InvalidKeyException if the given key is inappropriate for
586      * initializing this cipher, or its keysize exceeds the maximum allowable
587      * keysize (as determined from the configured jurisdiction policy files).
588      * @exception InvalidAlgorithmParameterException if the given algorithm
589      * parameters are inappropriate for this cipher,
590      * or this cipher is being initialized for decryption and requires
591      * algorithm parameters and <code>params</code> is null, or the given
592      * algorithm parameters imply a cryptographic strength that would exceed
593      * the legal limits (as determined from the configured jurisdiction
594      * policy files).
595      */
596     public final void init(int opmode, Key key, AlgorithmParameters params,
597         SecureRandom random)
598         throws InvalidKeyException, InvalidAlgorithmParameterException
599     { }
600
601     /**
602      * Initializes this cipher with the public key from the given certificate.
603      * <p> The cipher is initialized for one of the following four operations:
604      * encryption, decryption, key wrapping or key unwrapping, depending
605      * on the value of <code>opmode</code>.
606      *
607      * <p>If the certificate is of type X.509 and has a <i>key usage</i>
608      * extension field marked as critical, and the value of the <i>key usage</i>
609      * extension field implies that the public key in
610      * the certificate and its corresponding private key are not
611      * supposed to be used for the operation represented by the value
612      * of <code>opmode</code>,
613      * an <code>InvalidKeyException</code>
614      * is thrown.
615      *
616      * <p> If this cipher requires any algorithm parameters that cannot be
617      * derived from the public key in the given certificate, the underlying
618      * cipher
619      * implementation is supposed to generate the required parameters itself
620      * (using provider-specific default or ramdom values) if it is being
621      * initialized for encryption or key wrapping, and raise an <code>
622      * InvalidKeyException</code> if it is being initialized for decryption or
623      * key unwrapping.
624      * The generated parameters can be retrieved using
625      * {@link #getParameters() getParameters} or
626      * {@link #getIV() getIV} (if the parameter is an IV).
627      *
628      * <p>If this cipher (including its underlying feedback or padding scheme)
629      * requires any random bytes (e.g., for parameter generation), it will get
630      * them using the
631      * <code>SecureRandom</code>
632      * implementation of the highest-priority
633      * installed provider as the source of randomness.
634      * (If none of the installed providers supply an implementation of
635      * SecureRandom, a system-provided source of randomness will be used.)
636      *
637      * <p>Note that when a Cipher object is initialized, it loses all
638      * previously-acquired state. In other words, initializing a Cipher is
639      * equivalent to creating a new instance of that Cipher and initializing
640      * it.
641      *
642      * @param opmode the operation mode of this cipher (this is one of the
643      * following:
644      * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>,
645      * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>)
646      * @param certificate the certificate
647      *
648      * @exception InvalidKeyException if the public key in the given
649      * certificate is inappropriate for initializing this cipher, or this
650      * cipher is being initialized for decryption or unwrapping keys and
651      * requires algorithm parameters that cannot be determined from the
652      * public key in the given certificate, or the keysize of the public key
653      * in the given certificate has a keysize that exceeds the maximum
654      * allowable keysize (as determined by the configured jurisdiction policy
655      * files).
656      */
657     public final void init(int opmode, Certificate certificate)
658         throws InvalidKeyException
659     { }
660
661     /**
662      * Initializes this cipher with the public key from the given certificate
663      * and
664      * a source of randomness.
665      *
666      * <p>The cipher is initialized for one of the following four operations:
667      * encryption, decryption, key wrapping
668      * or key unwrapping, depending on
669      * the value of <code>opmode</code>.
670      *
671      * <p>If the certificate is of type X.509 and has a <i>key usage</i>
672      * extension field marked as critical, and the value of the <i>key usage</i>
673      * extension field implies that the public key in
674      * the certificate and its corresponding private key are not
675      * supposed to be used for the operation represented by the value of
676      * <code>opmode</code>,
677      * an <code>InvalidKeyException</code>
678      * is thrown.
679      *
680      * <p>If this cipher requires any algorithm parameters that cannot be
681      * derived from the public key in the given <code>certificate</code>,
682      * the underlying cipher
683      * implementation is supposed to generate the required parameters itself
684      * (using provider-specific default or random values) if it is being
685      * initialized for encryption or key wrapping, and raise an
686      * <code>InvalidKeyException</code> if it is being
687      * initialized for decryption or key unwrapping.
688      * The generated parameters can be retrieved using
689      * {@link #getParameters() getParameters} or
690      * {@link #getIV() getIV} (if the parameter is an IV).
691      *
692      * <p>If this cipher (including its underlying feedback or padding scheme)
693      * requires any random bytes (e.g., for parameter generation), it will get
694      * them from <code>random</code>.
695      *
696      * <p>Note that when a Cipher object is initialized, it loses all
697      * previously-acquired state. In other words, initializing a Cipher is
698      * equivalent to creating a new instance of that Cipher and initializing
699      * it.
700      *
701      * @param opmode the operation mode of this cipher (this is one of the
702      * following:
703      * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>,
704      * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>)
705      * @param certificate the certificate
706      * @param random the source of randomness
707      *
708      * @exception InvalidKeyException if the public key in the given
709      * certificate is inappropriate for initializing this cipher, or this
710      * cipher is being initialized for decryption or unwrapping keys and
711      * requires algorithm parameters that cannot be determined from the
712      * public key in the given certificate, or the keysize of the public key
713      * in the given certificate has a keysize that exceeds the maximum
714      * allowable keysize (as determined by the configured jurisdiction policy
715      * files).
716      */
717     public final void init(int opmode, Certificate certificate, SecureRandom
718         random) throws InvalidKeyException
719     { }
720
721     /**
722      * Continues a multiple-part encryption or decryption operation
723      * (depending on how this cipher was initialized), processing another data
724      * part.
725      *
726      * <p>The bytes in the <code>input</code> buffer are processed, and the
727      * result is stored in a new buffer.
728      *
729      * <p>If <code>input</code> has a length of zero, this method returns
730      * <code>null</code>.
731      *
732      * @param input the input buffer
733      *
734      * @return the new buffer with the result, or null if the underlying
735      * cipher is a block cipher and the input data is too short to result in a
736      * new block.
737      *
738      * @exception IllegalStateException if this cipher is in a wrong state
739      * (e.g., has not been initialized)
740      */
741     public final byte[] update(byte[] input) { }
742
743     /**
744      * Continues a multiple-part encryption or decryption operation
745      * (depending on how this cipher was initialized), processing another data
746      * part.
747      *
748      * <p>The first <code>inputLen</code> bytes in the <code>input</code>
749      * buffer, starting at <code>inputOffset</code> inclusive, are processed,
750      * and the result is stored in a new buffer.
751      *
752      * <p>If <code>inputLen</code> is zero, this method returns
753      * <code>null</code>.
754      *
755      * @param input the input buffer
756      * @param inputOffset the offset in <code>input</code> where the input
757      * starts
758      * @param inputLen the input length
759      *
760      * @return the new buffer with the result, or null if the underlying
761      * cipher is a block cipher and the input data is too short to result in a
762      * new block.
763      *
764      * @exception IllegalStateException if this cipher is in a wrong state
765      * (e.g., has not been initialized)
766      */
767     public final byte[] update(byte[] input, int inputOffset, int inputLen) { }
768
769     /**
770      * Continues a multiple-part encryption or decryption operation
771      * (depending on how this cipher was initialized), processing another data
772      * part.
773      *
774      * <p>The first <code>inputLen</code> bytes in the <code>input</code>
775      * buffer, starting at <code>inputOffset</code> inclusive, are processed,
776      * and the result is stored in the <code>output</code> buffer.
777      *
778      * <p>If the <code>output</code> buffer is too small to hold the result,
779      * a <code>ShortBufferException</code> is thrown. In this case, repeat this
780      * call with a larger output buffer. Use
781      * {@link #getOutputSize(int) getOutputSize} to determine how big
782      * the output buffer should be.
783      *
784      * <p>If <code>inputLen</code> is zero, this method returns
785      * a length of zero.
786      *
787      * <p>Note: this method should be copy-safe, which means the
788      * <code>input</code> and <code>output</code> buffers can reference
789      * the same byte array and no unprocessed input data is overwritten
790      * when the result is copied into the output buffer.
791      *
792      * @param input the input buffer
793      * @param inputOffset the offset in <code>input</code> where the input
794      * starts
795      * @param inputLen the input length
796      * @param output the buffer for the result
797      *
798      * @return the number of bytes stored in <code>output</code>
799      *
800      * @exception IllegalStateException if this cipher is in a wrong state
801      * (e.g., has not been initialized)
802      * @exception ShortBufferException if the given output buffer is too small
803      * to hold the result
804      */
805     public final int update(byte[] input, int inputOffset, int inputLen, byte[]
806         output) throws ShortBufferException
807     { }
808
809     /**
810      * Continues a multiple-part encryption or decryption operation
811      * (depending on how this cipher was initialized), processing another data
812      * part.
813      *
814      * <p>The first <code>inputLen</code> bytes in the <code>input</code>
815      * buffer, starting at <code>inputOffset</code> inclusive, are processed,
816      * and the result is stored in the <code>output</code> buffer, starting at
817      * <code>outputOffset</code> inclusive.
818      *
819      * <p>If the <code>output</code> buffer is too small to hold the result,
820      * a <code>ShortBufferException</code> is thrown. In this case, repeat this
821      * call with a larger output buffer. Use
822      * {@link #getOutputSize(int) getOutputSize} to determine how big
823      * the output buffer should be.
824      *
825      * <p>If <code>inputLen</code> is zero, this method returns
826      * a length of zero.
827      *
828      * <p>Note: this method should be copy-safe, which means the
829      * <code>input</code> and <code>output</code> buffers can reference
830      * the same byte array and no unprocessed input data is overwritten
831      * when the result is copied into the output buffer.
832      *
833      * @param input the input buffer
834      * @param inputOffset the offset in <code>input</code> where the input
835      * starts
836      * @param inputLen the input length
837      * @param output the buffer for the result
838      * @param outputOffset the offset in <code>output</code> where the result
839      * is stored
840      *
841      * @return the number of bytes stored in <code>output</code>
842      *
843      * @exception IllegalStateException if this cipher is in a wrong state
844      * (e.g., has not been initialized)
845      * @exception ShortBufferException if the given output buffer is too small
846      * to hold the result
847      */
848     public final int update(byte[] input, int inputOffset, int inputLen, byte[]
849         output, int outputOffset) throws ShortBufferException
850     { }
851
852     /**
853      * Continues a multiple-part encryption or decryption operation
854      * (depending on how this cipher was initialized), processing another data
855      * part.
856      *
857      * <p>All <code>input.remaining()</code> bytes starting at
858      * <code>input.position()</code> are processed. The result is stored
859      * in the output buffer.
860      * Upon return, the input buffer's position will be equal
861      * to its limit; its limit will not have changed. The output buffer's
862      * position will have advanced by n, where n is the value returned
863      * by this method; the output buffer's limit will not have changed.
864      *
865      * <p>If <code>output.remaining()</code> bytes are insufficient to
866      * hold the result, a <code>ShortBufferException</code> is thrown.
867      * In this case, repeat this call with a larger output buffer. Use
868      * {@link #getOutputSize(int) getOutputSize} to determine how big
869      * the output buffer should be.
870      *
871      * <p>Note: this method should be copy-safe, which means the
872      * <code>input</code> and <code>output</code> buffers can reference
873      * the same block of memory and no unprocessed input data is overwritten
874      * when the result is copied into the output buffer.
875      *
876      * @param input the input ByteBuffer
877      * @param output the output ByteByffer
878      *
879      * @return the number of bytes stored in <code>output</code>
880      *
881      * @exception IllegalStateException if this cipher is in a wrong state
882      * (e.g., has not been initialized)
883      * @exception IllegalArgumentException if input and output are the
884      * same object
885      * @exception ReadOnlyBufferException if the output buffer is read-only
886      * @exception ShortBufferException if there is insufficient space in the
887      * output buffer
888      * @since 1.5
889      */
890     public final int update(ByteBuffer input, ByteBuffer output)
891         throws ShortBufferException
892     { }
893
894     /**
895      * Finishes a multiple-part encryption or decryption operation, depending
896      * on how this cipher was initialized.
897      *
898      * <p>Input data that may have been buffered during a previous
899      * <code>update</code> operation is processed, with padding (if requested)
900      * being applied.
901      * The result is stored in a new buffer.
902      *
903      * <p>Upon finishing, this method resets this cipher object to the state
904      * it was in when previously initialized via a call to <code>init</code>.
905      * That is, the object is reset and available to encrypt or decrypt
906      * (depending on the operation mode that was specified in the call to
907      * <code>init</code>) more data.
908      *
909      * <p>Note: if any exception is thrown, this cipher object may need to
910      * be reset before it can be used again.
911      *
912      * @return the new buffer with the result
913      *
914      * @exception IllegalStateException if this cipher is in a wrong state
915      * (e.g., has not been initialized)
916      * @exception IllegalBlockSizeException if this cipher is a block cipher,
917      * no padding has been requested (only in encryption mode), and the total
918      * input length of the data processed by this cipher is not a multiple of
919      * block size; or if this encryption algorithm is unable to
920      * process the input data provided.
921      * @exception BadPaddingException if this cipher is in decryption mode,
922      * and (un)padding has been requested, but the decrypted data is not
923      * bounded by the appropriate padding bytes
924      */
925     public final byte[] doFinal()
926         throws IllegalBlockSizeException, BadPaddingException
927     { }
928
929     /**
930      * Finishes a multiple-part encryption or decryption operation, depending
931      * on how this cipher was initialized.
932      *
933      * <p>Input data that may have been buffered during a previous
934      * <code>update</code> operation is processed, with padding (if requested)
935      * being applied.
936      * The result is stored in the <code>output</code> buffer, starting at
937      * <code>outputOffset</code> inclusive.
938      *
939      * <p>If the <code>output</code> buffer is too small to hold the result,
940      * a <code>ShortBufferException</code> is thrown. In this case, repeat this
941      * call with a larger output buffer. Use
942      * {@link #getOutputSize(int) getOutputSize} to determine how big
943      * the output buffer should be.
944      *
945      * <p>Upon finishing, this method resets this cipher object to the state
946      * it was in when previously initialized via a call to <code>init</code>.
947      * That is, the object is reset and available to encrypt or decrypt
948      * (depending on the operation mode that was specified in the call to
949      * <code>init</code>) more data.
950      *
951      * <p>Note: if any exception is thrown, this cipher object may need to
952      * be reset before it can be used again.
953      *
954      * @param output the buffer for the result
955      * @param outputOffset the offset in <code>output</code> where the result
956      * is stored
957      *
958      * @return the number of bytes stored in <code>output</code>
959      *
960      * @exception IllegalStateException if this cipher is in a wrong state
961      * (e.g., has not been initialized)
962      * @exception IllegalBlockSizeException if this cipher is a block cipher,
963      * no padding has been requested (only in encryption mode), and the total
964      * input length of the data processed by this cipher is not a multiple of
965      * block size; or if this encryption algorithm is unable to
966      * process the input data provided.
967      * @exception ShortBufferException if the given output buffer is too small
968      * to hold the result
969      * @exception BadPaddingException if this cipher is in decryption mode,
970      * and (un)padding has been requested, but the decrypted data is not
971      * bounded by the appropriate padding bytes
972      */
973     public final int doFinal(byte[] output, int outputOffset)
974         throws IllegalBlockSizeException, ShortBufferException,
975         BadPaddingException
976     { }
977
978     /**
979      * Encrypts or decrypts data in a single-part operation, or finishes a
980      * multiple-part operation. The data is encrypted or decrypted,
981      * depending on how this cipher was initialized.
982      *
983      * <p>The bytes in the <code>input</code> buffer, and any input bytes that
984      * may have been buffered during a previous <code>update</code> operation,
985      * are processed, with padding (if requested) being applied.
986      * The result is stored in a new buffer.
987      *
988      * <p>Upon finishing, this method resets this cipher object to the state
989      * it was in when previously initialized via a call to <code>init</code>.
990      * That is, the object is reset and available to encrypt or decrypt
991      * (depending on the operation mode that was specified in the call to
992      * <code>init</code>) more data.
993      *
994      * <p>Note: if any exception is thrown, this cipher object may need to
995      * be reset before it can be used again.
996      *
997      * @param input the input buffer
998      *
999      * @return the new buffer with the result
1000     *
1001     * @exception IllegalStateException if this cipher is in a wrong state
1002     * (e.g., has not been initialized)
1003     * @exception IllegalBlockSizeException if this cipher is a block cipher,
1004     * no padding has been requested (only in encryption mode), and the total
1005     * input length of the data processed by this cipher is not a multiple of
1006     * block size; or if this encryption algorithm is unable to
1007     * process the input data provided.
1008     * @exception BadPaddingException if this cipher is in decryption mode,
1009     * and (un)padding has been requested, but the decrypted data is not
1010     * bounded by the appropriate padding bytes
1011     */
1012    public final byte[] doFinal(byte[] input)
1013        throws IllegalBlockSizeException, BadPaddingException
1014    { }
1015
1016    /**
1017     * Encrypts or decrypts data in a single-part operation, or finishes a
1018     * multiple-part operation. The data is encrypted or decrypted,
1019     * depending on how this cipher was initialized.
1020     *
1021     * <p>The first <code>inputLen</code> bytes in the <code>input</code>
1022     * buffer, starting at <code>inputOffset</code> inclusive, and any input
1023     * bytes that may have been buffered during a previous <code>update</code>
1024     * operation, are processed, with padding (if requested) being applied.
1025     * The result is stored in a new buffer.
1026     *
1027     * <p>Upon finishing, this method resets this cipher object to the state
1028     * it was in when previously initialized via a call to <code>init</code>.
1029     * That is, the object is reset and available to encrypt or decrypt
1030     * (depending on the operation mode that was specified in the call to
1031     * <code>init</code>) more data.
1032     *
1033     * <p>Note: if any exception is thrown, this cipher object may need to
1034     * be reset before it can be used again.
1035     *
1036     * @param input the input buffer
1037     * @param inputOffset the offset in <code>input</code> where the input
1038     * starts
1039     * @param inputLen the input length
1040     *
1041     * @return the new buffer with the result
1042     *
1043     * @exception IllegalStateException if this cipher is in a wrong state
1044     * (e.g., has not been initialized)
1045     * @exception IllegalBlockSizeException if this cipher is a block cipher,
1046     * no padding has been requested (only in encryption mode), and the total
1047     * input length of the data processed by this cipher is not a multiple of
1048     * block size; or if this encryption algorithm is unable to
1049     * process the input data provided.
1050     * @exception BadPaddingException if this cipher is in decryption mode,
1051     * and (un)padding has been requested, but the decrypted data is not
1052     * bounded by the appropriate padding bytes
1053     */
1054    public final byte[] doFinal(byte[] input, int inputOffset, int inputLen)
1055        throws IllegalBlockSizeException, BadPaddingException
1056    { }
1057
1058    /**
1059     * Encrypts or decrypts data in a single-part operation, or finishes a
1060     * multiple-part operation. The data is encrypted or decrypted,
1061     * depending on how this cipher was initialized.
1062     *
1063     * <p>The first <code>inputLen</code> bytes in the <code>input</code>
1064     * buffer, starting at <code>inputOffset</code> inclusive, and any input
1065     * bytes that may have been buffered during a previous <code>update</code>
1066     * operation, are processed, with padding (if requested) being applied.
1067     * The result is stored in the <code>output</code> buffer.
1068     *
1069     * <p>If the <code>output</code> buffer is too small to hold the result,
1070     * a <code>ShortBufferException</code> is thrown. In this case, repeat this
1071     * call with a larger output buffer. Use
1072     * {@link #getOutputSize(int) getOutputSize} to determine how big
1073     * the output buffer should be.
1074     *
1075     * <p>Upon finishing, this method resets this cipher object to the state
1076     * it was in when previously initialized via a call to <code>init</code>.
1077     * That is, the object is reset and available to encrypt or decrypt
1078     * (depending on the operation mode that was specified in the call to
1079     * <code>init</code>) more data.
1080     *
1081     * <p>Note: if any exception is thrown, this cipher object may need to
1082     * be reset before it can be used again.
1083     *
1084     * <p>Note: this method should be copy-safe, which means the
1085     * <code>input</code> and <code>output</code> buffers can reference
1086     * the same byte array and no unprocessed input data is overwritten
1087     * when the result is copied into the output buffer.
1088     *
1089     * @param input the input buffer
1090     * @param inputOffset the offset in <code>input</code> where the input
1091     * starts
1092     * @param inputLen the input length
1093     * @param output the buffer for the result
1094     *
1095     * @return the number of bytes stored in <code>output</code>
1096     *
1097     * @exception IllegalStateException if this cipher is in a wrong state
1098     * (e.g., has not been initialized)
1099     * @exception IllegalBlockSizeException if this cipher is a block cipher,
1100     * no padding has been requested (only in encryption mode), and the total
1101     * input length of the data processed by this cipher is not a multiple of
1102     * block size; or if this encryption algorithm is unable to
1103     * process the input data provided.
1104     * @exception ShortBufferException if the given output buffer is too small
1105     * to hold the result
1106     * @exception BadPaddingException if this cipher is in decryption mode,
1107     * and (un)padding has been requested, but the decrypted data is not
1108     * bounded by the appropriate padding bytes
1109     */
1110    public final int doFinal(byte[] input, int inputOffset, int inputLen, byte[]
1111        output)
1112        throws ShortBufferException, IllegalBlockSizeException,
1113        BadPaddingException
1114    { }
1115
1116    /**
1117     * Encrypts or decrypts data in a single-part operation, or finishes a
1118     * multiple-part operation. The data is encrypted or decrypted,
1119     * depending on how this cipher was initialized.
1120     *
1121     * <p>The first <code>inputLen</code> bytes in the <code>input</code>
1122     * buffer, starting at <code>inputOffset</code> inclusive, and any input
1123     * bytes that may have been buffered during a previous
1124     * <code>update</code> operation, are processed, with padding
1125     * (if requested) being applied.
1126     * The result is stored in the <code>output</code> buffer, starting at
1127     * <code>outputOffset</code> inclusive.
1128     *
1129     * <p>If the <code>output</code> buffer is too small to hold the result,
1130     * a <code>ShortBufferException</code> is thrown. In this case, repeat this
1131     * call with a larger output buffer. Use
1132     * {@link #getOutputSize(int) getOutputSize} to determine how big
1133     * the output buffer should be.
1134     *
1135     * <p>Upon finishing, this method resets this cipher object to the state
1136     * it was in when previously initialized via a call to <code>init</code>.
1137     * That is, the object is reset and available to encrypt or decrypt
1138     * (depending on the operation mode that was specified in the call to
1139     * <code>init</code>) more data.
1140     *
1141     * <p>Note: if any exception is thrown, this cipher object may need to
1142     * be reset before it can be used again.
1143     *
1144     * <p>Note: this method should be copy-safe, which means the
1145     * <code>input</code> and <code>output</code> buffers can reference
1146     * the same byte array and no unprocessed input data is overwritten
1147     * when the result is copied into the output buffer.
1148     *
1149     * @param input the input buffer
1150     * @param inputOffset the offset in <code>input</code> where the input
1151     * starts
1152     * @param inputLen the input length
1153     * @param output the buffer for the result
1154     * @param outputOffset the offset in <code>output</code> where the result
1155     * is stored
1156     *
1157     * @return the number of bytes stored in <code>output</code>
1158     *
1159     * @exception IllegalStateException if this cipher is in a wrong state
1160     * (e.g., has not been initialized)
1161     * @exception IllegalBlockSizeException if this cipher is a block cipher,
1162     * no padding has been requested (only in encryption mode), and the total
1163     * input length of the data processed by this cipher is not a multiple of
1164     * block size; or if this encryption algorithm is unable to
1165     * process the input data provided.
1166     * @exception ShortBufferException if the given output buffer is too small
1167     * to hold the result
1168     * @exception BadPaddingException if this cipher is in decryption mode,
1169     * and (un)padding has been requested, but the decrypted data is not
1170     * bounded by the appropriate padding bytes
1171     */
1172    public final int doFinal(byte[] input, int inputOffset, int inputLen, byte[]
1173        output, int outputOffset)
1174        throws ShortBufferException, IllegalBlockSizeException,
1175        BadPaddingException
1176    { }
1177
1178    /**
1179     * Encrypts or decrypts data in a single-part operation, or finishes a
1180     * multiple-part operation. The data is encrypted or decrypted,
1181     * depending on how this cipher was initialized.
1182     *
1183     * <p>All <code>input.remaining()</code> bytes starting at
1184     * <code>input.position()</code> are processed. The result is stored
1185     * in the output buffer.
1186     * Upon return, the input buffer's position will be equal
1187     * to its limit; its limit will not have changed. The output buffer's
1188     * position will have advanced by n, where n is the value returned
1189     * by this method; the output buffer's limit will not have changed.
1190     *
1191     * <p>If <code>output.remaining()</code> bytes are insufficient to
1192     * hold the result, a <code>ShortBufferException</code> is thrown.
1193     * In this case, repeat this call with a larger output buffer. Use
1194     * {@link #getOutputSize(int) getOutputSize} to determine how big
1195     * the output buffer should be.
1196     *
1197     * <p>Upon finishing, this method resets this cipher object to the state
1198     * it was in when previously initialized via a call to <code>init</code>.
1199     * That is, the object is reset and available to encrypt or decrypt
1200     * (depending on the operation mode that was specified in the call to
1201     * <code>init</code>) more data.
1202     *
1203     * <p>Note: if any exception is thrown, this cipher object may need to
1204     * be reset before it can be used again.
1205     *
1206     * <p>Note: this method should be copy-safe, which means the
1207     * <code>input</code> and <code>output</code> buffers can reference
1208     * the same byte array and no unprocessed input data is overwritten
1209     * when the result is copied into the output buffer.
1210     *
1211     * @param input the input ByteBuffer
1212     * @param output the output ByteBuffer
1213     *
1214     * @return the number of bytes stored in <code>output</code>
1215     *
1216     * @exception IllegalStateException if this cipher is in a wrong state
1217     * (e.g., has not been initialized)
1218     * @exception IllegalArgumentException if input and output are the
1219     * same object
1220     * @exception ReadOnlyBufferException if the output buffer is read-only
1221     * @exception IllegalBlockSizeException if this cipher is a block cipher,
1222     * no padding has been requested (only in encryption mode), and the total
1223     * input length of the data processed by this cipher is not a multiple of
1224     * block size; or if this encryption algorithm is unable to
1225     * process the input data provided.
1226     * @exception ShortBufferException if there is insufficient space in the
1227     * output buffer
1228     * @exception BadPaddingException if this cipher is in decryption mode,
1229     * and (un)padding has been requested, but the decrypted data is not
1230     * bounded by the appropriate padding bytes
1231     * @since 1.5
1232     */
1233    public final int doFinal(ByteBuffer input, ByteBuffer output)
1234        throws ShortBufferException, IllegalBlockSizeException,
1235        BadPaddingException
1236    { }
1237
1238    /**
1239     * Wrap a key.
1240     *
1241     * @param key the key to be wrapped.
1242     *
1243     * @return the wrapped key.
1244     *
1245     * @exception IllegalStateException if this cipher is in a wrong
1246     * state (e.g., has not been initialized).
1247     *
1248     * @exception IllegalBlockSizeException if this cipher is a block
1249     * cipher, no padding has been requested, and the length of the
1250     * encoding of the key to be wrapped is not a
1251     * multiple of the block size.
1252     *
1253     * @exception InvalidKeyException if it is impossible or unsafe to
1254     * wrap the key with this cipher (e.g., a hardware protected key is
1255     * being passed to a software-only cipher).
1256     */
1257    public final byte[] wrap(Key key)
1258        throws IllegalBlockSizeException, InvalidKeyException
1259    { }
1260
1261    /**
1262     * Unwrap a previously wrapped key.
1263     *
1264     * @param wrappedKey the key to be unwrapped.
1265     *
1266     * @param wrappedKeyAlgorithm the algorithm associated with the wrapped
1267     * key.
1268     *
1269     * @param wrappedKeyType the type of the wrapped key. This must be one of
1270     * <code>SECRET_KEY</code>, <code>PRIVATE_KEY</code>, or
1271     * <code>PUBLIC_KEY</code>.
1272     *
1273     * @return the unwrapped key.
1274     *
1275     * @exception IllegalStateException if this cipher is in a wrong state
1276     * (e.g., has not been initialized).
1277     *
1278     * @exception NoSuchAlgorithmException if no installed providers
1279     * can create keys of type <code>wrappedKeyType</code> for the
1280     * <code>wrappedKeyAlgorithm</code>.
1281     *
1282     * @exception InvalidKeyException if <code>wrappedKey</code> does not
1283     * represent a wrapped key of type <code>wrappedKeyType</code> for
1284     * the <code>wrappedKeyAlgorithm</code>.
1285     */
1286    public final Key unwrap(byte[] wrappedKey, String wrappedKeyAlgorithm, int
1287        wrappedKeyType) throws InvalidKeyException, NoSuchAlgorithmException
1288    { }
1289
1290    /**
1291     * Returns the maximum key length for the specified transformation
1292     * according to the installed JCE jurisdiction policy files. If
1293     * JCE unlimited strength jurisdiction policy files are installed,
1294     * Integer.MAX_VALUE will be returned.
1295     * For more information on default key size in JCE jurisdiction
1296     * policy files, please see appendix E in
1297     * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppE">
1298     * JCE Reference Guide</a>.
1299     *
1300     * @param transformation the cipher transformation.
1301     * @return the maximum key length in bits or Integer.MAX_VALUE.
1302     * @exception NullPointerException if <code>transformation</code> is null.
1303     * @exception NoSuchAlgorithmException if <code>transformation</code>
1304     * is not a valid transformation, i.e. in the form of "algorithm" or
1305     * "algorithm/mode/padding".
1306     * @since 1.5
1307     */
1308    public static final int getMaxAllowedKeyLength(String transformation)
1309        throws NoSuchAlgorithmException
1310    { }
1311
1312    /**
1313     * Returns an AlgorithmParameterSpec object which contains
1314     * the maximum cipher parameter value according to the
1315     * jurisdiction policy file. If JCE unlimited strength jurisdiction
1316     * policy files are installed or there is no maximum limit on the
1317     * parameters for the specified transformation in the policy file,
1318     * null will be returned.
1319     *
1320     * @param transformation the cipher transformation.
1321     * @return an AlgorithmParameterSpec which holds the maximum
1322     * value or null.
1323     * @exception NullPointerException if <code>transformation</code>
1324     * is null.
1325     * @exception NoSuchAlgorithmException if <code>transformation</code>
1326     * is not a valid transformation, i.e. in the form of "algorithm" or
1327     * "algorithm/mode/padding".
1328     * @since 1.5
1329     */
1330    public static final AlgorithmParameterSpec getMaxAllowedParameterSpec(String
1331        transformation) throws NoSuchAlgorithmException
1332    { }
1333}
1334
Popular Tags