View Javadoc
1   /*
2    * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.crypto;
27  
28  import java.util.StringTokenizer;
29  import java.util.NoSuchElementException;
30  import java.security.AlgorithmParameters;
31  import java.security.Provider;
32  import java.security.Key;
33  import java.security.SecureRandom;
34  import java.security.NoSuchAlgorithmException;
35  import java.security.NoSuchProviderException;
36  import java.security.InvalidKeyException;
37  import java.security.InvalidAlgorithmParameterException;
38  import java.security.ProviderException;
39  import java.security.spec.AlgorithmParameterSpec;
40  
41  import java.nio.ByteBuffer;
42  
43  /**
44   * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
45   * for the <code>Cipher</code> class.
46   * All the abstract methods in this class must be implemented by each
47   * cryptographic service provider who wishes to supply the implementation
48   * of a particular cipher algorithm.
49   *
50   * <p>In order to create an instance of <code>Cipher</code>, which
51   * encapsulates an instance of this <code>CipherSpi</code> class, an
52   * application calls one of the
53   * {@link Cipher#getInstance(java.lang.String) getInstance}
54   * factory methods of the
55   * {@link Cipher Cipher} engine class and specifies the requested
56   * <i>transformation</i>.
57   * Optionally, the application may also specify the name of a provider.
58   *
59   * <p>A <i>transformation</i> is a string that describes the operation (or
60   * set of operations) to be performed on the given input, to produce some
61   * output. A transformation always includes the name of a cryptographic
62   * algorithm (e.g., <i>DES</i>), and may be followed by a feedback mode and
63   * padding scheme.
64   *
65   * <p> A transformation is of the form:
66   *
67   * <ul>
68   * <li>"<i>algorithm/mode/padding</i>" or
69   *
70   * <li>"<i>algorithm</i>"
71   * </ul>
72   *
73   * <P> (in the latter case,
74   * provider-specific default values for the mode and padding scheme are used).
75   * For example, the following is a valid transformation:
76   *
77   * <pre>
78   *     Cipher c = Cipher.getInstance("<i>DES/CBC/PKCS5Padding</i>");
79   * </pre>
80   *
81   * <p>A provider may supply a separate class for each combination
82   * of <i>algorithm/mode/padding</i>, or may decide to provide more generic
83   * classes representing sub-transformations corresponding to
84   * <i>algorithm</i> or <i>algorithm/mode</i> or <i>algorithm//padding</i>
85   * (note the double slashes),
86   * in which case the requested mode and/or padding are set automatically by
87   * the <code>getInstance</code> methods of <code>Cipher</code>, which invoke
88   * the {@link #engineSetMode(java.lang.String) engineSetMode} and
89   * {@link #engineSetPadding(java.lang.String) engineSetPadding}
90   * methods of the provider's subclass of <code>CipherSpi</code>.
91   *
92   * <p>A <code>Cipher</code> property in a provider master class may have one of
93   * the following formats:
94   *
95   * <ul>
96   *
97   * <li>
98   * <pre>
99   *     // provider's subclass of "CipherSpi" implements "algName" with
100  *     // pluggable mode and padding
101  *     <code>Cipher.</code><i>algName</i>
102  * </pre>
103  *
104  * <li>
105  * <pre>
106  *     // provider's subclass of "CipherSpi" implements "algName" in the
107  *     // specified "mode", with pluggable padding
108  *     <code>Cipher.</code><i>algName/mode</i>
109  * </pre>
110  *
111  * <li>
112  * <pre>
113  *     // provider's subclass of "CipherSpi" implements "algName" with the
114  *     // specified "padding", with pluggable mode
115  *     <code>Cipher.</code><i>algName//padding</i>
116  * </pre>
117  *
118  * <li>
119  * <pre>
120  *     // provider's subclass of "CipherSpi" implements "algName" with the
121  *     // specified "mode" and "padding"
122  *     <code>Cipher.</code><i>algName/mode/padding</i>
123  * </pre>
124  *
125  * </ul>
126  *
127  * <p>For example, a provider may supply a subclass of <code>CipherSpi</code>
128  * that implements <i>DES/ECB/PKCS5Padding</i>, one that implements
129  * <i>DES/CBC/PKCS5Padding</i>, one that implements
130  * <i>DES/CFB/PKCS5Padding</i>, and yet another one that implements
131  * <i>DES/OFB/PKCS5Padding</i>. That provider would have the following
132  * <code>Cipher</code> properties in its master class:
133  *
134  * <ul>
135  *
136  * <li>
137  * <pre>
138  *     <code>Cipher.</code><i>DES/ECB/PKCS5Padding</i>
139  * </pre>
140  *
141  * <li>
142  * <pre>
143  *     <code>Cipher.</code><i>DES/CBC/PKCS5Padding</i>
144  * </pre>
145  *
146  * <li>
147  * <pre>
148  *     <code>Cipher.</code><i>DES/CFB/PKCS5Padding</i>
149  * </pre>
150  *
151  * <li>
152  * <pre>
153  *     <code>Cipher.</code><i>DES/OFB/PKCS5Padding</i>
154  * </pre>
155  *
156  * </ul>
157  *
158  * <p>Another provider may implement a class for each of the above modes
159  * (i.e., one class for <i>ECB</i>, one for <i>CBC</i>, one for <i>CFB</i>,
160  * and one for <i>OFB</i>), one class for <i>PKCS5Padding</i>,
161  * and a generic <i>DES</i> class that subclasses from <code>CipherSpi</code>.
162  * That provider would have the following
163  * <code>Cipher</code> properties in its master class:
164  *
165  * <ul>
166  *
167  * <li>
168  * <pre>
169  *     <code>Cipher.</code><i>DES</i>
170  * </pre>
171  *
172  * </ul>
173  *
174  * <p>The <code>getInstance</code> factory method of the <code>Cipher</code>
175  * engine class follows these rules in order to instantiate a provider's
176  * implementation of <code>CipherSpi</code> for a
177  * transformation of the form "<i>algorithm</i>":
178  *
179  * <ol>
180  * <li>
181  * Check if the provider has registered a subclass of <code>CipherSpi</code>
182  * for the specified "<i>algorithm</i>".
183  * <p>If the answer is YES, instantiate this
184  * class, for whose mode and padding scheme default values (as supplied by
185  * the provider) are used.
186  * <p>If the answer is NO, throw a <code>NoSuchAlgorithmException</code>
187  * exception.
188  * </ol>
189  *
190  * <p>The <code>getInstance</code> factory method of the <code>Cipher</code>
191  * engine class follows these rules in order to instantiate a provider's
192  * implementation of <code>CipherSpi</code> for a
193  * transformation of the form "<i>algorithm/mode/padding</i>":
194  *
195  * <ol>
196  * <li>
197  * Check if the provider has registered a subclass of <code>CipherSpi</code>
198  * for the specified "<i>algorithm/mode/padding</i>" transformation.
199  * <p>If the answer is YES, instantiate it.
200  * <p>If the answer is NO, go to the next step.
201  * <li>
202  * Check if the provider has registered a subclass of <code>CipherSpi</code>
203  * for the sub-transformation "<i>algorithm/mode</i>".
204  * <p>If the answer is YES, instantiate it, and call
205  * <code>engineSetPadding(<i>padding</i>)</code> on the new instance.
206  * <p>If the answer is NO, go to the next step.
207  * <li>
208  * Check if the provider has registered a subclass of <code>CipherSpi</code>
209  * for the sub-transformation "<i>algorithm//padding</i>" (note the double
210  * slashes).
211  * <p>If the answer is YES, instantiate it, and call
212  * <code>engineSetMode(<i>mode</i>)</code> on the new instance.
213  * <p>If the answer is NO, go to the next step.
214  * <li>
215  * Check if the provider has registered a subclass of <code>CipherSpi</code>
216  * for the sub-transformation "<i>algorithm</i>".
217  * <p>If the answer is YES, instantiate it, and call
218  * <code>engineSetMode(<i>mode</i>)</code> and
219  * <code>engineSetPadding(<i>padding</i>)</code> on the new instance.
220  * <p>If the answer is NO, throw a <code>NoSuchAlgorithmException</code>
221  * exception.
222  * </ol>
223  *
224  * @author Jan Luehe
225  * @see KeyGenerator
226  * @see SecretKey
227  * @since 1.4
228  */
229 
230 public abstract class CipherSpi {
231 
232     /**
233      * Sets the mode of this cipher.
234      *
235      * @param mode the cipher mode
236      *
237      * @exception NoSuchAlgorithmException if the requested cipher mode does
238      * not exist
239      */
240     protected abstract void engineSetMode(String mode)
241         throws NoSuchAlgorithmException;
242 
243     /**
244      * Sets the padding mechanism of this cipher.
245      *
246      * @param padding the padding mechanism
247      *
248      * @exception NoSuchPaddingException if the requested padding mechanism
249      * does not exist
250      */
251     protected abstract void engineSetPadding(String padding)
252         throws NoSuchPaddingException;
253 
254     /**
255      * Returns the block size (in bytes).
256      *
257      * @return the block size (in bytes), or 0 if the underlying algorithm is
258      * not a block cipher
259      */
260     protected abstract int engineGetBlockSize();
261 
262     /**
263      * Returns the length in bytes that an output buffer would
264      * need to be in order to hold the result of the next <code>update</code>
265      * or <code>doFinal</code> operation, given the input length
266      * <code>inputLen</code> (in bytes).
267      *
268      * <p>This call takes into account any unprocessed (buffered) data from a
269      * previous <code>update</code> call, padding, and AEAD tagging.
270      *
271      * <p>The actual output length of the next <code>update</code> or
272      * <code>doFinal</code> call may be smaller than the length returned by
273      * this method.
274      *
275      * @param inputLen the input length (in bytes)
276      *
277      * @return the required output buffer size (in bytes)
278      */
279     protected abstract int engineGetOutputSize(int inputLen);
280 
281     /**
282      * Returns the initialization vector (IV) in a new buffer.
283      *
284      * <p> This is useful in the context of password-based encryption or
285      * decryption, where the IV is derived from a user-provided passphrase.
286      *
287      * @return the initialization vector in a new buffer, or null if the
288      * underlying algorithm does not use an IV, or if the IV has not yet
289      * been set.
290      */
291     protected abstract byte[] engineGetIV();
292 
293     /**
294      * Returns the parameters used with this cipher.
295      *
296      * <p>The returned parameters may be the same that were used to initialize
297      * this cipher, or may contain a combination of default and random
298      * parameter values used by the underlying cipher implementation if this
299      * cipher requires algorithm parameters but was not initialized with any.
300      *
301      * @return the parameters used with this cipher, or null if this cipher
302      * does not use any parameters.
303      */
304     protected abstract AlgorithmParameters engineGetParameters();
305 
306     /**
307      * Initializes this cipher with a key and a source
308      * of randomness.
309      *
310      * <p>The cipher is initialized for one of the following four operations:
311      * encryption, decryption, key wrapping or key unwrapping, depending on
312      * the value of <code>opmode</code>.
313      *
314      * <p>If this cipher requires any algorithm parameters that cannot be
315      * derived from the given <code>key</code>, the underlying cipher
316      * implementation is supposed to generate the required parameters itself
317      * (using provider-specific default or random values) if it is being
318      * initialized for encryption or key wrapping, and raise an
319      * <code>InvalidKeyException</code> if it is being
320      * initialized for decryption or key unwrapping.
321      * The generated parameters can be retrieved using
322      * {@link #engineGetParameters() engineGetParameters} or
323      * {@link #engineGetIV() engineGetIV} (if the parameter is an IV).
324      *
325      * <p>If this cipher requires algorithm parameters that cannot be
326      * derived from the input parameters, and there are no reasonable
327      * provider-specific default values, initialization will
328      * necessarily fail.
329      *
330      * <p>If this cipher (including its underlying feedback or padding scheme)
331      * requires any random bytes (e.g., for parameter generation), it will get
332      * them from <code>random</code>.
333      *
334      * <p>Note that when a Cipher object is initialized, it loses all
335      * previously-acquired state. In other words, initializing a Cipher is
336      * equivalent to creating a new instance of that Cipher and initializing
337      * it.
338      *
339      * @param opmode the operation mode of this cipher (this is one of
340      * the following:
341      * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>,
342      * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>)
343      * @param key the encryption key
344      * @param random the source of randomness
345      *
346      * @exception InvalidKeyException if the given key is inappropriate for
347      * initializing this cipher, or requires
348      * algorithm parameters that cannot be
349      * determined from the given key.
350      * @throws UnsupportedOperationException if {@code opmode} is
351      * {@code WRAP_MODE} or {@code UNWRAP_MODE} is not implemented
352      * by the cipher.
353      */
354     protected abstract void engineInit(int opmode, Key key,
355                                        SecureRandom random)
356         throws InvalidKeyException;
357 
358     /**
359      * Initializes this cipher with a key, a set of
360      * algorithm parameters, and a source of randomness.
361      *
362      * <p>The cipher is initialized for one of the following four operations:
363      * encryption, decryption, key wrapping or key unwrapping, depending on
364      * the value of <code>opmode</code>.
365      *
366      * <p>If this cipher requires any algorithm parameters and
367      * <code>params</code> is null, the underlying cipher implementation is
368      * supposed to generate the required parameters itself (using
369      * provider-specific default or random values) if it is being
370      * initialized for encryption or key wrapping, and raise an
371      * <code>InvalidAlgorithmParameterException</code> if it is being
372      * initialized for decryption or key unwrapping.
373      * The generated parameters can be retrieved using
374      * {@link #engineGetParameters() engineGetParameters} or
375      * {@link #engineGetIV() engineGetIV} (if the parameter is an IV).
376      *
377      * <p>If this cipher requires algorithm parameters that cannot be
378      * derived from the input parameters, and there are no reasonable
379      * provider-specific default values, initialization will
380      * necessarily fail.
381      *
382      * <p>If this cipher (including its underlying feedback or padding scheme)
383      * requires any random bytes (e.g., for parameter generation), it will get
384      * them from <code>random</code>.
385      *
386      * <p>Note that when a Cipher object is initialized, it loses all
387      * previously-acquired state. In other words, initializing a Cipher is
388      * equivalent to creating a new instance of that Cipher and initializing
389      * it.
390      *
391      * @param opmode the operation mode of this cipher (this is one of
392      * the following:
393      * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>,
394      * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>)
395      * @param key the encryption key
396      * @param params the algorithm parameters
397      * @param random the source of randomness
398      *
399      * @exception InvalidKeyException if the given key is inappropriate for
400      * initializing this cipher
401      * @exception InvalidAlgorithmParameterException if the given algorithm
402      * parameters are inappropriate for this cipher,
403      * or if this cipher requires
404      * algorithm parameters and <code>params</code> is null.
405      * @throws UnsupportedOperationException if {@code opmode} is
406      * {@code WRAP_MODE} or {@code UNWRAP_MODE} is not implemented
407      * by the cipher.
408      */
409     protected abstract void engineInit(int opmode, Key key,
410                                        AlgorithmParameterSpec params,
411                                        SecureRandom random)
412         throws InvalidKeyException, InvalidAlgorithmParameterException;
413 
414     /**
415      * Initializes this cipher with a key, a set of
416      * algorithm parameters, and a source of randomness.
417      *
418      * <p>The cipher is initialized for one of the following four operations:
419      * encryption, decryption, key wrapping or key unwrapping, depending on
420      * the value of <code>opmode</code>.
421      *
422      * <p>If this cipher requires any algorithm parameters and
423      * <code>params</code> is null, the underlying cipher implementation is
424      * supposed to generate the required parameters itself (using
425      * provider-specific default or random values) if it is being
426      * initialized for encryption or key wrapping, and raise an
427      * <code>InvalidAlgorithmParameterException</code> if it is being
428      * initialized for decryption or key unwrapping.
429      * The generated parameters can be retrieved using
430      * {@link #engineGetParameters() engineGetParameters} or
431      * {@link #engineGetIV() engineGetIV} (if the parameter is an IV).
432      *
433      * <p>If this cipher requires algorithm parameters that cannot be
434      * derived from the input parameters, and there are no reasonable
435      * provider-specific default values, initialization will
436      * necessarily fail.
437      *
438      * <p>If this cipher (including its underlying feedback or padding scheme)
439      * requires any random bytes (e.g., for parameter generation), it will get
440      * them from <code>random</code>.
441      *
442      * <p>Note that when a Cipher object is initialized, it loses all
443      * previously-acquired state. In other words, initializing a Cipher is
444      * equivalent to creating a new instance of that Cipher and initializing
445      * it.
446      *
447      * @param opmode the operation mode of this cipher (this is one of
448      * the following:
449      * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>,
450      * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>)
451      * @param key the encryption key
452      * @param params the algorithm parameters
453      * @param random the source of randomness
454      *
455      * @exception InvalidKeyException if the given key is inappropriate for
456      * initializing this cipher
457      * @exception InvalidAlgorithmParameterException if the given algorithm
458      * parameters are inappropriate for this cipher,
459      * or if this cipher requires
460      * algorithm parameters and <code>params</code> is null.
461      * @throws UnsupportedOperationException if {@code opmode} is
462      * {@code WRAP_MODE} or {@code UNWRAP_MODE} is not implemented
463      * by the cipher.
464      */
465     protected abstract void engineInit(int opmode, Key key,
466                                        AlgorithmParameters params,
467                                        SecureRandom random)
468         throws InvalidKeyException, InvalidAlgorithmParameterException;
469 
470     /**
471      * Continues a multiple-part encryption or decryption operation
472      * (depending on how this cipher was initialized), processing another data
473      * part.
474      *
475      * <p>The first <code>inputLen</code> bytes in the <code>input</code>
476      * buffer, starting at <code>inputOffset</code> inclusive, are processed,
477      * and the result is stored in a new buffer.
478      *
479      * @param input the input buffer
480      * @param inputOffset the offset in <code>input</code> where the input
481      * starts
482      * @param inputLen the input length
483      *
484      * @return the new buffer with the result, or null if the underlying
485      * cipher is a block cipher and the input data is too short to result in a
486      * new block.
487      */
488     protected abstract byte[] engineUpdate(byte[] input, int inputOffset,
489                                            int inputLen);
490 
491     /**
492      * Continues a multiple-part encryption or decryption operation
493      * (depending on how this cipher was initialized), processing another data
494      * part.
495      *
496      * <p>The first <code>inputLen</code> bytes in the <code>input</code>
497      * buffer, starting at <code>inputOffset</code> inclusive, are processed,
498      * and the result is stored in the <code>output</code> buffer, starting at
499      * <code>outputOffset</code> inclusive.
500      *
501      * <p>If the <code>output</code> buffer is too small to hold the result,
502      * a <code>ShortBufferException</code> is thrown.
503      *
504      * @param input the input buffer
505      * @param inputOffset the offset in <code>input</code> where the input
506      * starts
507      * @param inputLen the input length
508      * @param output the buffer for the result
509      * @param outputOffset the offset in <code>output</code> where the result
510      * is stored
511      *
512      * @return the number of bytes stored in <code>output</code>
513      *
514      * @exception ShortBufferException if the given output buffer is too small
515      * to hold the result
516      */
517     protected abstract int engineUpdate(byte[] input, int inputOffset,
518                                         int inputLen, byte[] output,
519                                         int outputOffset)
520         throws ShortBufferException;
521 
522     /**
523      * Continues a multiple-part encryption or decryption operation
524      * (depending on how this cipher was initialized), processing another data
525      * part.
526      *
527      * <p>All <code>input.remaining()</code> bytes starting at
528      * <code>input.position()</code> are processed. The result is stored
529      * in the output buffer.
530      * Upon return, the input buffer's position will be equal
531      * to its limit; its limit will not have changed. The output buffer's
532      * position will have advanced by n, where n is the value returned
533      * by this method; the output buffer's limit will not have changed.
534      *
535      * <p>If <code>output.remaining()</code> bytes are insufficient to
536      * hold the result, a <code>ShortBufferException</code> is thrown.
537      *
538      * <p>Subclasses should consider overriding this method if they can
539      * process ByteBuffers more efficiently than byte arrays.
540      *
541      * @param input the input ByteBuffer
542      * @param output the output ByteByffer
543      *
544      * @return the number of bytes stored in <code>output</code>
545      *
546      * @exception ShortBufferException if there is insufficient space in the
547      * output buffer
548      *
549      * @throws NullPointerException if either parameter is <CODE>null</CODE>
550      * @since 1.5
551      */
552     protected int engineUpdate(ByteBuffer input, ByteBuffer output)
553             throws ShortBufferException {
554         try {
555             return bufferCrypt(input, output, true);
556         } catch (IllegalBlockSizeException e) {
557             // never thrown for engineUpdate()
558             throw new ProviderException("Internal error in update()");
559         } catch (BadPaddingException e) {
560             // never thrown for engineUpdate()
561             throw new ProviderException("Internal error in update()");
562         }
563     }
564 
565     /**
566      * Encrypts or decrypts data in a single-part operation,
567      * or finishes a multiple-part operation.
568      * The data is encrypted or decrypted, depending on how this cipher was
569      * initialized.
570      *
571      * <p>The first <code>inputLen</code> bytes in the <code>input</code>
572      * buffer, starting at <code>inputOffset</code> inclusive, and any input
573      * bytes that may have been buffered during a previous <code>update</code>
574      * operation, are processed, with padding (if requested) being applied.
575      * If an AEAD mode such as GCM/CCM is being used, the authentication
576      * tag is appended in the case of encryption, or verified in the
577      * case of decryption.
578      * The result is stored in a new buffer.
579      *
580      * <p>Upon finishing, this method resets this cipher object to the state
581      * it was in when previously initialized via a call to
582      * <code>engineInit</code>.
583      * That is, the object is reset and available to encrypt or decrypt
584      * (depending on the operation mode that was specified in the call to
585      * <code>engineInit</code>) more data.
586      *
587      * <p>Note: if any exception is thrown, this cipher object may need to
588      * be reset before it can be used again.
589      *
590      * @param input the input buffer
591      * @param inputOffset the offset in <code>input</code> where the input
592      * starts
593      * @param inputLen the input length
594      *
595      * @return the new buffer with the result
596      *
597      * @exception IllegalBlockSizeException if this cipher is a block cipher,
598      * no padding has been requested (only in encryption mode), and the total
599      * input length of the data processed by this cipher is not a multiple of
600      * block size; or if this encryption algorithm is unable to
601      * process the input data provided.
602      * @exception BadPaddingException if this cipher is in decryption mode,
603      * and (un)padding has been requested, but the decrypted data is not
604      * bounded by the appropriate padding bytes
605      * @exception AEADBadTagException if this cipher is decrypting in an
606      * AEAD mode (such as GCM/CCM), and the received authentication tag
607      * does not match the calculated value
608      */
609     protected abstract byte[] engineDoFinal(byte[] input, int inputOffset,
610                                             int inputLen)
611         throws IllegalBlockSizeException, BadPaddingException;
612 
613     /**
614      * Encrypts or decrypts data in a single-part operation,
615      * or finishes a multiple-part operation.
616      * The data is encrypted or decrypted, depending on how this cipher was
617      * initialized.
618      *
619      * <p>The first <code>inputLen</code> bytes in the <code>input</code>
620      * buffer, starting at <code>inputOffset</code> inclusive, and any input
621      * bytes that may have been buffered during a previous <code>update</code>
622      * operation, are processed, with padding (if requested) being applied.
623      * If an AEAD mode such as GCM/CCM is being used, the authentication
624      * tag is appended in the case of encryption, or verified in the
625      * case of decryption.
626      * The result is stored in the <code>output</code> buffer, starting at
627      * <code>outputOffset</code> inclusive.
628      *
629      * <p>If the <code>output</code> buffer is too small to hold the result,
630      * a <code>ShortBufferException</code> is thrown.
631      *
632      * <p>Upon finishing, this method resets this cipher object to the state
633      * it was in when previously initialized via a call to
634      * <code>engineInit</code>.
635      * That is, the object is reset and available to encrypt or decrypt
636      * (depending on the operation mode that was specified in the call to
637      * <code>engineInit</code>) more data.
638      *
639      * <p>Note: if any exception is thrown, this cipher object may need to
640      * be reset before it can be used again.
641      *
642      * @param input the input buffer
643      * @param inputOffset the offset in <code>input</code> where the input
644      * starts
645      * @param inputLen the input length
646      * @param output the buffer for the result
647      * @param outputOffset the offset in <code>output</code> where the result
648      * is stored
649      *
650      * @return the number of bytes stored in <code>output</code>
651      *
652      * @exception IllegalBlockSizeException if this cipher is a block cipher,
653      * no padding has been requested (only in encryption mode), and the total
654      * input length of the data processed by this cipher is not a multiple of
655      * block size; or if this encryption algorithm is unable to
656      * process the input data provided.
657      * @exception ShortBufferException if the given output buffer is too small
658      * to hold the result
659      * @exception BadPaddingException if this cipher is in decryption mode,
660      * and (un)padding has been requested, but the decrypted data is not
661      * bounded by the appropriate padding bytes
662      * @exception AEADBadTagException if this cipher is decrypting in an
663      * AEAD mode (such as GCM/CCM), and the received authentication tag
664      * does not match the calculated value
665      */
666     protected abstract int engineDoFinal(byte[] input, int inputOffset,
667                                          int inputLen, byte[] output,
668                                          int outputOffset)
669         throws ShortBufferException, IllegalBlockSizeException,
670                BadPaddingException;
671 
672     /**
673      * Encrypts or decrypts data in a single-part operation,
674      * or finishes a multiple-part operation.
675      * The data is encrypted or decrypted, depending on how this cipher was
676      * initialized.
677      *
678      * <p>All <code>input.remaining()</code> bytes starting at
679      * <code>input.position()</code> are processed.
680      * If an AEAD mode such as GCM/CCM is being used, the authentication
681      * tag is appended in the case of encryption, or verified in the
682      * case of decryption.
683      * The result is stored in the output buffer.
684      * Upon return, the input buffer's position will be equal
685      * to its limit; its limit will not have changed. The output buffer's
686      * position will have advanced by n, where n is the value returned
687      * by this method; the output buffer's limit will not have changed.
688      *
689      * <p>If <code>output.remaining()</code> bytes are insufficient to
690      * hold the result, a <code>ShortBufferException</code> is thrown.
691      *
692      * <p>Upon finishing, this method resets this cipher object to the state
693      * it was in when previously initialized via a call to
694      * <code>engineInit</code>.
695      * That is, the object is reset and available to encrypt or decrypt
696      * (depending on the operation mode that was specified in the call to
697      * <code>engineInit</code>) more data.
698      *
699      * <p>Note: if any exception is thrown, this cipher object may need to
700      * be reset before it can be used again.
701      *
702      * <p>Subclasses should consider overriding this method if they can
703      * process ByteBuffers more efficiently than byte arrays.
704      *
705      * @param input the input ByteBuffer
706      * @param output the output ByteByffer
707      *
708      * @return the number of bytes stored in <code>output</code>
709      *
710      * @exception IllegalBlockSizeException if this cipher is a block cipher,
711      * no padding has been requested (only in encryption mode), and the total
712      * input length of the data processed by this cipher is not a multiple of
713      * block size; or if this encryption algorithm is unable to
714      * process the input data provided.
715      * @exception ShortBufferException if there is insufficient space in the
716      * output buffer
717      * @exception BadPaddingException if this cipher is in decryption mode,
718      * and (un)padding has been requested, but the decrypted data is not
719      * bounded by the appropriate padding bytes
720      * @exception AEADBadTagException if this cipher is decrypting in an
721      * AEAD mode (such as GCM/CCM), and the received authentication tag
722      * does not match the calculated value
723      *
724      * @throws NullPointerException if either parameter is <CODE>null</CODE>
725      * @since 1.5
726      */
727     protected int engineDoFinal(ByteBuffer input, ByteBuffer output)
728             throws ShortBufferException, IllegalBlockSizeException,
729             BadPaddingException {
730         return bufferCrypt(input, output, false);
731     }
732 
733     // copied from sun.security.jca.JCAUtil
734     // will be changed to reference that method once that code has been
735     // integrated and promoted
736     static int getTempArraySize(int totalSize) {
737         return Math.min(4096, totalSize);
738     }
739 
740     /**
741      * Implementation for encryption using ByteBuffers. Used for both
742      * engineUpdate() and engineDoFinal().
743      */
744     private int bufferCrypt(ByteBuffer input, ByteBuffer output,
745             boolean isUpdate) throws ShortBufferException,
746             IllegalBlockSizeException, BadPaddingException {
747         if ((input == null) || (output == null)) {
748             throw new NullPointerException
749                 ("Input and output buffers must not be null");
750         }
751         int inPos = input.position();
752         int inLimit = input.limit();
753         int inLen = inLimit - inPos;
754         if (isUpdate && (inLen == 0)) {
755             return 0;
756         }
757         int outLenNeeded = engineGetOutputSize(inLen);
758         if (output.remaining() < outLenNeeded) {
759             throw new ShortBufferException("Need at least " + outLenNeeded
760                 + " bytes of space in output buffer");
761         }
762 
763         boolean a1 = input.hasArray();
764         boolean a2 = output.hasArray();
765 
766         if (a1 && a2) {
767             byte[] inArray = input.array();
768             int inOfs = input.arrayOffset() + inPos;
769             byte[] outArray = output.array();
770             int outPos = output.position();
771             int outOfs = output.arrayOffset() + outPos;
772             int n;
773             if (isUpdate) {
774                 n = engineUpdate(inArray, inOfs, inLen, outArray, outOfs);
775             } else {
776                 n = engineDoFinal(inArray, inOfs, inLen, outArray, outOfs);
777             }
778             input.position(inLimit);
779             output.position(outPos + n);
780             return n;
781         } else if (!a1 && a2) {
782             int outPos = output.position();
783             byte[] outArray = output.array();
784             int outOfs = output.arrayOffset() + outPos;
785             byte[] inArray = new byte[getTempArraySize(inLen)];
786             int total = 0;
787             do {
788                 int chunk = Math.min(inLen, inArray.length);
789                 if (chunk > 0) {
790                     input.get(inArray, 0, chunk);
791                 }
792                 int n;
793                 if (isUpdate || (inLen != chunk)) {
794                     n = engineUpdate(inArray, 0, chunk, outArray, outOfs);
795                 } else {
796                     n = engineDoFinal(inArray, 0, chunk, outArray, outOfs);
797                 }
798                 total += n;
799                 outOfs += n;
800                 inLen -= chunk;
801             } while (inLen > 0);
802             output.position(outPos + total);
803             return total;
804         } else { // output is not backed by an accessible byte[]
805             byte[] inArray;
806             int inOfs;
807             if (a1) {
808                 inArray = input.array();
809                 inOfs = input.arrayOffset() + inPos;
810             } else {
811                 inArray = new byte[getTempArraySize(inLen)];
812                 inOfs = 0;
813             }
814             byte[] outArray = new byte[getTempArraySize(outLenNeeded)];
815             int outSize = outArray.length;
816             int total = 0;
817             boolean resized = false;
818             do {
819                 int chunk =
820                     Math.min(inLen, (outSize == 0? inArray.length : outSize));
821                 if (!a1 && !resized && chunk > 0) {
822                     input.get(inArray, 0, chunk);
823                     inOfs = 0;
824                 }
825                 try {
826                     int n;
827                     if (isUpdate || (inLen != chunk)) {
828                         n = engineUpdate(inArray, inOfs, chunk, outArray, 0);
829                     } else {
830                         n = engineDoFinal(inArray, inOfs, chunk, outArray, 0);
831                     }
832                     resized = false;
833                     inOfs += chunk;
834                     inLen -= chunk;
835                     if (n > 0) {
836                         output.put(outArray, 0, n);
837                         total += n;
838                     }
839                 } catch (ShortBufferException e) {
840                     if (resized) {
841                         // we just resized the output buffer, but it still
842                         // did not work. Bug in the provider, abort
843                         throw (ProviderException)new ProviderException
844                             ("Could not determine buffer size").initCause(e);
845                     }
846                     // output buffer is too small, realloc and try again
847                     resized = true;
848                     outSize = engineGetOutputSize(chunk);
849                     outArray = new byte[outSize];
850                 }
851             } while (inLen > 0);
852             if (a1) {
853                 input.position(inLimit);
854             }
855             return total;
856         }
857     }
858 
859     /**
860      * Wrap a key.
861      *
862      * <p>This concrete method has been added to this previously-defined
863      * abstract class. (For backwards compatibility, it cannot be abstract.)
864      * It may be overridden by a provider to wrap a key.
865      * Such an override is expected to throw an IllegalBlockSizeException or
866      * InvalidKeyException (under the specified circumstances),
867      * if the given key cannot be wrapped.
868      * If this method is not overridden, it always throws an
869      * UnsupportedOperationException.
870      *
871      * @param key the key to be wrapped.
872      *
873      * @return the wrapped key.
874      *
875      * @exception IllegalBlockSizeException if this cipher is a block cipher,
876      * no padding has been requested, and the length of the encoding of the
877      * key to be wrapped is not a multiple of the block size.
878      *
879      * @exception InvalidKeyException if it is impossible or unsafe to
880      * wrap the key with this cipher (e.g., a hardware protected key is
881      * being passed to a software-only cipher).
882      *
883      * @throws UnsupportedOperationException if this method is not supported.
884      */
885     protected byte[] engineWrap(Key key)
886         throws IllegalBlockSizeException, InvalidKeyException
887     {
888         throw new UnsupportedOperationException();
889     }
890 
891     /**
892      * Unwrap a previously wrapped key.
893      *
894      * <p>This concrete method has been added to this previously-defined
895      * abstract class. (For backwards compatibility, it cannot be abstract.)
896      * It may be overridden by a provider to unwrap a previously wrapped key.
897      * Such an override is expected to throw an InvalidKeyException if
898      * the given wrapped key cannot be unwrapped.
899      * If this method is not overridden, it always throws an
900      * UnsupportedOperationException.
901      *
902      * @param wrappedKey the key to be unwrapped.
903      *
904      * @param wrappedKeyAlgorithm the algorithm associated with the wrapped
905      * key.
906      *
907      * @param wrappedKeyType the type of the wrapped key. This is one of
908      * <code>SECRET_KEY</code>, <code>PRIVATE_KEY</code>, or
909      * <code>PUBLIC_KEY</code>.
910      *
911      * @return the unwrapped key.
912      *
913      * @exception NoSuchAlgorithmException if no installed providers
914      * can create keys of type <code>wrappedKeyType</code> for the
915      * <code>wrappedKeyAlgorithm</code>.
916      *
917      * @exception InvalidKeyException if <code>wrappedKey</code> does not
918      * represent a wrapped key of type <code>wrappedKeyType</code> for
919      * the <code>wrappedKeyAlgorithm</code>.
920      *
921      * @throws UnsupportedOperationException if this method is not supported.
922      */
923     protected Key engineUnwrap(byte[] wrappedKey,
924                                String wrappedKeyAlgorithm,
925                                int wrappedKeyType)
926         throws InvalidKeyException, NoSuchAlgorithmException
927     {
928         throw new UnsupportedOperationException();
929     }
930 
931     /**
932      * Returns the key size of the given key object in bits.
933      * <p>This concrete method has been added to this previously-defined
934      * abstract class. It throws an <code>UnsupportedOperationException</code>
935      * if it is not overridden by the provider.
936      *
937      * @param key the key object.
938      *
939      * @return the key size of the given key object.
940      *
941      * @exception InvalidKeyException if <code>key</code> is invalid.
942      */
943     protected int engineGetKeySize(Key key)
944         throws InvalidKeyException
945     {
946         throw new UnsupportedOperationException();
947     }
948 
949     /**
950      * Continues a multi-part update of the Additional Authentication
951      * Data (AAD), using a subset of the provided buffer.
952      * <p>
953      * Calls to this method provide AAD to the cipher when operating in
954      * modes such as AEAD (GCM/CCM).  If this cipher is operating in
955      * either GCM or CCM mode, all AAD must be supplied before beginning
956      * operations on the ciphertext (via the {@code update} and {@code
957      * doFinal} methods).
958      *
959      * @param src the buffer containing the AAD
960      * @param offset the offset in {@code src} where the AAD input starts
961      * @param len the number of AAD bytes
962      *
963      * @throws IllegalStateException if this cipher is in a wrong state
964      * (e.g., has not been initialized), does not accept AAD, or if
965      * operating in either GCM or CCM mode and one of the {@code update}
966      * methods has already been called for the active
967      * encryption/decryption operation
968      * @throws UnsupportedOperationException if this method
969      * has not been overridden by an implementation
970      *
971      * @since 1.7
972      */
973     protected void engineUpdateAAD(byte[] src, int offset, int len) {
974         throw new UnsupportedOperationException(
975             "The underlying Cipher implementation "
976             +  "does not support this method");
977     }
978 
979     /**
980      * Continues a multi-part update of the Additional Authentication
981      * Data (AAD).
982      * <p>
983      * Calls to this method provide AAD to the cipher when operating in
984      * modes such as AEAD (GCM/CCM).  If this cipher is operating in
985      * either GCM or CCM mode, all AAD must be supplied before beginning
986      * operations on the ciphertext (via the {@code update} and {@code
987      * doFinal} methods).
988      * <p>
989      * All {@code src.remaining()} bytes starting at
990      * {@code src.position()} are processed.
991      * Upon return, the input buffer's position will be equal
992      * to its limit; its limit will not have changed.
993      *
994      * @param src the buffer containing the AAD
995      *
996      * @throws IllegalStateException if this cipher is in a wrong state
997      * (e.g., has not been initialized), does not accept AAD, or if
998      * operating in either GCM or CCM mode and one of the {@code update}
999      * methods has already been called for the active
1000      * encryption/decryption operation
1001      * @throws UnsupportedOperationException if this method
1002      * has not been overridden by an implementation
1003      *
1004      * @since 1.7
1005      */
1006     protected void engineUpdateAAD(ByteBuffer src) {
1007         throw new UnsupportedOperationException(
1008             "The underlying Cipher implementation "
1009             +  "does not support this method");
1010     }
1011 }