Source for javax.crypto.Cipher

   1: /* Cipher.java -- Interface to a cryptographic cipher.
   2:    Copyright (C) 2004, 2006  Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package javax.crypto;
  40: 
  41: import gnu.java.security.Engine;
  42: 
  43: import java.nio.ByteBuffer;
  44: import java.nio.ReadOnlyBufferException;
  45: 
  46: import java.security.AlgorithmParameters;
  47: import java.security.InvalidAlgorithmParameterException;
  48: import java.security.InvalidKeyException;
  49: import java.security.Key;
  50: import java.security.NoSuchAlgorithmException;
  51: import java.security.NoSuchProviderException;
  52: import java.security.Provider;
  53: import java.security.SecureRandom;
  54: import java.security.Security;
  55: import java.security.cert.Certificate;
  56: import java.security.cert.X509Certificate;
  57: import java.security.spec.AlgorithmParameterSpec;
  58: import java.util.StringTokenizer;
  59: 
  60: /**
  61:  * <p>This class implements a cryptographic cipher for transforming
  62:  * data.</p>
  63:  *
  64:  * <p>Ciphers cannot be instantiated directly; rather one of the
  65:  * <code>getInstance</code> must be used to instantiate a given
  66:  * <i>transformation</i>, optionally with a specific provider.</p>
  67:  *
  68:  * <p>A transformation is of the form:</p>
  69:  *
  70:  * <ul>
  71:  * <li><i>algorithm</i>/<i>mode</i>/<i>padding</i>, or</li>
  72:  * <li><i>algorithm</i>
  73:  * </ul>
  74:  *
  75:  * <p>where <i>algorithm</i> is the base name of a cryptographic cipher
  76:  * (such as "AES"), <i>mode</i> is the abbreviated name of a block
  77:  * cipher mode (such as "CBC" for cipher block chaining mode), and
  78:  * <i>padding</i> is the name of a padding scheme (such as
  79:  * "PKCS5Padding"). If only the algorithm name is supplied, then the
  80:  * provider-specific default mode and padding will be used.</p>
  81:  *
  82:  * <p>An example transformation is:</p>
  83:  *
  84:  * <blockquote><code>Cipher c =
  85:  * Cipher.getInstance("AES/CBC/PKCS5Padding");</code></blockquote>
  86:  *
  87:  * <p>Finally, when requesting a block cipher in stream cipher mode
  88:  * (such as <acronym title="Advanced Encryption Standard">AES</acronym>
  89:  * in OFB or CFB mode) the number of bits to be processed
  90:  * at a time may be specified by appending it to the name of the mode;
  91:  * e.g. <code>"AES/OFB8/NoPadding"</code>. If no such number is
  92:  * specified a provider-specific default value is used.</p>
  93:  *
  94:  * @author Casey Marshall (csm@gnu.org)
  95:  * @see java.security.KeyGenerator
  96:  * @see javax.crypto.SecretKey
  97:  */
  98: public class Cipher
  99: {
 100: 
 101:   // Constants and variables.
 102:   // ------------------------------------------------------------------------
 103: 
 104:   private static final String SERVICE = "Cipher";
 105: 
 106:   /**
 107:    * The decryption operation mode.
 108:    */
 109:   public static final int DECRYPT_MODE = 2;
 110: 
 111:   /**
 112:    * The encryption operation mode.
 113:    */
 114:   public static final int ENCRYPT_MODE = 1;
 115: 
 116:   /**
 117:    * Constant for when the key to be unwrapped is a private key.
 118:    */
 119:   public static final int PRIVATE_KEY = 2;
 120: 
 121:   /**
 122:    * Constant for when the key to be unwrapped is a public key.
 123:    */
 124:   public static final int PUBLIC_KEY = 1;
 125: 
 126:   /**
 127:    * Constant for when the key to be unwrapped is a secret key.
 128:    */
 129:   public static final int SECRET_KEY = 3;
 130: 
 131:   /**
 132:    * The key unwrapping operation mode.
 133:    */
 134:   public static final int UNWRAP_MODE = 4;
 135: 
 136:   /**
 137:    * The key wrapping operation mode.
 138:    */
 139:   public static final int WRAP_MODE = 3;
 140: 
 141:   /**
 142:    * The uninitialized state. This state signals that any of the
 143:    * <code>init</code> methods have not been called, and therefore no
 144:    * transformations can be done.
 145:    */
 146:   private static final int INITIAL_STATE = 0;
 147: 
 148:   /** The underlying cipher service provider interface. */
 149:   private CipherSpi cipherSpi;
 150: 
 151:   /** The provider from which this instance came. */
 152:   private Provider provider;
 153: 
 154:   /** The transformation requested. */
 155:   private String transformation;
 156: 
 157:   /** Our current state (encrypting, wrapping, etc.) */
 158:   private int state;
 159: 
 160:   /**
 161:    * Creates a new cipher instance for the given transformation.
 162:    * <p>
 163:    * The installed providers are tried in order for an implementation, and the
 164:    * first appropriate instance is returned. If no installed provider can
 165:    * provide the implementation, an appropriate exception is thrown.
 166:    *
 167:    * @param transformation The transformation to create.
 168:    * @return An appropriate cipher for this transformation.
 169:    * @throws NoSuchAlgorithmException If no installed provider can supply the
 170:    *           appropriate cipher or mode.
 171:    * @throws NoSuchPaddingException If no installed provider can supply the
 172:    *           appropriate padding.
 173:    */
 174:   public static final Cipher getInstance(String transformation)
 175:       throws NoSuchAlgorithmException, NoSuchPaddingException
 176:   {
 177:     Provider[] p = Security.getProviders();
 178:     NoSuchAlgorithmException lastException = null;
 179:     NoSuchPaddingException lastPaddingException = null;
 180:     for (int i = 0; i < p.length; i++)
 181:       try
 182:         {
 183:           return getInstance(transformation, p[i]);
 184:         }
 185:       catch (NoSuchAlgorithmException x)
 186:         {
 187:           lastException = x;
 188:           lastPaddingException = null;
 189:         }
 190:       catch (NoSuchPaddingException x)
 191:         {
 192:           lastPaddingException = x;
 193:         }
 194:     if (lastPaddingException != null)
 195:       throw lastPaddingException;
 196:     if (lastException != null)
 197:       throw lastException;
 198:     throw new NoSuchAlgorithmException(transformation);
 199:   }
 200: 
 201:   /**
 202:    * Creates a new cipher instance for the given transformation and the named
 203:    * provider.
 204:    *
 205:    * @param transformation The transformation to create.
 206:    * @param provider The name of the provider to use.
 207:    * @return An appropriate cipher for this transformation.
 208:    * @throws NoSuchAlgorithmException If the provider cannot supply the
 209:    *           appropriate cipher or mode.
 210:    * @throws NoSuchProviderException If the named provider is not installed.
 211:    * @throws NoSuchPaddingException If the provider cannot supply the
 212:    *           appropriate padding.
 213:    * @throws IllegalArgumentException if either <code>transformation</code> or
 214:    *           <code>provider</code> is <code>null</code>.
 215:    */
 216:   public static final Cipher getInstance(String transformation, String provider)
 217:       throws NoSuchAlgorithmException, NoSuchProviderException,
 218:       NoSuchPaddingException
 219:   {
 220:     if (provider == null)
 221:       throw new IllegalArgumentException("provider MUST NOT be null");
 222:     Provider p = Security.getProvider(provider);
 223:     if (p == null)
 224:       throw new NoSuchProviderException(provider);
 225:     return getInstance(transformation, p);
 226:   }
 227: 
 228:   /**
 229:    * Creates a new cipher instance for a given transformation from a given
 230:    * provider.
 231:    *
 232:    * @param transformation The transformation to create.
 233:    * @param provider The provider to use.
 234:    * @return An appropriate cipher for this transformation.
 235:    * @throws NoSuchAlgorithmException If the given provider cannot supply the
 236:    *           appropriate cipher or mode.
 237:    * @throws NoSuchPaddingException If the given provider cannot supply the
 238:    *           appropriate padding scheme.
 239:    */
 240:   public static final Cipher getInstance(String transformation,
 241:                                          Provider provider)
 242:       throws NoSuchAlgorithmException, NoSuchPaddingException
 243:   {
 244:     StringBuilder sb = new StringBuilder().append("Cipher transformation [")
 245:         .append(transformation).append("] from provider [")
 246:         .append(provider).append("] ");
 247:     Throwable cause;
 248:     Object spi;
 249:     CipherSpi result;
 250:     if (transformation.indexOf('/') < 0)
 251:       {
 252:         try
 253:           {
 254:             spi = Engine.getInstance(SERVICE, transformation, provider);
 255:             return new Cipher((CipherSpi) spi, provider, transformation);
 256:           }
 257:         catch (Exception e)
 258:           {
 259:             if (e instanceof NoSuchAlgorithmException)
 260:               throw (NoSuchAlgorithmException) e;
 261:             cause = e;
 262:           }
 263:       }
 264:     else
 265:       {
 266:         StringTokenizer tok = new StringTokenizer(transformation, "/");
 267:         if (tok.countTokens() != 3)
 268:           throw new NoSuchAlgorithmException(sb.append("is malformed").toString());
 269: 
 270:         String alg = tok.nextToken();
 271:         String mode = tok.nextToken();
 272:         String pad = tok.nextToken();
 273:         try
 274:           {
 275:             spi = Engine.getInstance(SERVICE, transformation, provider);
 276:             return new Cipher((CipherSpi) spi, provider, transformation);
 277:           }
 278:         catch (Exception e)
 279:           {
 280:             cause = e;
 281:           }
 282: 
 283:         try
 284:           {
 285:             spi = Engine.getInstance(SERVICE, alg + '/' + mode, provider);
 286:             result = (CipherSpi) spi;
 287:             result.engineSetPadding(pad);
 288:             return new Cipher(result, provider, transformation);
 289:           }
 290:         catch (Exception e)
 291:           {
 292:             if (e instanceof NoSuchPaddingException)
 293:               throw (NoSuchPaddingException) e;
 294:             cause = e;
 295:           }
 296: 
 297:         try
 298:           {
 299:             spi = Engine.getInstance(SERVICE, alg + "//" + pad, provider);
 300:             result = (CipherSpi) spi;
 301:             result.engineSetMode(mode);
 302:             return new Cipher(result, provider, transformation);
 303:           }
 304:         catch (Exception e)
 305:           {
 306:             cause = e;
 307:           }
 308: 
 309:         try
 310:           {
 311:             spi = Engine.getInstance(SERVICE, alg, provider);
 312:             result = (CipherSpi) spi;
 313:             result.engineSetMode(mode);
 314:             result.engineSetPadding(pad);
 315:             return new Cipher(result, provider, transformation);
 316:           }
 317:         catch (Exception e)
 318:           {
 319:             if (e instanceof NoSuchPaddingException)
 320:               throw (NoSuchPaddingException) e;
 321:             cause = e;
 322:           }
 323:       }
 324:     sb.append("could not be created");
 325:     NoSuchAlgorithmException x = new NoSuchAlgorithmException(sb.toString());
 326:     x.initCause(cause);
 327:     throw x;
 328:   }
 329: 
 330:   /**
 331:    * Create a cipher.
 332:    *
 333:    * @param cipherSpi The underlying implementation of the cipher.
 334:    * @param provider  The provider of this cipher implementation.
 335:    * @param transformation The transformation this cipher performs.
 336:    */
 337:   protected
 338:   Cipher(CipherSpi cipherSpi, Provider provider, String transformation)
 339:   {
 340:     this.cipherSpi = cipherSpi;
 341:     this.provider = provider;
 342:     this.transformation = transformation;
 343:     state = INITIAL_STATE;
 344:   }
 345: 
 346:   /**
 347:    * Get the name that this cipher instance was created with; this is
 348:    * equivalent to the "transformation" argument given to any of the
 349:    * {@link #getInstance()} methods.
 350:    *
 351:    * @return The cipher name.
 352:    */
 353:   public final String getAlgorithm()
 354:   {
 355:     return transformation;
 356:   }
 357: 
 358:   /**
 359:    * Return the size of blocks, in bytes, that this cipher processes.
 360:    *
 361:    * @return The block size.
 362:    */
 363:   public final int getBlockSize()
 364:   {
 365:     if (cipherSpi != null)
 366:       {
 367:         return cipherSpi.engineGetBlockSize();
 368:       }
 369:     return 1;
 370:   }
 371: 
 372:   /**
 373:    * Return the currently-operating {@link ExemptionMechanism}.
 374:    *
 375:    * @return null, currently.
 376:    */
 377:   public final ExemptionMechanism getExemptionMechanism()
 378:   {
 379:     return null;
 380:   }
 381: 
 382:   /**
 383:    * Return the <i>initialization vector</i> that this instance was
 384:    * initialized with.
 385:    *
 386:    * @return The IV.
 387:    */
 388:   public final byte[] getIV()
 389:   {
 390:     if (cipherSpi != null)
 391:       {
 392:         return cipherSpi.engineGetIV();
 393:       }
 394:     return null;
 395:   }
 396: 
 397:   /**
 398:    * Return the {@link java.security.AlgorithmParameters} that this
 399:    * instance was initialized with.
 400:    *
 401:    * @return The parameters.
 402:    */
 403:   public final AlgorithmParameters getParameters()
 404:   {
 405:     if (cipherSpi != null) {
 406:       return cipherSpi.engineGetParameters();
 407:     }
 408:     return null;
 409:   }
 410: 
 411:   /**
 412:    * Return this cipher's provider.
 413:    *
 414:    * @return The provider.
 415:    */
 416:   public final Provider getProvider()
 417:   {
 418:     return provider;
 419:   }
 420: 
 421:   /**
 422:    * Finishes a multi-part transformation, and returns the final
 423:    * transformed bytes.
 424:    *
 425:    * @return The final transformed bytes.
 426:    * @throws java.lang.IllegalStateException If this instance has not
 427:    *         been initialized, or if a <tt>doFinal</tt> call has already
 428:    *         been made.
 429:    * @throws javax.crypto.IllegalBlockSizeException If this instance has
 430:    *         no padding and the input is not a multiple of this cipher's
 431:    *         block size.
 432:    * @throws javax.crypto.BadPaddingException If this instance is
 433:    *         decrypting and the padding bytes do not match this
 434:    *         instance's padding scheme.
 435:    */
 436:   public final byte[] doFinal()
 437:     throws IllegalStateException, IllegalBlockSizeException, BadPaddingException
 438:   {
 439:     return doFinal(new byte[0], 0, 0);
 440:   }
 441: 
 442:   /**
 443:    * Finishes a multi-part transformation or does an entire
 444:    * transformation on the input, and returns the transformed bytes.
 445:    *
 446:    * @param input The final input bytes.
 447:    * @return The final transformed bytes.
 448:    * @throws java.lang.IllegalStateException If this instance has not
 449:    *         been initialized, or if a <tt>doFinal</tt> call has already
 450:    *         been made.
 451:    * @throws javax.crypto.IllegalBlockSizeException If this instance has
 452:    *         no padding and the input is not a multiple of this cipher's
 453:    *         block size.
 454:    * @throws javax.crypto.BadPaddingException If this instance is
 455:    *         decrypting and the padding bytes do not match this
 456:    *         instance's padding scheme.
 457:    */
 458:   public final byte[] doFinal(byte[] input)
 459:     throws IllegalStateException, IllegalBlockSizeException, BadPaddingException
 460:   {
 461:     return doFinal(input, 0, input.length);
 462:   }
 463: 
 464:   /**
 465:    * Finishes a multi-part transformation or does an entire
 466:    * transformation on the input, and returns the transformed bytes.
 467:    *
 468:    * @param input       The final input bytes.
 469:    * @param inputOffset The index in the input bytes to start.
 470:    * @param inputLength The number of bytes to read from the input.
 471:    * @return The final transformed bytes.
 472:    * @throws java.lang.IllegalStateException If this instance has not
 473:    *         been initialized, or if a <tt>doFinal</tt> call has already
 474:    *         been made.
 475:    * @throws javax.crypto.IllegalBlockSizeException If this instance has
 476:    *         no padding and the input is not a multiple of this cipher's
 477:    *         block size.
 478:    * @throws javax.crypto.BadPaddingException If this instance is
 479:    *         decrypting and the padding bytes do not match this
 480:    *         instance's padding scheme.
 481:    */
 482:   public final byte[] doFinal(byte[] input, int inputOffset, int inputLength)
 483:     throws IllegalStateException, IllegalBlockSizeException, BadPaddingException
 484:   {
 485:     if (cipherSpi == null)
 486:       {
 487:         byte[] b = new byte[inputLength];
 488:         System.arraycopy(input, inputOffset, b, 0, inputLength);
 489:         return b;
 490:       }
 491:     if (state != ENCRYPT_MODE && state != DECRYPT_MODE)
 492:       {
 493:         throw new IllegalStateException("neither encrypting nor decrypting");
 494:       }
 495:     return cipherSpi.engineDoFinal(input, inputOffset, inputLength);
 496:   }
 497: 
 498:   /**
 499:    * Finishes a multi-part transformation and stores the transformed
 500:    * bytes into the given array.
 501:    *
 502:    * @param output       The destination for the transformed bytes.
 503:    * @param outputOffset The offset in <tt>output</tt> to start storing
 504:    *        bytes.
 505:    * @return The number of bytes placed into the output array.
 506:    * @throws java.lang.IllegalStateException If this instance has not
 507:    *         been initialized, or if a <tt>doFinal</tt> call has already
 508:    *         been made.
 509:    * @throws javax.crypto.IllegalBlockSizeException If this instance has
 510:    *         no padding and the input is not a multiple of this cipher's
 511:    *         block size.
 512:    * @throws javax.crypto.BadPaddingException If this instance is
 513:    *         decrypting and the padding bytes do not match this
 514:    *         instance's padding scheme.
 515:    * @throws javax.crypto.ShortBufferException If the output array is
 516:    *         not large enough to hold the transformed bytes.
 517:    */
 518:   public final int doFinal(byte[] output, int outputOffset)
 519:     throws IllegalStateException, IllegalBlockSizeException, BadPaddingException,
 520:            ShortBufferException
 521:   {
 522:     if (cipherSpi == null)
 523:       {
 524:         return 0;
 525:       }
 526:     if (state != ENCRYPT_MODE && state != DECRYPT_MODE)
 527:       {
 528:         throw new IllegalStateException("neither encrypting nor decrypting");
 529:       }
 530:     return cipherSpi.engineDoFinal(new byte[0], 0, 0, output, outputOffset);
 531:   }
 532: 
 533:   /**
 534:    * Finishes a multi-part transformation or transforms a portion of a
 535:    * byte array, and stores the result in the given byte array.
 536:    *
 537:    * @param input        The input bytes.
 538:    * @param inputOffset  The index in <tt>input</tt> to start.
 539:    * @param inputLength  The number of bytes to transform.
 540:    * @param output       The output buffer.
 541:    * @param outputOffset The index in <tt>output</tt> to start.
 542:    * @return The number of bytes placed into the output array.
 543:    * @throws java.lang.IllegalStateException If this instance has not
 544:    *         been initialized, or if a <tt>doFinal</tt> call has already
 545:    *         been made.
 546:    * @throws javax.crypto.IllegalBlockSizeException If this instance has
 547:    *         no padding and the input is not a multiple of this cipher's
 548:    *         block size.
 549:    * @throws javax.crypto.BadPaddingException If this instance is
 550:    *         decrypting and the padding bytes do not match this
 551:    *         instance's padding scheme.
 552:    * @throws javax.crypto.ShortBufferException If the output array is
 553:    *         not large enough to hold the transformed bytes.
 554:    */
 555:   public final int doFinal(byte[] input, int inputOffset, int inputLength,
 556:                            byte[] output, int outputOffset)
 557:     throws IllegalStateException, IllegalBlockSizeException, BadPaddingException,
 558:            ShortBufferException
 559:   {
 560:     if (cipherSpi == null)
 561:       {
 562:         if (inputLength > output.length - outputOffset)
 563:           {
 564:             throw new ShortBufferException();
 565:           }
 566:         System.arraycopy(input, inputOffset, output, outputOffset, inputLength);
 567:         return inputLength;
 568:       }
 569:     if (state != ENCRYPT_MODE && state != DECRYPT_MODE)
 570:       {
 571:         throw new IllegalStateException("neither encrypting nor decrypting");
 572:       }
 573:     return cipherSpi.engineDoFinal(input, inputOffset, inputLength,
 574:                                    output, outputOffset);
 575:   }
 576: 
 577:   public final int doFinal(byte[] input, int inputOffset, int inputLength,
 578:                            byte[] output)
 579:     throws IllegalStateException, IllegalBlockSizeException, BadPaddingException,
 580:            ShortBufferException
 581:   {
 582:     return doFinal(input, inputOffset, inputLength, output, 0);
 583:   }
 584: 
 585:   /**
 586:    * Finishes a multi-part transformation with, or completely
 587:    * transforms, a byte buffer, and stores the result into the output
 588:    * buffer.
 589:    *
 590:    * @param input  The input buffer.
 591:    * @param output The output buffer.
 592:    * @return The number of bytes stored into the output buffer.
 593:    * @throws IllegalArgumentException If the input and output buffers
 594:    *  are the same object.
 595:    * @throws IllegalStateException If this cipher was not initialized
 596:    *  for encryption or decryption.
 597:    * @throws ReadOnlyBufferException If the output buffer is not
 598:    *  writable.
 599:    * @throws IllegalBlockSizeException If this cipher requires a total
 600:    *  input that is a multiple of its block size to complete this
 601:    *  transformation.
 602:    * @throws ShortBufferException If the output buffer is not large
 603:    *  enough to hold the transformed bytes.
 604:    * @throws BadPaddingException If the cipher is a block cipher with
 605:    *  a padding scheme, and the decrypted bytes do not end with a
 606:    *  valid padding.
 607:    * @since 1.5
 608:    */
 609:   public final int doFinal (ByteBuffer input, ByteBuffer output)
 610:     throws ReadOnlyBufferException, ShortBufferException,
 611:            BadPaddingException, IllegalBlockSizeException
 612:   {
 613:     if (input == output)
 614:       throw new IllegalArgumentException
 615:         ("input and output buffers cannot be the same");
 616:     if (state != ENCRYPT_MODE && state != DECRYPT_MODE)
 617:       throw new IllegalStateException
 618:         ("not initialized for encrypting or decrypting");
 619:     return cipherSpi.engineDoFinal (input, output);
 620:   }
 621: 
 622:   /**
 623:    * Returns the size an output buffer needs to be if this cipher is
 624:    * updated with a number of bytes.
 625:    *
 626:    * @param inputLength The input length.
 627:    * @return The output length given this input length.
 628:    * @throws java.lang.IllegalStateException If this instance has not
 629:    *         been initialized, or if a <tt>doFinal</tt> call has already
 630:    *         been made.
 631:    */
 632:   public final int getOutputSize(int inputLength) throws IllegalStateException
 633:   {
 634:     if (cipherSpi == null)
 635:       return inputLength;
 636:     return cipherSpi.engineGetOutputSize(inputLength);
 637:   }
 638: 
 639:   /**
 640:    * <p>Initialize this cipher with the public key from the given
 641:    * certificate.</p>
 642:    *
 643:    * <p>The cipher will be initialized for encryption, decryption, key
 644:    * wrapping, or key unwrapping, depending upon whether the
 645:    * <code>opmode</code> argument is {@link #ENCRYPT_MODE}, {@link
 646:    * #DECRYPT_MODE}, {@link #WRAP_MODE}, or {@link #UNWRAP_MODE},
 647:    * respectively.</p>
 648:    *
 649:    * <p>As per the Java 1.4 specification, if <code>cert</code> is an
 650:    * instance of an {@link java.security.cert.X509Certificate} and its
 651:    * <i>key usage</i> extension field is incompatible with
 652:    * <code>opmode</code> then an {@link
 653:    * java.security.InvalidKeyException} is thrown.</p>
 654:    *
 655:    * <p>If this cipher requires any random bytes (for example for an
 656:    * initilization vector) than the {@link java.security.SecureRandom}
 657:    * with the highest priority is used as the source of these bytes.</p>
 658:    *
 659:    * <p>A call to any of the <code>init</code> methods overrides the
 660:    * state of the instance, and is equivalent to creating a new instance
 661:    * and calling its <code>init</code> method.</p>
 662:    *
 663:    * @param opmode      The operation mode to use.
 664:    * @param certificate The certificate.
 665:    * @throws java.security.InvalidKeyException If the underlying cipher
 666:    *         instance rejects the certificate's public key, or if the
 667:    *         public key cannot be used as described above.
 668:    */
 669:   public final void init(int opmode, Certificate certificate)
 670:     throws InvalidKeyException
 671:   {
 672:     init(opmode, certificate, new SecureRandom());
 673:   }
 674: 
 675:   /**
 676:    * <p>Initialize this cipher with the supplied key.</p>
 677:    *
 678:    * <p>The cipher will be initialized for encryption, decryption, key
 679:    * wrapping, or key unwrapping, depending upon whether the
 680:    * <code>opmode</code> argument is {@link #ENCRYPT_MODE}, {@link
 681:    * #DECRYPT_MODE}, {@link #WRAP_MODE}, or {@link #UNWRAP_MODE},
 682:    * respectively.</p>
 683:    *
 684:    * <p>If this cipher requires any random bytes (for example for an
 685:    * initilization vector) than the {@link java.security.SecureRandom}
 686:    * with the highest priority is used as the source of these bytes.</p>
 687:    *
 688:    * <p>A call to any of the <code>init</code> methods overrides the
 689:    * state of the instance, and is equivalent to creating a new instance
 690:    * and calling its <code>init</code> method.</p>
 691:    *
 692:    * @param opmode The operation mode to use.
 693:    * @param key    The key.
 694:    * @throws java.security.InvalidKeyException If the underlying cipher
 695:    *         instance rejects the given key.
 696:    */
 697:   public final void init(int opmode, Key key) throws InvalidKeyException
 698:   {
 699:     if (cipherSpi != null)
 700:       {
 701:         cipherSpi.engineInit(opmode, key, new SecureRandom());
 702:       }
 703:     state = opmode;
 704:   }
 705: 
 706:   /**
 707:    * <p>Initialize this cipher with the public key from the given
 708:    * certificate and the specified source of randomness.</p>
 709:    *
 710:    * <p>The cipher will be initialized for encryption, decryption, key
 711:    * wrapping, or key unwrapping, depending upon whether the
 712:    * <code>opmode</code> argument is {@link #ENCRYPT_MODE}, {@link
 713:    * #DECRYPT_MODE}, {@link #WRAP_MODE}, or {@link #UNWRAP_MODE},
 714:    * respectively.</p>
 715:    *
 716:    * <p>As per the Java 1.4 specification, if <code>cert</code> is an
 717:    * instance of an {@link java.security.cert.X509Certificate} and its
 718:    * <i>key usage</i> extension field is incompatible with
 719:    * <code>opmode</code> then an {@link
 720:    * java.security.InvalidKeyException} is thrown.</p>
 721:    *
 722:    * <p>If this cipher requires any random bytes (for example for an
 723:    * initilization vector) than the {@link java.security.SecureRandom}
 724:    * with the highest priority is used as the source of these bytes.</p>
 725:    *
 726:    * <p>A call to any of the <code>init</code> methods overrides the
 727:    * state of the instance, and is equivalent to creating a new instance
 728:    * and calling its <code>init</code> method.</p>
 729:    *
 730:    * @param opmode      The operation mode to use.
 731:    * @param certificate The certificate.
 732:    * @param random      The source of randomness.
 733:    * @throws java.security.InvalidKeyException If the underlying cipher
 734:    *         instance rejects the certificate's public key, or if the
 735:    *         public key cannot be used as described above.
 736:    */
 737:   public final void
 738:   init(int opmode, Certificate certificate, SecureRandom random)
 739:   throws InvalidKeyException
 740:   {
 741:     if (certificate instanceof X509Certificate)
 742:       {
 743:         boolean[] keyInfo = ((X509Certificate) certificate).getKeyUsage();
 744:         if (keyInfo != null)
 745:           {
 746:             switch (opmode)
 747:               {
 748:               case DECRYPT_MODE:
 749:                 if (!keyInfo[3])
 750:                   {
 751:                     throw new InvalidKeyException(
 752:                       "the certificate's key cannot be used for transforming data");
 753:                   }
 754:                 if (keyInfo[7])
 755:                   {
 756:                     throw new InvalidKeyException(
 757:                       "the certificate's key can only be used for encryption");
 758:                   }
 759:                 break;
 760: 
 761:               case ENCRYPT_MODE:
 762:                 if (!keyInfo[3])
 763:                   {
 764:                     throw new InvalidKeyException(
 765:                       "the certificate's key cannot be used for transforming data");
 766:                   }
 767:                 if (keyInfo[8])
 768:                   {
 769:                     throw new InvalidKeyException(
 770:                       "the certificate's key can only be used for decryption");
 771:                   }
 772:                 break;
 773: 
 774:               case UNWRAP_MODE:
 775:                 if (!keyInfo[2] || keyInfo[7])
 776:                   {
 777:                     throw new InvalidKeyException(
 778:                       "the certificate's key cannot be used for key unwrapping");
 779:                   }
 780:                 break;
 781: 
 782:               case WRAP_MODE:
 783:                 if (!keyInfo[2] || keyInfo[8])
 784:                   {
 785:                     throw new InvalidKeyException(
 786:                       "the certificate's key cannot be used for key wrapping");
 787:                   }
 788:                 break;
 789:               }
 790:           }
 791:       }
 792:     init(opmode, certificate.getPublicKey(), random);
 793:   }
 794: 
 795:   /**
 796:    * <p>Initialize this cipher with the supplied key and source of
 797:    * randomness.</p>
 798:    *
 799:    * <p>The cipher will be initialized for encryption, decryption, key
 800:    * wrapping, or key unwrapping, depending upon whether the
 801:    * <code>opmode</code> argument is {@link #ENCRYPT_MODE}, {@link
 802:    * #DECRYPT_MODE}, {@link #WRAP_MODE}, or {@link #UNWRAP_MODE},
 803:    * respectively.</p>
 804:    *
 805:    * <p>A call to any of the <code>init</code> methods overrides the
 806:    * state of the instance, and is equivalent to creating a new instance
 807:    * and calling its <code>init</code> method.</p>
 808:    *
 809:    * @param opmode The operation mode to use.
 810:    * @param key    The key.
 811:    * @param random The source of randomness to use.
 812:    * @throws java.security.InvalidKeyException If the underlying cipher
 813:    *         instance rejects the given key.
 814:    */
 815:   public final void init(int opmode, Key key, SecureRandom random)
 816:     throws InvalidKeyException
 817:   {
 818:     if (cipherSpi != null)
 819:       {
 820:         cipherSpi.engineInit(opmode, key, random);
 821:       }
 822:     state = opmode;
 823:   }
 824: 
 825:   /**
 826:    * <p>Initialize this cipher with the supplied key and parameters.</p>
 827:    *
 828:    * <p>The cipher will be initialized for encryption, decryption, key
 829:    * wrapping, or key unwrapping, depending upon whether the
 830:    * <code>opmode</code> argument is {@link #ENCRYPT_MODE}, {@link
 831:    * #DECRYPT_MODE}, {@link #WRAP_MODE}, or {@link #UNWRAP_MODE},
 832:    * respectively.</p>
 833:    *
 834:    * <p>If this cipher requires any random bytes (for example for an
 835:    * initilization vector) then the {@link java.security.SecureRandom}
 836:    * with the highest priority is used as the source of these bytes.</p>
 837:    *
 838:    * <p>A call to any of the <code>init</code> methods overrides the
 839:    * state of the instance, and is equivalent to creating a new instance
 840:    * and calling its <code>init</code> method.</p>
 841:    *
 842:    * @param opmode The operation mode to use.
 843:    * @param key    The key.
 844:    * @param params The algorithm parameters to initialize this instance
 845:    *               with.
 846:    * @throws java.security.InvalidKeyException If the underlying cipher
 847:    *         instance rejects the given key.
 848:    * @throws java.security.InvalidAlgorithmParameterException If the
 849:    *         supplied parameters are inappropriate for this cipher.
 850:    */
 851:   public final void init(int opmode, Key key, AlgorithmParameters params)
 852:     throws InvalidKeyException, InvalidAlgorithmParameterException
 853:   {
 854:     init(opmode, key, params, new SecureRandom());
 855:   }
 856: 
 857:   /**
 858:    * <p>Initialize this cipher with the supplied key and parameters.</p>
 859:    *
 860:    * <p>The cipher will be initialized for encryption, decryption, key
 861:    * wrapping, or key unwrapping, depending upon whether the
 862:    * <code>opmode</code> argument is {@link #ENCRYPT_MODE}, {@link
 863:    * #DECRYPT_MODE}, {@link #WRAP_MODE}, or {@link #UNWRAP_MODE},
 864:    * respectively.</p>
 865:    *
 866:    * <p>If this cipher requires any random bytes (for example for an
 867:    * initilization vector) then the {@link java.security.SecureRandom}
 868:    * with the highest priority is used as the source of these bytes.</p>
 869:    *
 870:    * <p>A call to any of the <code>init</code> methods overrides the
 871:    * state of the instance, and is equivalent to creating a new instance
 872:    * and calling its <code>init</code> method.</p>
 873:    *
 874:    * @param opmode The operation mode to use.
 875:    * @param key    The key.
 876:    * @param params The algorithm parameters to initialize this instance
 877:    *               with.
 878:    * @throws java.security.InvalidKeyException If the underlying cipher
 879:    *         instance rejects the given key.
 880:    * @throws java.security.InvalidAlgorithmParameterException If the
 881:    *         supplied parameters are inappropriate for this cipher.
 882:    */
 883:   public final void init(int opmode, Key key, AlgorithmParameterSpec params)
 884:     throws InvalidKeyException, InvalidAlgorithmParameterException
 885:   {
 886:     init(opmode, key, params, new SecureRandom());
 887:   }
 888: 
 889:   /**
 890:    * <p>Initialize this cipher with the supplied key, parameters, and
 891:    * source of randomness.</p>
 892:    *
 893:    * <p>The cipher will be initialized for encryption, decryption, key
 894:    * wrapping, or key unwrapping, depending upon whether the
 895:    * <code>opmode</code> argument is {@link #ENCRYPT_MODE}, {@link
 896:    * #DECRYPT_MODE}, {@link #WRAP_MODE}, or {@link #UNWRAP_MODE},
 897:    * respectively.</p>
 898:    *
 899:    * <p>A call to any of the <code>init</code> methods overrides the
 900:    * state of the instance, and is equivalent to creating a new instance
 901:    * and calling its <code>init</code> method.</p>
 902:    *
 903:    * @param opmode The operation mode to use.
 904:    * @param key    The key.
 905:    * @param params The algorithm parameters to initialize this instance
 906:    *               with.
 907:    * @param random The source of randomness to use.
 908:    * @throws java.security.InvalidKeyException If the underlying cipher
 909:    *         instance rejects the given key.
 910:    * @throws java.security.InvalidAlgorithmParameterException If the
 911:    *         supplied parameters are inappropriate for this cipher.
 912:    */
 913:   public final void init(int opmode, Key key, AlgorithmParameters params,
 914:                          SecureRandom random)
 915:     throws InvalidKeyException, InvalidAlgorithmParameterException
 916:   {
 917:     if (cipherSpi != null)
 918:       {
 919:         cipherSpi.engineInit(opmode, key, params, random);
 920:       }
 921:     state = opmode;
 922:   }
 923: 
 924:   /**
 925:    * <p>Initialize this cipher with the supplied key, parameters, and
 926:    * source of randomness.</p>
 927:    *
 928:    * <p>The cipher will be initialized for encryption, decryption, key
 929:    * wrapping, or key unwrapping, depending upon whether the
 930:    * <code>opmode</code> argument is {@link #ENCRYPT_MODE}, {@link
 931:    * #DECRYPT_MODE}, {@link #WRAP_MODE}, or {@link #UNWRAP_MODE},
 932:    * respectively.</p>
 933:    *
 934:    * <p>A call to any of the <code>init</code> methods overrides the
 935:    * state of the instance, and is equivalent to creating a new instance
 936:    * and calling its <code>init</code> method.</p>
 937:    *
 938:    * @param opmode The operation mode to use.
 939:    * @param key    The key.
 940:    * @param params The algorithm parameters to initialize this instance
 941:    *               with.
 942:    * @param random The source of randomness to use.
 943:    * @throws java.security.InvalidKeyException If the underlying cipher
 944:    *         instance rejects the given key.
 945:    * @throws java.security.InvalidAlgorithmParameterException If the
 946:    *         supplied parameters are inappropriate for this cipher.
 947:    */
 948:   public final void init(int opmode, Key key, AlgorithmParameterSpec params,
 949:                          SecureRandom random)
 950:     throws InvalidKeyException, InvalidAlgorithmParameterException
 951:   {
 952:     if (cipherSpi != null)
 953:       {
 954:         cipherSpi.engineInit(opmode, key, params, random);
 955:       }
 956:     state = opmode;
 957:   }
 958: 
 959:   /**
 960:    * Unwrap a previously-wrapped key.
 961:    *
 962:    * @param wrappedKey          The wrapped key.
 963:    * @param wrappedKeyAlgorithm The algorithm with which the key was
 964:    *        wrapped.
 965:    * @param wrappedKeyType      The type of key (public, private, or
 966:    *        secret) that this wrapped key respresents.
 967:    * @return The unwrapped key.
 968:    * @throws java.lang.IllegalStateException If this instance has not be
 969:    *         initialized for unwrapping.
 970:    * @throws java.security.InvalidKeyException If <code>wrappedKey</code>
 971:    *         is not a wrapped key, if the algorithm cannot unwrap this
 972:    *         key, or if the unwrapped key's type differs from the
 973:    *         specified type.
 974:    * @throws java.security.NoSuchAlgorithmException If
 975:    *         <code>wrappedKeyAlgorithm</code> is not a valid algorithm
 976:    *         name.
 977:    */
 978:   public final Key unwrap(byte[] wrappedKey, String wrappedKeyAlgorithm,
 979:                           int wrappedKeyType)
 980:     throws IllegalStateException, InvalidKeyException, NoSuchAlgorithmException
 981:   {
 982:     if (cipherSpi == null)
 983:       {
 984:         return null;
 985:       }
 986:     if (state != UNWRAP_MODE)
 987:       {
 988:         throw new IllegalStateException("instance is not for unwrapping");
 989:       }
 990:     return cipherSpi.engineUnwrap(wrappedKey, wrappedKeyAlgorithm,
 991:                                   wrappedKeyType);
 992:   }
 993: 
 994:   /**
 995:    * Continue a multi-part transformation on an entire byte array,
 996:    * returning the transformed bytes.
 997:    *
 998:    * @param input The input bytes.
 999:    * @return The transformed bytes.
1000:    * @throws java.lang.IllegalStateException If this cipher was not
1001:    *         initialized for encryption or decryption.
1002:    */
1003:   public final byte[] update(byte[] input) throws IllegalStateException
1004:   {
1005:     return update(input, 0, input.length);
1006:   }
1007: 
1008:   /**
1009:    * Continue a multi-part transformation on part of a byte array,
1010:    * returning the transformed bytes.
1011:    *
1012:    * @param input       The input bytes.
1013:    * @param inputOffset The index in the input to start.
1014:    * @param inputLength The number of bytes to transform.
1015:    * @return The transformed bytes.
1016:    * @throws java.lang.IllegalStateException If this cipher was not
1017:    *         initialized for encryption or decryption.
1018:    */
1019:   public final byte[] update(byte[] input, int inputOffset, int inputLength)
1020:     throws IllegalStateException
1021:   {
1022:     if (cipherSpi == null)
1023:       {
1024:         byte[] b = new byte[inputLength];
1025:         System.arraycopy(input, inputOffset, b, 0, inputLength);
1026:         return b;
1027:       }
1028:     if (state != ENCRYPT_MODE && state != DECRYPT_MODE)
1029:       {
1030:         throw new IllegalStateException(
1031:           "cipher is not for encrypting or decrypting");
1032:       }
1033:     return cipherSpi.engineUpdate(input, inputOffset, inputLength);
1034:   }
1035: 
1036:   /**
1037:    * Continue a multi-part transformation on part of a byte array,
1038:    * placing the transformed bytes into the given array.
1039:    *
1040:    * @param input       The input bytes.
1041:    * @param inputOffset The index in the input to start.
1042:    * @param inputLength The number of bytes to transform.
1043:    * @param output      The output byte array.
1044:    * @return The number of transformed bytes.
1045:    * @throws java.lang.IllegalStateException If this cipher was not
1046:    *         initialized for encryption or decryption.
1047:    * @throws javax.security.ShortBufferException If there is not enough
1048:    *         room in the output array to hold the transformed bytes.
1049:    */
1050:   public final int update(byte[] input, int inputOffset, int inputLength,
1051:                           byte[] output)
1052:     throws IllegalStateException, ShortBufferException
1053:   {
1054:     return update(input, inputOffset, inputLength, output, 0);
1055:   }
1056: 
1057:   /**
1058:    * Continue a multi-part transformation on part of a byte array,
1059:    * placing the transformed bytes into the given array.
1060:    *
1061:    * @param input        The input bytes.
1062:    * @param inputOffset  The index in the input to start.
1063:    * @param inputLength  The number of bytes to transform.
1064:    * @param output       The output byte array.
1065:    * @param outputOffset The index in the output array to start.
1066:    * @return The number of transformed bytes.
1067:    * @throws java.lang.IllegalStateException If this cipher was not
1068:    *         initialized for encryption or decryption.
1069:    * @throws javax.security.ShortBufferException If there is not enough
1070:    *         room in the output array to hold the transformed bytes.
1071:    */
1072:   public final int update(byte[] input, int inputOffset, int inputLength,
1073:                           byte[] output, int outputOffset)
1074:     throws IllegalStateException, ShortBufferException
1075:   {
1076:     if (cipherSpi == null)
1077:       {
1078:         if (inputLength > output.length - outputOffset)
1079:           {
1080:             throw new ShortBufferException();
1081:           }
1082:         System.arraycopy(input, inputOffset, output, outputOffset, inputLength);
1083:         return inputLength;
1084:       }
1085:     if (state != ENCRYPT_MODE && state != DECRYPT_MODE)
1086:       {
1087:         throw new IllegalStateException(
1088:           "cipher is not for encrypting or decrypting");
1089:       }
1090:     return cipherSpi.engineUpdate(input, inputOffset, inputLength,
1091:                                   output, outputOffset);
1092:   }
1093: 
1094:   /**
1095:    * Continue a multi-part transformation on a byte buffer, storing
1096:    * the transformed bytes into another buffer.
1097:    *
1098:    * @param input  The input buffer.
1099:    * @param output The output buffer.
1100:    * @return The number of bytes stored in <i>output</i>.
1101:    * @throws IllegalArgumentException If the two buffers are the same
1102:    *  object.
1103:    * @throws IllegalStateException If this cipher was not initialized
1104:    *  for encrypting or decrypting.
1105:    * @throws ReadOnlyBufferException If the output buffer is not
1106:    *  writable.
1107:    * @throws ShortBufferException If the output buffer does not have
1108:    *  enough available space for the transformed bytes.
1109:    * @since 1.5
1110:    */
1111:   public final int update (ByteBuffer input, ByteBuffer output)
1112:     throws ReadOnlyBufferException, ShortBufferException
1113:   {
1114:     if (input == output)
1115:       throw new IllegalArgumentException
1116:         ("input and output buffers must be different");
1117:     if (state != ENCRYPT_MODE && state != DECRYPT_MODE)
1118:       throw new IllegalStateException
1119:         ("not initialized for encryption or decryption");
1120:     return cipherSpi.engineUpdate (input, output);
1121:   }
1122: 
1123:   /**
1124:    * Wrap a key.
1125:    *
1126:    * @param key The key to wrap.
1127:    * @return The wrapped key.
1128:    * @throws java.lang.IllegalStateException If this instance was not
1129:    *         initialized for key wrapping.
1130:    * @throws javax.crypto.IllegalBlockSizeException If this instance has
1131:    *         no padding and the key is not a multiple of the block size.
1132:    * @throws java.security.InvalidKeyException If this instance cannot
1133:    *         wrap this key.
1134:    */
1135:   public final byte[] wrap(Key key)
1136:     throws IllegalStateException, IllegalBlockSizeException, InvalidKeyException
1137:   {
1138:     if (cipherSpi == null)
1139:       {
1140:         return null;
1141:       }
1142:     if (state != WRAP_MODE)
1143:       {
1144:         throw new IllegalStateException("instance is not for key wrapping");
1145:       }
1146:     return cipherSpi.engineWrap(key);
1147:   }
1148: }