Save This Page
Home » openjdk-7 » com.sun.crypto » provider » [javadoc | source]
    1   /*
    2    * Copyright (c) 2002, 2009, 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 com.sun.crypto.provider;
   27   
   28   import java.security;
   29   import java.security.spec;
   30   import javax.crypto;
   31   import javax.crypto.spec;
   32   import javax.crypto.BadPaddingException;
   33   
   34   /**
   35    * This class implements the AES algorithm in its various modes
   36    * (<code>ECB</code>, <code>CFB</code>, <code>OFB</code>, <code>CBC</code>,
   37    * <code>PCBC</code>) and padding schemes (<code>PKCS5Padding</code>,
   38    * <code>NoPadding</code>, <code>ISO10126Padding</code>).
   39    *
   40    * @author Valerie Peng
   41    *
   42    *
   43    * @see AESCrypt
   44    * @see CipherBlockChaining
   45    * @see ElectronicCodeBook
   46    * @see CipherFeedback
   47    * @see OutputFeedback
   48    */
   49   
   50   public final class AESCipher extends CipherSpi {
   51       /*
   52        * internal CipherCore object which does the real work.
   53        */
   54       private CipherCore core = null;
   55   
   56       /**
   57        * Creates an instance of AES cipher with default ECB mode and
   58        * PKCS5Padding.
   59        */
   60       public AESCipher() {
   61           core = new CipherCore(new AESCrypt(), AESConstants.AES_BLOCK_SIZE);
   62       }
   63   
   64       /**
   65        * Sets the mode of this cipher.
   66        *
   67        * @param mode the cipher mode
   68        *
   69        * @exception NoSuchAlgorithmException if the requested cipher mode does
   70        * not exist
   71        */
   72       protected void engineSetMode(String mode)
   73           throws NoSuchAlgorithmException {
   74           core.setMode(mode);
   75       }
   76   
   77       /**
   78        * Sets the padding mechanism of this cipher.
   79        *
   80        * @param padding the padding mechanism
   81        *
   82        * @exception NoSuchPaddingException if the requested padding mechanism
   83        * does not exist
   84        */
   85       protected void engineSetPadding(String paddingScheme)
   86           throws NoSuchPaddingException {
   87           core.setPadding(paddingScheme);
   88       }
   89   
   90       /**
   91        * Returns the block size (in bytes).
   92        *
   93        * @return the block size (in bytes), or 0 if the underlying algorithm is
   94        * not a block cipher
   95        */
   96       protected int engineGetBlockSize() {
   97           return AESConstants.AES_BLOCK_SIZE;
   98       }
   99   
  100       /**
  101        * Returns the length in bytes that an output buffer would need to be in
  102        * order to hold the result of the next <code>update</code> or
  103        * <code>doFinal</code> operation, given the input length
  104        * <code>inputLen</code> (in bytes).
  105        *
  106        * <p>This call takes into account any unprocessed (buffered) data from a
  107        * previous <code>update</code> call, and padding.
  108        *
  109        * <p>The actual output length of the next <code>update</code> or
  110        * <code>doFinal</code> call may be smaller than the length returned by
  111        * this method.
  112        *
  113        * @param inputLen the input length (in bytes)
  114        *
  115        * @return the required output buffer size (in bytes)
  116        */
  117       protected int engineGetOutputSize(int inputLen) {
  118           return core.getOutputSize(inputLen);
  119       }
  120   
  121       /**
  122        * Returns the initialization vector (IV) in a new buffer.
  123        *
  124        * <p>This is useful in the case where a random IV has been created
  125        * (see <a href = "#init">init</a>),
  126        * or in the context of password-based encryption or
  127        * decryption, where the IV is derived from a user-provided password.
  128        *
  129        * @return the initialization vector in a new buffer, or null if the
  130        * underlying algorithm does not use an IV, or if the IV has not yet
  131        * been set.
  132        */
  133       protected byte[] engineGetIV() {
  134           return core.getIV();
  135       }
  136   
  137       /**
  138        * Returns the parameters used with this cipher.
  139        *
  140        * <p>The returned parameters may be the same that were used to initialize
  141        * this cipher, or may contain the default set of parameters or a set of
  142        * randomly generated parameters used by the underlying cipher
  143        * implementation (provided that the underlying cipher implementation
  144        * uses a default set of parameters or creates new parameters if it needs
  145        * parameters but was not initialized with any).
  146        *
  147        * @return the parameters used with this cipher, or null if this cipher
  148        * does not use any parameters.
  149        */
  150       protected AlgorithmParameters engineGetParameters() {
  151           return core.getParameters("AES");
  152       }
  153   
  154       /**
  155        * Initializes this cipher with a key and a source of randomness.
  156        *
  157        * <p>The cipher is initialized for one of the following four operations:
  158        * encryption, decryption, key wrapping or key unwrapping, depending on
  159        * the value of <code>opmode</code>.
  160        *
  161        * <p>If this cipher requires an initialization vector (IV), it will get
  162        * it from <code>random</code>.
  163        * This behaviour should only be used in encryption or key wrapping
  164        * mode, however.
  165        * When initializing a cipher that requires an IV for decryption or
  166        * key unwrapping, the IV
  167        * (same IV that was used for encryption or key wrapping) must be provided
  168        * explicitly as a
  169        * parameter, in order to get the correct result.
  170        *
  171        * <p>This method also cleans existing buffer and other related state
  172        * information.
  173        *
  174        * @param opmode the operation mode of this cipher (this is one of
  175        * the following:
  176        * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>,
  177        * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>)
  178        * @param key the secret key
  179        * @param random the source of randomness
  180        *
  181        * @exception InvalidKeyException if the given key is inappropriate for
  182        * initializing this cipher
  183        */
  184       protected void engineInit(int opmode, Key key, SecureRandom random)
  185           throws InvalidKeyException {
  186           core.init(opmode, key, random);
  187       }
  188   
  189       /**
  190        * Initializes this cipher with a key, a set of
  191        * algorithm parameters, and a source of randomness.
  192        *
  193        * <p>The cipher is initialized for one of the following four operations:
  194        * encryption, decryption, key wrapping or key unwrapping, depending on
  195        * the value of <code>opmode</code>.
  196        *
  197        * <p>If this cipher (including its underlying feedback or padding scheme)
  198        * requires any random bytes, it will get them from <code>random</code>.
  199        *
  200        * @param opmode the operation mode of this cipher (this is one of
  201        * the following:
  202        * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>,
  203        * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>)
  204        * @param key the encryption key
  205        * @param params the algorithm parameters
  206        * @param random the source of randomness
  207        *
  208        * @exception InvalidKeyException if the given key is inappropriate for
  209        * initializing this cipher
  210        * @exception InvalidAlgorithmParameterException if the given algorithm
  211        * parameters are inappropriate for this cipher
  212        */
  213       protected void engineInit(int opmode, Key key,
  214                                 AlgorithmParameterSpec params,
  215                                 SecureRandom random)
  216           throws InvalidKeyException, InvalidAlgorithmParameterException {
  217           core.init(opmode, key, params, random);
  218       }
  219   
  220       protected void engineInit(int opmode, Key key,
  221                                 AlgorithmParameters params,
  222                                 SecureRandom random)
  223           throws InvalidKeyException, InvalidAlgorithmParameterException {
  224           core.init(opmode, key, params, random);
  225       }
  226   
  227       /**
  228        * Continues a multiple-part encryption or decryption operation
  229        * (depending on how this cipher was initialized), processing another data
  230        * part.
  231        *
  232        * <p>The first <code>inputLen</code> bytes in the <code>input</code>
  233        * buffer, starting at <code>inputOffset</code>, are processed, and the
  234        * result is stored in a new buffer.
  235        *
  236        * @param input the input buffer
  237        * @param inputOffset the offset in <code>input</code> where the input
  238        * starts
  239        * @param inputLen the input length
  240        *
  241        * @return the new buffer with the result
  242        *
  243        * @exception IllegalStateException if this cipher is in a wrong state
  244        * (e.g., has not been initialized)
  245        */
  246       protected byte[] engineUpdate(byte[] input, int inputOffset,
  247                                     int inputLen) {
  248           return core.update(input, inputOffset, inputLen);
  249       }
  250   
  251       /**
  252        * Continues a multiple-part encryption or decryption operation
  253        * (depending on how this cipher was initialized), processing another data
  254        * part.
  255        *
  256        * <p>The first <code>inputLen</code> bytes in the <code>input</code>
  257        * buffer, starting at <code>inputOffset</code>, are processed, and the
  258        * result is stored in the <code>output</code> buffer, starting at
  259        * <code>outputOffset</code>.
  260        *
  261        * @param input the input buffer
  262        * @param inputOffset the offset in <code>input</code> where the input
  263        * starts
  264        * @param inputLen the input length
  265        * @param output the buffer for the result
  266        * @param outputOffset the offset in <code>output</code> where the result
  267        * is stored
  268        *
  269        * @return the number of bytes stored in <code>output</code>
  270        *
  271        * @exception ShortBufferException if the given output buffer is too small
  272        * to hold the result
  273        */
  274       protected int engineUpdate(byte[] input, int inputOffset, int inputLen,
  275                                  byte[] output, int outputOffset)
  276           throws ShortBufferException {
  277           return core.update(input, inputOffset, inputLen, output,
  278                              outputOffset);
  279       }
  280   
  281       /**
  282        * Encrypts or decrypts data in a single-part operation,
  283        * or finishes a multiple-part operation.
  284        * The data is encrypted or decrypted, depending on how this cipher was
  285        * initialized.
  286        *
  287        * <p>The first <code>inputLen</code> bytes in the <code>input</code>
  288        * buffer, starting at <code>inputOffset</code>, and any input bytes that
  289        * may have been buffered during a previous <code>update</code> operation,
  290        * are processed, with padding (if requested) being applied.
  291        * The result is stored in a new buffer.
  292        *
  293        * <p>The cipher is reset to its initial state (uninitialized) after this
  294        * call.
  295        *
  296        * @param input the input buffer
  297        * @param inputOffset the offset in <code>input</code> where the input
  298        * starts
  299        * @param inputLen the input length
  300        *
  301        * @return the new buffer with the result
  302        *
  303        * @exception IllegalBlockSizeException if this cipher is a block cipher,
  304        * no padding has been requested (only in encryption mode), and the total
  305        * input length of the data processed by this cipher is not a multiple of
  306        * block size
  307        * @exception BadPaddingException if this cipher is in decryption mode,
  308        * and (un)padding has been requested, but the decrypted data is not
  309        * bounded by the appropriate padding bytes
  310        */
  311       protected byte[] engineDoFinal(byte[] input, int inputOffset, int inputLen)
  312           throws IllegalBlockSizeException, BadPaddingException {
  313           return core.doFinal(input, inputOffset, inputLen);
  314       }
  315   
  316       /**
  317        * Encrypts or decrypts data in a single-part operation,
  318        * or finishes a multiple-part operation.
  319        * The data is encrypted or decrypted, depending on how this cipher was
  320        * initialized.
  321        *
  322        * <p>The first <code>inputLen</code> bytes in the <code>input</code>
  323        * buffer, starting at <code>inputOffset</code>, and any input bytes that
  324        * may have been buffered during a previous <code>update</code> operation,
  325        * are processed, with padding (if requested) being applied.
  326        * The result is stored in the <code>output</code> buffer, starting at
  327        * <code>outputOffset</code>.
  328        *
  329        * <p>The cipher is reset to its initial state (uninitialized) after this
  330        * call.
  331        *
  332        * @param input the input buffer
  333        * @param inputOffset the offset in <code>input</code> where the input
  334        * starts
  335        * @param inputLen the input length
  336        * @param output the buffer for the result
  337        * @param outputOffset the offset in <code>output</code> where the result
  338        * is stored
  339        *
  340        * @return the number of bytes stored in <code>output</code>
  341        *
  342        * @exception IllegalBlockSizeException if this cipher is a block cipher,
  343        * no padding has been requested (only in encryption mode), and the total
  344        * input length of the data processed by this cipher is not a multiple of
  345        * block size
  346        * @exception ShortBufferException if the given output buffer is too small
  347        * to hold the result
  348        * @exception BadPaddingException if this cipher is in decryption mode,
  349        * and (un)padding has been requested, but the decrypted data is not
  350        * bounded by the appropriate padding bytes
  351        */
  352       protected int engineDoFinal(byte[] input, int inputOffset, int inputLen,
  353                                   byte[] output, int outputOffset)
  354           throws IllegalBlockSizeException, ShortBufferException,
  355                  BadPaddingException {
  356           return core.doFinal(input, inputOffset, inputLen, output,
  357                               outputOffset);
  358       }
  359   
  360       /**
  361        *  Returns the key size of the given key object.
  362        *
  363        * @param key the key object.
  364        *
  365        * @return the key size of the given key object.
  366        *
  367        * @exception InvalidKeyException if <code>key</code> is invalid.
  368        */
  369       protected int engineGetKeySize(Key key) throws InvalidKeyException {
  370           byte[] encoded = key.getEncoded();
  371           if (!AESCrypt.isKeySizeValid(encoded.length)) {
  372               throw new InvalidKeyException("Invalid AES key length: " +
  373                                             encoded.length + " bytes");
  374           }
  375           return encoded.length * 8;
  376       }
  377   
  378       /**
  379        * Wrap a key.
  380        *
  381        * @param key the key to be wrapped.
  382        *
  383        * @return the wrapped key.
  384        *
  385        * @exception IllegalBlockSizeException if this cipher is a block
  386        * cipher, no padding has been requested, and the length of the
  387        * encoding of the key to be wrapped is not a
  388        * multiple of the block size.
  389        *
  390        * @exception InvalidKeyException if it is impossible or unsafe to
  391        * wrap the key with this cipher (e.g., a hardware protected key is
  392        * being passed to a software only cipher).
  393        */
  394       protected byte[] engineWrap(Key key)
  395           throws IllegalBlockSizeException, InvalidKeyException {
  396           return core.wrap(key);
  397       }
  398   
  399       /**
  400        * Unwrap a previously wrapped key.
  401        *
  402        * @param wrappedKey the key to be unwrapped.
  403        *
  404        * @param wrappedKeyAlgorithm the algorithm the wrapped key is for.
  405        *
  406        * @param wrappedKeyType the type of the wrapped key.
  407        * This is one of <code>Cipher.SECRET_KEY</code>,
  408        * <code>Cipher.PRIVATE_KEY</code>, or <code>Cipher.PUBLIC_KEY</code>.
  409        *
  410        * @return the unwrapped key.
  411        *
  412        * @exception NoSuchAlgorithmException if no installed providers
  413        * can create keys of type <code>wrappedKeyType</code> for the
  414        * <code>wrappedKeyAlgorithm</code>.
  415        *
  416        * @exception InvalidKeyException if <code>wrappedKey</code> does not
  417        * represent a wrapped key of type <code>wrappedKeyType</code> for
  418        * the <code>wrappedKeyAlgorithm</code>.
  419        */
  420       protected Key engineUnwrap(byte[] wrappedKey,
  421                                        String wrappedKeyAlgorithm,
  422                                        int wrappedKeyType)
  423           throws InvalidKeyException, NoSuchAlgorithmException {
  424           return core.unwrap(wrappedKey, wrappedKeyAlgorithm,
  425                              wrappedKeyType);
  426       }
  427   }

Save This Page
Home » openjdk-7 » com.sun.crypto » provider » [javadoc | source]