KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > crypto > CipherSpi


1 /*
2  * @(#)CipherSpi.java 1.8 03/12/19
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.StringTokenizer;
19 import java.util.NoSuchElementException;
20 import java.security.AlgorithmParameters;
21 import java.security.Provider;
22 import java.security.Key;
23 import java.security.SecureRandom;
24 import java.security.NoSuchAlgorithmException;
25 import java.security.NoSuchProviderException;
26 import java.security.InvalidKeyException;
27 import java.security.InvalidAlgorithmParameterException;
28 import java.security.ProviderException;
29 import java.security.spec.AlgorithmParameterSpec;
30 import java.nio.ByteBuffer;
31
32 /**
33  * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
34  * for the <code>Cipher</code> class.
35  * All the abstract methods in this class must be implemented by each
36  * cryptographic service provider who wishes to supply the implementation
37  * of a particular cipher algorithm.
38  *
39  * <p>In order to create an instance of <code>Cipher</code>, which
40  * encapsulates an instance of this <code>CipherSpi</code> class, an
41  * application calls one of the
42  * {@link Cipher#getInstance(java.lang.String) getInstance}
43  * factory methods of the
44  * {@link Cipher Cipher} engine class and specifies the requested
45  * <i>transformation</i>.
46  * Optionally, the application may also specify the name of a provider.
47  *
48  * <p>A <i>transformation</i> is a string that describes the operation (or
49  * set of operations) to be performed on the given input, to produce some
50  * output. A transformation always includes the name of a cryptographic
51  * algorithm (e.g., <i>DES</i>), and may be followed by a feedback mode and
52  * padding scheme.
53  *
54  * <p> A transformation is of the form:<p>
55  *
56  * <ul>
57  * <li>"<i>algorithm/mode/padding</i>" or
58  * <p>
59  * <li>"<i>algorithm</i>"
60  * </ul>
61  *
62  * <P> (in the latter case,
63  * provider-specific default values for the mode and padding scheme are used).
64  * For example, the following is a valid transformation:<p>
65  *
66  * <pre>
67  * Cipher c = Cipher.getInstance("<i>DES/CBC/PKCS5Padding</i>");
68  * </pre>
69  *
70  * <p>A provider may supply a separate class for each combination
71  * of <i>algorithm/mode/padding</i>, or may decide to provide more generic
72  * classes representing sub-transformations corresponding to
73  * <i>algorithm</i> or <i>algorithm/mode</i> or <i>algorithm//padding</i>
74  * (note the double slashes),
75  * in which case the requested mode and/or padding are set automatically by
76  * the <code>getInstance</code> methods of <code>Cipher</code>, which invoke
77  * the {@link #engineSetMode(java.lang.String) engineSetMode} and
78  * {@link #engineSetPadding(java.lang.String) engineSetPadding}
79  * methods of the provider's subclass of <code>CipherSpi</code>.
80  *
81  * <p>A <code>Cipher</code> property in a provider master class may have one of
82  * the following formats:
83  *
84  * <ul>
85  *
86  * <li>
87  * <pre>
88  * // provider's subclass of "CipherSpi" implements "algName" with
89  * // pluggable mode and padding
90  * <code>Cipher.</code><i>algName</i>
91  * </pre>
92  *
93  * <li>
94  * <pre>
95  * // provider's subclass of "CipherSpi" implements "algName" in the
96  * // specified "mode", with pluggable padding
97  * <code>Cipher.</code><i>algName/mode</i>
98  * </pre>
99  *
100  * <li>
101  * <pre>
102  * // provider's subclass of "CipherSpi" implements "algName" with the
103  * // specified "padding", with pluggable mode
104  * <code>Cipher.</code><i>algName//padding</i>
105  * </pre>
106  *
107  * <li>
108  * <pre>
109  * // provider's subclass of "CipherSpi" implements "algName" with the
110  * // specified "mode" and "padding"
111  * <code>Cipher.</code><i>algName/mode/padding</i>
112  * </pre>
113  *
114  * </ul>
115  *
116  * <p>For example, a provider may supply a subclass of <code>CipherSpi</code>
117  * that implements <i>DES/ECB/PKCS5Padding</i>, one that implements
118  * <i>DES/CBC/PKCS5Padding</i>, one that implements
119  * <i>DES/CFB/PKCS5Padding</i>, and yet another one that implements
120  * <i>DES/OFB/PKCS5Padding</i>. That provider would have the following
121  * <code>Cipher</code> properties in its master class:<p>
122  *
123  * <ul>
124  *
125  * <li>
126  * <pre>
127  * <code>Cipher.</code><i>DES/ECB/PKCS5Padding</i>
128  * </pre>
129  *
130  * <li>
131  * <pre>
132  * <code>Cipher.</code><i>DES/CBC/PKCS5Padding</i>
133  * </pre>
134  *
135  * <li>
136  * <pre>
137  * <code>Cipher.</code><i>DES/CFB/PKCS5Padding</i>
138  * </pre>
139  *
140  * <li>
141  * <pre>
142  * <code>Cipher.</code><i>DES/OFB/PKCS5Padding</i>
143  * </pre>
144  *
145  * </ul>
146  *
147  * <p>Another provider may implement a class for each of the above modes
148  * (i.e., one class for <i>ECB</i>, one for <i>CBC</i>, one for <i>CFB</i>,
149  * and one for <i>OFB</i>), one class for <i>PKCS5Padding</i>,
150  * and a generic <i>DES</i> class that subclasses from <code>CipherSpi</code>.
151  * That provider would have the following
152  * <code>Cipher</code> properties in its master class:<p>
153  *
154  * <ul>
155  *
156  * <li>
157  * <pre>
158  * <code>Cipher.</code><i>DES</i>
159  * </pre>
160  *
161  * </ul>
162  *
163  * <p>The <code>getInstance</code> factory method of the <code>Cipher</code>
164  * engine class follows these rules in order to instantiate a provider's
165  * implementation of <code>CipherSpi</code> for a
166  * transformation of the form "<i>algorithm</i>":
167  *
168  * <ol>
169  * <li>
170  * Check if the provider has registered a subclass of <code>CipherSpi</code>
171  * for the specified "<i>algorithm</i>".
172  * <p>If the answer is YES, instantiate this
173  * class, for whose mode and padding scheme default values (as supplied by
174  * the provider) are used.
175  * <p>If the answer is NO, throw a <code>NoSuchAlgorithmException</code>
176  * exception.
177  * </ol>
178  *
179  * <p>The <code>getInstance</code> factory method of the <code>Cipher</code>
180  * engine class follows these rules in order to instantiate a provider's
181  * implementation of <code>CipherSpi</code> for a
182  * transformation of the form "<i>algorithm/mode/padding</i>":
183  *
184  * <ol>
185  * <li>
186  * Check if the provider has registered a subclass of <code>CipherSpi</code>
187  * for the specified "<i>algorithm/mode/padding</i>" transformation.
188  * <p>If the answer is YES, instantiate it.
189  * <p>If the answer is NO, go to the next step.<p>
190  * <li>
191  * Check if the provider has registered a subclass of <code>CipherSpi</code>
192  * for the sub-transformation "<i>algorithm/mode</i>".
193  * <p>If the answer is YES, instantiate it, and call
194  * <code>engineSetPadding(<i>padding</i>)</code> on the new instance.
195  * <p>If the answer is NO, go to the next step.<p>
196  * <li>
197  * Check if the provider has registered a subclass of <code>CipherSpi</code>
198  * for the sub-transformation "<i>algorithm//padding</i>" (note the double
199  * slashes).
200  * <p>If the answer is YES, instantiate it, and call
201  * <code>engineSetMode(<i>mode</i>)</code> on the new instance.
202  * <p>If the answer is NO, go to the next step.<p>
203  * <li>
204  * Check if the provider has registered a subclass of <code>CipherSpi</code>
205  * for the sub-transformation "<i>algorithm</i>".
206  * <p>If the answer is YES, instantiate it, and call
207  * <code>engineSetMode(<i>mode</i>)</code> and
208  * <code>engineSetPadding(<i>padding</i>)</code> on the new instance.
209  * <p>If the answer is NO, throw a <code>NoSuchAlgorithmException</code>
210  * exception.
211  * </ol>
212  *
213  * @author Jan Luehe
214  *
215  * @version 1.25, 12/10/03
216  *
217  * @see KeyGenerator
218  * @see SecretKey
219  * @since 1.4
220  */
221 public abstract class CipherSpi
222 {
223
224     public CipherSpi() { }
225
226     /**
227      * Sets the mode of this cipher.
228      *
229      * @param mode the cipher mode
230      *
231      * @exception NoSuchAlgorithmException if the requested cipher mode does
232      * not exist
233      */
234     protected abstract void engineSetMode(String mode)
235         throws NoSuchAlgorithmException;
236
237     /**
238      * Sets the padding mechanism of this cipher.
239      *
240      * @param padding the padding mechanism
241      *
242      * @exception NoSuchPaddingException if the requested padding mechanism
243      * does not exist
244      */
245     protected abstract void engineSetPadding(String padding)
246         throws NoSuchPaddingException;
247
248     /**
249      * Returns the block size (in bytes).
250      *
251      * @return the block size (in bytes), or 0 if the underlying algorithm is
252      * not a block cipher
253      */
254     protected abstract int engineGetBlockSize();
255
256     /**
257      * Returns the length in bytes that an output buffer would
258      * need to be in order to hold the result of the next <code>update</code>
259      * or <code>doFinal</code> operation, given the input length
260      * <code>inputLen</code> (in bytes).
261      *
262      * <p>This call takes into account any unprocessed (buffered) data from a
263      * previous <code>update</code> call, and padding.
264      *
265      * <p>The actual output length of the next <code>update</code> or
266      * <code>doFinal</code> call may be smaller than the length returned by
267      * this method.
268      *
269      * @param inputLen the input length (in bytes)
270      *
271      * @return the required output buffer size (in bytes)
272      */
273     protected abstract int engineGetOutputSize(int inputLen);
274
275     /**
276      * Returns the initialization vector (IV) in a new buffer.
277      *
278      * <p> This is useful in the context of password-based encryption or
279      * decryption, where the IV is derived from a user-provided passphrase.
280      *
281      * @return the initialization vector in a new buffer, or null if the
282      * underlying algorithm does not use an IV, or if the IV has not yet
283      * been set.
284      */
285     protected abstract byte[] engineGetIV();
286
287     /**
288      * Returns the parameters used with this cipher.
289      *
290      * <p>The returned parameters may be the same that were used to initialize
291      * this cipher, or may contain a combination of default and random
292      * parameter values used by the underlying cipher implementation if this
293      * cipher requires algorithm parameters but was not initialized with any.
294      *
295      * @return the parameters used with this cipher, or null if this cipher
296      * does not use any parameters.
297      */
298     protected abstract AlgorithmParameters engineGetParameters();
299
300     /**
301      * Initializes this cipher with a key and a source
302      * of randomness.
303      *
304      * <p>The cipher is initialized for one of the following four operations:
305      * encryption, decryption, key wrapping or key unwrapping, depending on
306      * the value of <code>opmode</code>.
307      *
308      * <p>If this cipher requires any algorithm parameters that cannot be
309      * derived from the given <code>key</code>, the underlying cipher
310      * implementation is supposed to generate the required parameters itself
311      * (using provider-specific default or random values) if it is being
312      * initialized for encryption or key wrapping, and raise an
313      * <code>InvalidKeyException</code> if it is being
314      * initialized for decryption or key unwrapping.
315      * The generated parameters can be retrieved using
316      * {@link #engineGetParameters() engineGetParameters} or
317      * {@link #engineGetIV() engineGetIV} (if the parameter is an IV).
318      *
319      * <p>If this cipher (including its underlying feedback or padding scheme)
320      * requires any random bytes (e.g., for parameter generation), it will get
321      * them from <code>random</code>.
322      *
323      * <p>Note that when a Cipher object is initialized, it loses all
324      * previously-acquired state. In other words, initializing a Cipher is
325      * equivalent to creating a new instance of that Cipher and initializing
326      * it.
327      *
328      * @param opmode the operation mode of this cipher (this is one of
329      * the following:
330      * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>,
331      * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>)
332      * @param key the encryption key
333      * @param random the source of randomness
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.
339      */
340     protected abstract void engineInit(int opmode, Key key, SecureRandom random)
341         throws InvalidKeyException;
342
343     /**
344      * Initializes this cipher with a key, a set of
345      * algorithm parameters, 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 on
349      * the value of <code>opmode</code>.
350      *
351      * <p>If this cipher requires any algorithm parameters and
352      * <code>params</code> is null, the underlying cipher implementation is
353      * supposed to generate the required parameters itself (using
354      * provider-specific default or random values) if it is being
355      * initialized for encryption or key wrapping, and raise an
356      * <code>InvalidAlgorithmParameterException</code> if it is being
357      * initialized for decryption or key unwrapping.
358      * The generated parameters can be retrieved using
359      * {@link #engineGetParameters() engineGetParameters} or
360      * {@link #engineGetIV() engineGetIV} (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
372      * the 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 params the algorithm parameters
377      * @param random the source of randomness
378      *
379      * @exception InvalidKeyException if the given key is inappropriate for
380      * initializing this cipher
381      * @exception InvalidAlgorithmParameterException if the given algorithm
382      * parameters are inappropriate for this cipher,
383      * or if this cipher is being initialized for decryption and requires
384      * algorithm parameters and <code>params</code> is null.
385      */
386     protected abstract void engineInit(int opmode, Key key,
387         AlgorithmParameterSpec params, SecureRandom random)
388         throws InvalidKeyException, InvalidAlgorithmParameterException;
389
390     /**
391      * Initializes this cipher with a key, a set of
392      * algorithm parameters, and a source of randomness.
393      *
394      * <p>The cipher is initialized for one of the following four operations:
395      * encryption, decryption, key wrapping or key unwrapping, depending on
396      * the value of <code>opmode</code>.
397      *
398      * <p>If this cipher requires any algorithm parameters and
399      * <code>params</code> is null, the underlying cipher implementation is
400      * supposed to generate the required parameters itself (using
401      * provider-specific default or random values) if it is being
402      * initialized for encryption or key wrapping, and raise an
403      * <code>InvalidAlgorithmParameterException</code> if it is being
404      * initialized for decryption or key unwrapping.
405      * The generated parameters can be retrieved using
406      * {@link #engineGetParameters() engineGetParameters} or
407      * {@link #engineGetIV() engineGetIV} (if the parameter is an IV).
408      *
409      * <p>If this cipher (including its underlying feedback or padding scheme)
410      * requires any random bytes (e.g., for parameter generation), it will get
411      * them from <code>random</code>.
412      *
413      * <p>Note that when a Cipher object is initialized, it loses all
414      * previously-acquired state. In other words, initializing a Cipher is
415      * equivalent to creating a new instance of that Cipher and initializing
416      * it.
417      *
418      * @param opmode the operation mode of this cipher (this is one of
419      * the following:
420      * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>,
421      * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>)
422      * @param key the encryption key
423      * @param params the algorithm parameters
424      * @param random the source of randomness
425      *
426      * @exception InvalidKeyException if the given key is inappropriate for
427      * initializing this cipher
428      * @exception InvalidAlgorithmParameterException if the given algorithm
429      * parameters are inappropriate for this cipher,
430      * or if this cipher is being initialized for decryption and requires
431      * algorithm parameters and <code>params</code> is null.
432      */
433     protected abstract void engineInit(int opmode, Key key, AlgorithmParameters
434         params, SecureRandom random)
435         throws InvalidKeyException, InvalidAlgorithmParameterException;
436
437     /**
438      * Continues a multiple-part encryption or decryption operation
439      * (depending on how this cipher was initialized), processing another data
440      * part.
441      *
442      * <p>The first <code>inputLen</code> bytes in the <code>input</code>
443      * buffer, starting at <code>inputOffset</code> inclusive, are processed,
444      * and the result is stored in a new buffer.
445      *
446      * @param input the input buffer
447      * @param inputOffset the offset in <code>input</code> where the input
448      * starts
449      * @param inputLen the input length
450      *
451      * @return the new buffer with the result, or null if the underlying
452      * cipher is a block cipher and the input data is too short to result in a
453      * new block.
454      */
455     protected abstract byte[] engineUpdate(byte[] input, int inputOffset, int
456         inputLen);
457
458     /**
459      * Continues a multiple-part encryption or decryption operation
460      * (depending on how this cipher was initialized), processing another data
461      * part.
462      *
463      * <p>The first <code>inputLen</code> bytes in the <code>input</code>
464      * buffer, starting at <code>inputOffset</code> inclusive, are processed,
465      * and the result is stored in the <code>output</code> buffer, starting at
466      * <code>outputOffset</code> inclusive.
467      *
468      * <p>If the <code>output</code> buffer is too small to hold the result,
469      * a <code>ShortBufferException</code> is thrown.
470      *
471      * @param input the input buffer
472      * @param inputOffset the offset in <code>input</code> where the input
473      * starts
474      * @param inputLen the input length
475      * @param output the buffer for the result
476      * @param outputOffset the offset in <code>output</code> where the result
477      * is stored
478      *
479      * @return the number of bytes stored in <code>output</code>
480      *
481      * @exception ShortBufferException if the given output buffer is too small
482      * to hold the result
483      */
484     protected abstract int engineUpdate(byte[] input, int inputOffset, int
485         inputLen, byte[] output, int outputOffset) throws ShortBufferException;
486
487     /**
488      * Continues a multiple-part encryption or decryption operation
489      * (depending on how this cipher was initialized), processing another data
490      * part.
491      *
492      * <p>All <code>input.remaining()</code> bytes starting at
493      * <code>input.position()</code> are processed. The result is stored
494      * in the output buffer.
495      * Upon return, the input buffer's position will be equal
496      * to its limit; its limit will not have changed. The output buffer's
497      * position will have advanced by n, where n is the value returned
498      * by this method; the output buffer's limit will not have changed.
499      *
500      * <p>If <code>output.remaining()</code> bytes are insufficient to
501      * hold the result, a <code>ShortBufferException</code> is thrown.
502      *
503      * <p>Subclasses should consider overriding this method if they can
504      * process ByteBuffers more efficiently than byte arrays.
505      *
506      * @param input the input ByteBuffer
507      * @param output the output ByteByffer
508      *
509      * @return the number of bytes stored in <code>output</code>
510      *
511      * @exception ShortBufferException if there is insufficient space in the
512      * output buffer
513      *
514      * @throws NullPointerException if either parameter is <CODE>null</CODE>
515      * @since 1.5
516      */
517     protected int engineUpdate(ByteBuffer input, ByteBuffer output)
518         throws ShortBufferException
519     { }
520
521     /**
522      * Encrypts or decrypts data in a single-part operation,
523      * or finishes a multiple-part operation.
524      * The data is encrypted or decrypted, depending on how this cipher was
525      * initialized.
526      *
527      * <p>The first <code>inputLen</code> bytes in the <code>input</code>
528      * buffer, starting at <code>inputOffset</code> inclusive, and any input
529      * bytes that may have been buffered during a previous <code>update</code>
530      * operation, are processed, with padding (if requested) being applied.
531      * The result is stored in a new buffer.
532      *
533      * <p>Upon finishing, this method resets this cipher object to the state
534      * it was in when previously initialized via a call to
535      * <code>engineInit</code>.
536      * That is, the object is reset and available to encrypt or decrypt
537      * (depending on the operation mode that was specified in the call to
538      * <code>engineInit</code>) more data.
539      *
540      * <p>Note: if any exception is thrown, this cipher object may need to
541      * be reset before it can be used again.
542      *
543      * @param input the input buffer
544      * @param inputOffset the offset in <code>input</code> where the input
545      * starts
546      * @param inputLen the input length
547      *
548      * @return the new buffer with the result
549      *
550      * @exception IllegalBlockSizeException if this cipher is a block cipher,
551      * no padding has been requested (only in encryption mode), and the total
552      * input length of the data processed by this cipher is not a multiple of
553      * block size; or if this encryption algorithm is unable to
554      * process the input data provided.
555      * @exception BadPaddingException if this cipher is in decryption mode,
556      * and (un)padding has been requested, but the decrypted data is not
557      * bounded by the appropriate padding bytes
558      */
559     protected abstract byte[] engineDoFinal(byte[] input, int inputOffset, int
560         inputLen) throws IllegalBlockSizeException, BadPaddingException;
561
562     /**
563      * Encrypts or decrypts data in a single-part operation,
564      * or finishes a multiple-part operation.
565      * The data is encrypted or decrypted, depending on how this cipher was
566      * initialized.
567      *
568      * <p>The first <code>inputLen</code> bytes in the <code>input</code>
569      * buffer, starting at <code>inputOffset</code> inclusive, and any input
570      * bytes that may have been buffered during a previous <code>update</code>
571      * operation, are processed, with padding (if requested) being applied.
572      * The result is stored in the <code>output</code> buffer, starting at
573      * <code>outputOffset</code> inclusive.
574      *
575      * <p>If the <code>output</code> buffer is too small to hold the result,
576      * a <code>ShortBufferException</code> is thrown.
577      *
578      * <p>Upon finishing, this method resets this cipher object to the state
579      * it was in when previously initialized via a call to
580      * <code>engineInit</code>.
581      * That is, the object is reset and available to encrypt or decrypt
582      * (depending on the operation mode that was specified in the call to
583      * <code>engineInit</code>) more data.
584      *
585      * <p>Note: if any exception is thrown, this cipher object may need to
586      * be reset before it can be used again.
587      *
588      * @param input the input buffer
589      * @param inputOffset the offset in <code>input</code> where the input
590      * starts
591      * @param inputLen the input length
592      * @param output the buffer for the result
593      * @param outputOffset the offset in <code>output</code> where the result
594      * is stored
595      *
596      * @return the number of bytes stored in <code>output</code>
597      *
598      * @exception IllegalBlockSizeException if this cipher is a block cipher,
599      * no padding has been requested (only in encryption mode), and the total
600      * input length of the data processed by this cipher is not a multiple of
601      * block size; or if this encryption algorithm is unable to
602      * process the input data provided.
603      * @exception ShortBufferException if the given output buffer is too small
604      * to hold the result
605      * @exception BadPaddingException if this cipher is in decryption mode,
606      * and (un)padding has been requested, but the decrypted data is not
607      * bounded by the appropriate padding bytes
608      */
609     protected abstract int engineDoFinal(byte[] input, int inputOffset, int
610         inputLen, byte[] output, int outputOffset)
611         throws ShortBufferException, IllegalBlockSizeException,
612         BadPaddingException;
613
614     /**
615      * Encrypts or decrypts data in a single-part operation,
616      * or finishes a multiple-part operation.
617      * The data is encrypted or decrypted, depending on how this cipher was
618      * initialized.
619      *
620      * <p>All <code>input.remaining()</code> bytes starting at
621      * <code>input.position()</code> are processed. The result is stored
622      * in the output buffer.
623      * Upon return, the input buffer's position will be equal
624      * to its limit; its limit will not have changed. The output buffer's
625      * position will have advanced by n, where n is the value returned
626      * by this method; the output buffer's limit will not have changed.
627      *
628      * <p>If <code>output.remaining()</code> bytes are insufficient to
629      * hold the result, a <code>ShortBufferException</code> is thrown.
630      *
631      * <p>Upon finishing, this method resets this cipher object to the state
632      * it was in when previously initialized via a call to
633      * <code>engineInit</code>.
634      * That is, the object is reset and available to encrypt or decrypt
635      * (depending on the operation mode that was specified in the call to
636      * <code>engineInit</code>) more data.
637      *
638      * <p>Note: if any exception is thrown, this cipher object may need to
639      * be reset before it can be used again.
640      *
641      * <p>Subclasses should consider overriding this method if they can
642      * process ByteBuffers more efficiently than byte arrays.
643      *
644      * @param input the input ByteBuffer
645      * @param output the output ByteByffer
646      *
647      * @return the number of bytes stored in <code>output</code>
648      *
649      * @exception IllegalBlockSizeException if this cipher is a block cipher,
650      * no padding has been requested (only in encryption mode), and the total
651      * input length of the data processed by this cipher is not a multiple of
652      * block size; or if this encryption algorithm is unable to
653      * process the input data provided.
654      * @exception ShortBufferException if there is insufficient space in the
655      * output buffer
656      * @exception BadPaddingException if this cipher is in decryption mode,
657      * and (un)padding has been requested, but the decrypted data is not
658      * bounded by the appropriate padding bytes
659      *
660      * @throws NullPointerException if either parameter is <CODE>null</CODE>
661      * @since 1.5
662      */
663     protected int engineDoFinal(ByteBuffer input, ByteBuffer output)
664         throws ShortBufferException, IllegalBlockSizeException,
665         BadPaddingException
666     { }
667
668     /**
669      * Wrap a key.
670      *
671      * <p>This concrete method has been added to this previously-defined
672      * abstract class. (For backwards compatibility, it cannot be abstract.)
673      * It may be overridden by a provider to wrap a key.
674      * Such an override is expected to throw an IllegalBlockSizeException or
675      * InvalidKeyException (under the specified circumstances),
676      * if the given key cannot be wrapped.
677      * If this method is not overridden, it always throws an
678      * UnsupportedOperationException.
679      *
680      * @param key the key to be wrapped.
681      *
682      * @return the wrapped key.
683      *
684      * @exception IllegalBlockSizeException if this cipher is a block cipher,
685      * no padding has been requested, and the length of the encoding of the
686      * key to be wrapped is not a multiple of the block size.
687      *
688      * @exception InvalidKeyException if it is impossible or unsafe to
689      * wrap the key with this cipher (e.g., a hardware protected key is
690      * being passed to a software-only cipher).
691      */
692     protected byte[] engineWrap(Key key)
693         throws IllegalBlockSizeException, InvalidKeyException
694     { }
695
696     /**
697      * Unwrap a previously wrapped key.
698      *
699      * <p>This concrete method has been added to this previously-defined
700      * abstract class. (For backwards compatibility, it cannot be abstract.)
701      * It may be overridden by a provider to unwrap a previously wrapped key.
702      * Such an override is expected to throw an InvalidKeyException if
703      * the given wrapped key cannot be unwrapped.
704      * If this method is not overridden, it always throws an
705      * UnsupportedOperationException.
706      *
707      * @param wrappedKey the key to be unwrapped.
708      *
709      * @param wrappedKeyAlgorithm the algorithm associated with the wrapped
710      * key.
711      *
712      * @param wrappedKeyType the type of the wrapped key. This is one of
713      * <code>SECRET_KEY</code>, <code>PRIVATE_KEY</code>, or
714      * <code>PUBLIC_KEY</code>.
715      *
716      * @return the unwrapped key.
717      *
718      * @exception NoSuchAlgorithmException if no installed providers
719      * can create keys of type <code>wrappedKeyType</code> for the
720      * <code>wrappedKeyAlgorithm</code>.
721      *
722      * @exception InvalidKeyException if <code>wrappedKey</code> does not
723      * represent a wrapped key of type <code>wrappedKeyType</code> for
724      * the <code>wrappedKeyAlgorithm</code>.
725      */
726     protected Key engineUnwrap(byte[] wrappedKey, String wrappedKeyAlgorithm,
727         int wrappedKeyType) throws InvalidKeyException, NoSuchAlgorithmException
728     { }
729
730     /**
731      * Returns the key size of the given key object in bits.
732      * <p>This concrete method has been added to this previously-defined
733      * abstract class. It throws an <code>UnsupportedOperationException</code>
734      * if it is not overridden by the provider.
735      *
736      * @param key the key object.
737      *
738      * @return the key size of the given key object.
739      *
740      * @exception InvalidKeyException if <code>key</code> is invalid.
741      */
742     protected int engineGetKeySize(Key key) throws InvalidKeyException { }
743 }
744
Popular Tags