1 /* 2 * Copyright (c) 1997, 2018, 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.*; 29 import java.util.concurrent.ConcurrentHashMap; 30 import java.util.concurrent.ConcurrentMap; 31 import java.util.regex.*; 32 33 34 import java.security.*; 35 import java.security.Provider.Service; 36 import java.security.spec.AlgorithmParameterSpec; 37 import java.security.spec.InvalidParameterSpecException; 38 import java.security.cert.Certificate; 39 import java.security.cert.X509Certificate; 40 41 import javax.crypto.spec.*; 42 43 import java.nio.ByteBuffer; 44 import java.nio.ReadOnlyBufferException; 45 46 import sun.security.util.Debug; 47 import sun.security.jca.*; 48 49 /** 50 * This class provides the functionality of a cryptographic cipher for 51 * encryption and decryption. It forms the core of the Java Cryptographic 52 * Extension (JCE) framework. 53 * 54 * <p>In order to create a Cipher object, the application calls the 55 * Cipher's {@code getInstance} method, and passes the name of the 56 * requested <i>transformation</i> to it. Optionally, the name of a provider 57 * may be specified. 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>AES</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>AES/CBC/PKCS5Padding</i>"); 79 * </pre> 80 * 81 * Using modes such as {@code CFB} and {@code OFB}, block 82 * ciphers can encrypt data in units smaller than the cipher's actual 83 * block size. When requesting such a mode, you may optionally specify 84 * the number of bits to be processed at a time by appending this number 85 * to the mode name as shown in the "{@code AES/CFB8/NoPadding}" and 86 * "{@code AES/OFB32/PKCS5Padding}" transformations. If no such 87 * number is specified, a provider-specific default is used. 88 * (See the 89 * {@extLink security_guide_jdk_providers JDK Providers Documentation} 90 * for the JDK Providers default values.) 91 * Thus, block ciphers can be turned into byte-oriented stream ciphers by 92 * using an 8 bit mode such as CFB8 or OFB8. 93 * <p> 94 * Modes such as Authenticated Encryption with Associated Data (AEAD) 95 * provide authenticity assurances for both confidential data and 96 * Additional Associated Data (AAD) that is not encrypted. (Please see 97 * <a href="http://www.ietf.org/rfc/rfc5116.txt"> RFC 5116 </a> for more 98 * information on AEAD and AAD algorithms such as GCM/CCM.) Both 99 * confidential and AAD data can be used when calculating the 100 * authentication tag (similar to a {@link Mac}). This tag is appended 101 * to the ciphertext during encryption, and is verified on decryption. 102 * <p> 103 * AEAD modes such as GCM/CCM perform all AAD authenticity calculations 104 * before starting the ciphertext authenticity calculations. To avoid 105 * implementations having to internally buffer ciphertext, all AAD data 106 * must be supplied to GCM/CCM implementations (via the {@code updateAAD} 107 * methods) <b>before</b> the ciphertext is processed (via 108 * the {@code update} and {@code doFinal} methods). 109 * <p> 110 * Note that GCM mode has a uniqueness requirement on IVs used in 111 * encryption with a given key. When IVs are repeated for GCM 112 * encryption, such usages are subject to forgery attacks. Thus, after 113 * each encryption operation using GCM mode, callers should re-initialize 114 * the cipher objects with GCM parameters which have a different IV value. 115 * <pre> 116 * GCMParameterSpec s = ...; 117 * cipher.init(..., s); 118 * 119 * // If the GCM parameters were generated by the provider, it can 120 * // be retrieved by: 121 * // cipher.getParameters().getParameterSpec(GCMParameterSpec.class); 122 * 123 * cipher.updateAAD(...); // AAD 124 * cipher.update(...); // Multi-part update 125 * cipher.doFinal(...); // conclusion of operation 126 * 127 * // Use a different IV value for every encryption 128 * byte[] newIv = ...; 129 * s = new GCMParameterSpec(s.getTLen(), newIv); 130 * cipher.init(..., s); 131 * ... 132 * 133 * </pre> 134 * The ChaCha20 and ChaCha20-Poly1305 algorithms have a similar requirement 135 * for unique nonces with a given key. After each encryption or decryption 136 * operation, callers should re-initialize their ChaCha20 or ChaCha20-Poly1305 137 * ciphers with parameters that specify a different nonce value. Please 138 * see <a href="https://tools.ietf.org/html/rfc7539">RFC 7539</a> for more 139 * information on the ChaCha20 and ChaCha20-Poly1305 algorithms. 140 * <p> 141 * Every implementation of the Java platform is required to support 142 * the following standard {@code Cipher} transformations with the keysizes 143 * in parentheses: 144 * <ul> 145 * <li>{@code AES/CBC/NoPadding} (128)</li> 146 * <li>{@code AES/CBC/PKCS5Padding} (128)</li> 147 * <li>{@code AES/ECB/NoPadding} (128)</li> 148 * <li>{@code AES/ECB/PKCS5Padding} (128)</li> 149 * <li>{@code AES/GCM/NoPadding} (128)</li> 150 * <li>{@code DES/CBC/NoPadding} (56)</li> 151 * <li>{@code DES/CBC/PKCS5Padding} (56)</li> 152 * <li>{@code DES/ECB/NoPadding} (56)</li> 153 * <li>{@code DES/ECB/PKCS5Padding} (56)</li> 154 * <li>{@code DESede/CBC/NoPadding} (168)</li> 155 * <li>{@code DESede/CBC/PKCS5Padding} (168)</li> 156 * <li>{@code DESede/ECB/NoPadding} (168)</li> 157 * <li>{@code DESede/ECB/PKCS5Padding} (168)</li> 158 * <li>{@code RSA/ECB/PKCS1Padding} (1024, 2048)</li> 159 * <li>{@code RSA/ECB/OAEPWithSHA-1AndMGF1Padding} (1024, 2048)</li> 160 * <li>{@code RSA/ECB/OAEPWithSHA-256AndMGF1Padding} (1024, 2048)</li> 161 * </ul> 162 * These transformations are described in the 163 * <a href="{@docRoot}/../specs/security/standard-names.html#cipher-algorithm-names"> 164 * Cipher section</a> of the 165 * Java Security Standard Algorithm Names Specification. 166 * Consult the release documentation for your implementation to see if any 167 * other transformations are supported. 168 * 169 * @author Jan Luehe 170 * @see KeyGenerator 171 * @see SecretKey 172 * @since 1.4 173 */ 174 175 public class Cipher { 176 177 private static final Debug debug = 178 Debug.getInstance("jca", "Cipher"); 179 180 private static final Debug pdebug = 181 Debug.getInstance("provider", "Provider"); 182 private static final boolean skipDebug = 183 Debug.isOn("engine=") && !Debug.isOn("cipher"); 184 185 /** 186 * Constant used to initialize cipher to encryption mode. 187 */ 188 public static final int ENCRYPT_MODE = 1; 189 190 /** 191 * Constant used to initialize cipher to decryption mode. 192 */ 193 public static final int DECRYPT_MODE = 2; 194 195 /** 196 * Constant used to initialize cipher to key-wrapping mode. 197 */ 198 public static final int WRAP_MODE = 3; 199 200 /** 201 * Constant used to initialize cipher to key-unwrapping mode. 202 */ 203 public static final int UNWRAP_MODE = 4; 204 205 /** 206 * Constant used to indicate the to-be-unwrapped key is a "public key". 207 */ 208 public static final int PUBLIC_KEY = 1; 209 210 /** 211 * Constant used to indicate the to-be-unwrapped key is a "private key". 212 */ 213 public static final int PRIVATE_KEY = 2; 214 215 /** 216 * Constant used to indicate the to-be-unwrapped key is a "secret key". 217 */ 218 public static final int SECRET_KEY = 3; 219 220 // The provider 221 private Provider provider; 222 223 // The provider implementation (delegate) 224 private CipherSpi spi; 225 226 // The transformation 227 private String transformation; 228 229 // Crypto permission representing the maximum allowable cryptographic 230 // strength that this Cipher object can be used for. (The cryptographic 231 // strength is a function of the keysize and algorithm parameters encoded 232 // in the crypto permission.) 233 private CryptoPermission cryptoPerm; 234 235 // The exemption mechanism that needs to be enforced 236 private ExemptionMechanism exmech; 237 238 // Flag which indicates whether or not this cipher has been initialized 239 private boolean initialized = false; 240 241 // The operation mode - store the operation mode after the 242 // cipher has been initialized. 243 private int opmode = 0; 244 245 // The OID for the KeyUsage extension in an X.509 v3 certificate 246 private static final String KEY_USAGE_EXTENSION_OID = "2.5.29.15"; 247 248 // next SPI to try in provider selection 249 // null once provider is selected 250 private CipherSpi firstSpi; 251 252 // next service to try in provider selection 253 // null once provider is selected 254 private Service firstService; 255 256 // remaining services to try in provider selection 257 // null once provider is selected 258 private Iterator<Service> serviceIterator; 259 260 // list of transform Strings to lookup in the provider 261 private List<Transform> transforms; 262 263 private final Object lock; 264 265 /** 266 * Creates a Cipher object. 267 * 268 * @param cipherSpi the delegate 269 * @param provider the provider 270 * @param transformation the transformation 271 */ 272 protected Cipher(CipherSpi cipherSpi, 273 Provider provider, 274 String transformation) { 275 // See bug 4341369 & 4334690 for more info. 276 // If the caller is trusted, then okay. 277 // Otherwise throw a NullPointerException. 278 if (!JceSecurityManager.INSTANCE.isCallerTrusted(provider)) { 279 throw new NullPointerException(); 280 } 281 this.spi = cipherSpi; 282 this.provider = provider; 283 this.transformation = transformation; 284 this.cryptoPerm = CryptoAllPermission.INSTANCE; 285 this.lock = null; 286 } 287 288 /** 289 * Creates a Cipher object. Called internally and by NullCipher. 290 * 291 * @param cipherSpi the delegate 292 * @param transformation the transformation 293 */ 294 Cipher(CipherSpi cipherSpi, String transformation) { 295 this.spi = cipherSpi; 296 this.transformation = transformation; 297 this.cryptoPerm = CryptoAllPermission.INSTANCE; 298 this.lock = null; 299 } 300 301 private Cipher(CipherSpi firstSpi, Service firstService, 302 Iterator<Service> serviceIterator, String transformation, 303 List<Transform> transforms) { 304 this.firstSpi = firstSpi; 305 this.firstService = firstService; 306 this.serviceIterator = serviceIterator; 307 this.transforms = transforms; 308 this.transformation = transformation; 309 this.lock = new Object(); 310 } 311 312 private static String[] tokenizeTransformation(String transformation) 313 throws NoSuchAlgorithmException { 314 if (transformation == null) { 315 throw new NoSuchAlgorithmException("No transformation given"); 316 } 317 /* 318 * array containing the components of a Cipher transformation: 319 * 320 * index 0: algorithm component (e.g., AES) 321 * index 1: feedback component (e.g., CFB) 322 * index 2: padding component (e.g., PKCS5Padding) 323 */ 324 String[] parts = new String[3]; 325 int count = 0; 326 StringTokenizer parser = new StringTokenizer(transformation, "/"); 327 try { 328 while (parser.hasMoreTokens() && count < 3) { 329 parts[count++] = parser.nextToken().trim(); 330 } 331 if (count == 0 || count == 2) { 332 throw new NoSuchAlgorithmException("Invalid transformation" 333 + " format:" + 334 transformation); 335 } 336 // treats all subsequent tokens as part of padding 337 if (count == 3 && parser.hasMoreTokens()) { 338 parts[2] = parts[2] + parser.nextToken("\r\n"); 339 } 340 } catch (NoSuchElementException e) { 341 throw new NoSuchAlgorithmException("Invalid transformation " + 342 "format:" + transformation); 343 } 344 if ((parts[0] == null) || (parts[0].length() == 0)) { 345 throw new NoSuchAlgorithmException("Invalid transformation:" + 346 "algorithm not specified-" 347 + transformation); 348 } 349 return parts; 350 } 351 352 // Provider attribute name for supported chaining mode 353 private static final String ATTR_MODE = "SupportedModes"; 354 // Provider attribute name for supported padding names 355 private static final String ATTR_PAD = "SupportedPaddings"; 356 357 // constants indicating whether the provider supports 358 // a given mode or padding 359 private static final int S_NO = 0; // does not support 360 private static final int S_MAYBE = 1; // unable to determine 361 private static final int S_YES = 2; // does support 362 363 /** 364 * Nested class to deal with modes and paddings. 365 */ 366 private static class Transform { 367 // transform string to lookup in the provider 368 final String transform; 369 // the mode/padding suffix in upper case. for example, if the algorithm 370 // to lookup is "AES/CBC/PKCS5Padding" suffix is "/CBC/PKCS5PADDING" 371 // if lookup is "AES", suffix is the empty string 372 // needed because aliases prevent straight transform.equals() 373 final String suffix; 374 // value to pass to setMode() or null if no such call required 375 final String mode; 376 // value to pass to setPadding() or null if no such call required 377 final String pad; 378 Transform(String alg, String suffix, String mode, String pad) { 379 this.transform = alg + suffix; 380 this.suffix = suffix.toUpperCase(Locale.ENGLISH); 381 this.mode = mode; 382 this.pad = pad; 383 } 384 // set mode and padding for the given SPI 385 void setModePadding(CipherSpi spi) throws NoSuchAlgorithmException, 386 NoSuchPaddingException { 387 if (mode != null) { 388 spi.engineSetMode(mode); 389 } 390 if (pad != null) { 391 spi.engineSetPadding(pad); 392 } 393 } 394 // check whether the given services supports the mode and 395 // padding described by this Transform 396 int supportsModePadding(Service s) { 397 int smode = supportsMode(s); 398 if (smode == S_NO) { 399 return smode; 400 } 401 int spad = supportsPadding(s); 402 // our constants are defined so that Math.min() is a tri-valued AND 403 return Math.min(smode, spad); 404 } 405 406 // separate methods for mode and padding 407 // called directly by Cipher only to throw the correct exception 408 int supportsMode(Service s) { 409 return supports(s, ATTR_MODE, mode); 410 } 411 int supportsPadding(Service s) { 412 return supports(s, ATTR_PAD, pad); 413 } 414 415 private static int supports(Service s, String attrName, String value) { 416 if (value == null) { 417 return S_YES; 418 } 419 String regexp = s.getAttribute(attrName); 420 if (regexp == null) { 421 return S_MAYBE; 422 } 423 return matches(regexp, value) ? S_YES : S_NO; 424 } 425 426 // ConcurrentMap<String,Pattern> for previously compiled patterns 427 private static final ConcurrentMap<String, Pattern> patternCache = 428 new ConcurrentHashMap<String, Pattern>(); 429 430 private static boolean matches(String regexp, String str) { 431 Pattern pattern = patternCache.get(regexp); 432 if (pattern == null) { 433 pattern = Pattern.compile(regexp); 434 patternCache.putIfAbsent(regexp, pattern); 435 } 436 return pattern.matcher(str.toUpperCase(Locale.ENGLISH)).matches(); 437 } 438 439 } 440 441 private static List<Transform> getTransforms(String transformation) 442 throws NoSuchAlgorithmException { 443 String[] parts = tokenizeTransformation(transformation); 444 445 String alg = parts[0]; 446 String mode = parts[1]; 447 String pad = parts[2]; 448 if ((mode != null) && (mode.length() == 0)) { 449 mode = null; 450 } 451 if ((pad != null) && (pad.length() == 0)) { 452 pad = null; 453 } 454 455 if ((mode == null) && (pad == null)) { 456 // AES 457 Transform tr = new Transform(alg, "", null, null); 458 return Collections.singletonList(tr); 459 } else { // if ((mode != null) && (pad != null)) { 460 // AES/CBC/PKCS5Padding 461 List<Transform> list = new ArrayList<>(4); 462 list.add(new Transform(alg, "/" + mode + "/" + pad, null, null)); 463 list.add(new Transform(alg, "/" + mode, null, pad)); 464 list.add(new Transform(alg, "//" + pad, mode, null)); 465 list.add(new Transform(alg, "", mode, pad)); 466 return list; 467 } 468 } 469 470 // get the transform matching the specified service 471 private static Transform getTransform(Service s, 472 List<Transform> transforms) { 473 String alg = s.getAlgorithm().toUpperCase(Locale.ENGLISH); 474 for (Transform tr : transforms) { 475 if (alg.endsWith(tr.suffix)) { 476 return tr; 477 } 478 } 479 return null; 480 } 481 482 /** 483 * Returns a {@code Cipher} object that implements the specified 484 * transformation. 485 * 486 * <p> This method traverses the list of registered security Providers, 487 * starting with the most preferred Provider. 488 * A new Cipher object encapsulating the 489 * CipherSpi implementation from the first 490 * Provider that supports the specified algorithm is returned. 491 * 492 * <p> Note that the list of registered providers may be retrieved via 493 * the {@link Security#getProviders() Security.getProviders()} method. 494 * 495 * @implNote 496 * The JDK Reference Implementation additionally uses the 497 * {@code jdk.security.provider.preferred} 498 * {@link Security#getProperty(String) Security} property to determine 499 * the preferred provider order for the specified algorithm. This 500 * may be different than the order of providers returned by 501 * {@link Security#getProviders() Security.getProviders()}. 502 * 503 * @param transformation the name of the transformation, e.g., 504 * <i>AES/CBC/PKCS5Padding</i>. 505 * See the Cipher section in the <a href= 506 * "{@docRoot}/../specs/security/standard-names.html#cipher-algorithm-names"> 507 * Java Security Standard Algorithm Names Specification</a> 508 * for information about standard transformation names. 509 * 510 * @return a cipher that implements the requested transformation 511 * 512 * @throws NoSuchAlgorithmException if {@code transformation} 513 * is {@code null}, empty, in an invalid format, 514 * or if no {@code Provider} supports a {@code CipherSpi} 515 * implementation for the specified algorithm 516 * 517 * @throws NoSuchPaddingException if {@code transformation} 518 * contains a padding scheme that is not available 519 * 520 * @see java.security.Provider 521 */ 522 public static final Cipher getInstance(String transformation) 523 throws NoSuchAlgorithmException, NoSuchPaddingException 524 { 525 if ((transformation == null) || transformation.equals("")) { 526 throw new NoSuchAlgorithmException("Null or empty transformation"); 527 } 528 List<Transform> transforms = getTransforms(transformation); 529 List<ServiceId> cipherServices = new ArrayList<>(transforms.size()); 530 for (Transform transform : transforms) { 531 cipherServices.add(new ServiceId("Cipher", transform.transform)); 532 } 533 List<Service> services = GetInstance.getServices(cipherServices); 534 // make sure there is at least one service from a signed provider 535 // and that it can use the specified mode and padding 536 Iterator<Service> t = services.iterator(); 537 Exception failure = null; 538 while (t.hasNext()) { 539 Service s = t.next(); 540 if (JceSecurity.canUseProvider(s.getProvider()) == false) { 541 continue; 542 } 543 Transform tr = getTransform(s, transforms); 544 if (tr == null) { 545 // should never happen 546 continue; 547 } 548 int canuse = tr.supportsModePadding(s); 549 if (canuse == S_NO) { 550 // does not support mode or padding we need, ignore 551 continue; 552 } 553 if (canuse == S_YES) { 554 return new Cipher(null, s, t, transformation, transforms); 555 } else { // S_MAYBE, try out if it works 556 try { 557 CipherSpi spi = (CipherSpi)s.newInstance(null); 558 tr.setModePadding(spi); 559 return new Cipher(spi, s, t, transformation, transforms); 560 } catch (Exception e) { 561 failure = e; 562 } 563 } 564 } 565 throw new NoSuchAlgorithmException 566 ("Cannot find any provider supporting " + transformation, failure); 567 } 568 569 /** 570 * Returns a {@code Cipher} object that implements the specified 571 * transformation. 572 * 573 * <p> A new Cipher object encapsulating the 574 * CipherSpi implementation from the specified provider 575 * is returned. The specified provider must be registered 576 * in the security provider list. 577 * 578 * <p> Note that the list of registered providers may be retrieved via 579 * the {@link Security#getProviders() Security.getProviders()} method. 580 * 581 * @param transformation the name of the transformation, 582 * e.g., <i>AES/CBC/PKCS5Padding</i>. 583 * See the Cipher section in the <a href= 584 * "{@docRoot}/../specs/security/standard-names.html#cipher-algorithm-names"> 585 * Java Security Standard Algorithm Names Specification</a> 586 * for information about standard transformation names. 587 * 588 * @param provider the name of the provider. 589 * 590 * @return a cipher that implements the requested transformation 591 * 592 * @throws IllegalArgumentException if the {@code provider} 593 * is {@code null} or empty 594 * 595 * @throws NoSuchAlgorithmException if {@code transformation} 596 * is {@code null}, empty, in an invalid format, 597 * or if a {@code CipherSpi} implementation for the 598 * specified algorithm is not available from the specified 599 * provider 600 * 601 * @throws NoSuchPaddingException if {@code transformation} 602 * contains a padding scheme that is not available 603 * 604 * @throws NoSuchProviderException if the specified provider is not 605 * registered in the security provider list 606 * 607 * @see java.security.Provider 608 */ 609 public static final Cipher getInstance(String transformation, 610 String provider) 611 throws NoSuchAlgorithmException, NoSuchProviderException, 612 NoSuchPaddingException 613 { 614 if ((transformation == null) || transformation.equals("")) { 615 throw new NoSuchAlgorithmException("Null or empty transformation"); 616 } 617 if ((provider == null) || (provider.length() == 0)) { 618 throw new IllegalArgumentException("Missing provider"); 619 } 620 Provider p = Security.getProvider(provider); 621 if (p == null) { 622 throw new NoSuchProviderException("No such provider: " + 623 provider); 624 } 625 return getInstance(transformation, p); 626 } 627 628 private String getProviderName() { 629 return (provider == null) ? "(no provider)" : provider.getName(); 630 } 631 632 /** 633 * Returns a {@code Cipher} object that implements the specified 634 * transformation. 635 * 636 * <p> A new Cipher object encapsulating the 637 * CipherSpi implementation from the specified Provider 638 * object is returned. Note that the specified Provider object 639 * does not have to be registered in the provider list. 640 * 641 * @param transformation the name of the transformation, 642 * e.g., <i>AES/CBC/PKCS5Padding</i>. 643 * See the Cipher section in the <a href= 644 * "{@docRoot}/../specs/security/standard-names.html#cipher-algorithm-names"> 645 * Java Security Standard Algorithm Names Specification</a> 646 * for information about standard transformation names. 647 * 648 * @param provider the provider. 649 * 650 * @return a cipher that implements the requested transformation 651 * 652 * @throws IllegalArgumentException if the {@code provider} 653 * is {@code null} 654 * 655 * @throws NoSuchAlgorithmException if {@code transformation} 656 * is {@code null}, empty, in an invalid format, 657 * or if a {@code CipherSpi} implementation for the 658 * specified algorithm is not available from the specified 659 * {@code Provider} object 660 * 661 * @throws NoSuchPaddingException if {@code transformation} 662 * contains a padding scheme that is not available 663 * 664 * @see java.security.Provider 665 */ 666 public static final Cipher getInstance(String transformation, 667 Provider provider) 668 throws NoSuchAlgorithmException, NoSuchPaddingException 669 { 670 if ((transformation == null) || transformation.equals("")) { 671 throw new NoSuchAlgorithmException("Null or empty transformation"); 672 } 673 if (provider == null) { 674 throw new IllegalArgumentException("Missing provider"); 675 } 676 Exception failure = null; 677 List<Transform> transforms = getTransforms(transformation); 678 boolean providerChecked = false; 679 String paddingError = null; 680 for (Transform tr : transforms) { 681 Service s = provider.getService("Cipher", tr.transform); 682 if (s == null) { 683 continue; 684 } 685 if (providerChecked == false) { 686 // for compatibility, first do the lookup and then verify 687 // the provider. this makes the difference between a NSAE 688 // and a SecurityException if the 689 // provider does not support the algorithm. 690 Exception ve = JceSecurity.getVerificationResult(provider); 691 if (ve != null) { 692 String msg = "JCE cannot authenticate the provider " 693 + provider.getName(); 694 throw new SecurityException(msg, ve); 695 } 696 providerChecked = true; 697 } 698 if (tr.supportsMode(s) == S_NO) { 699 continue; 700 } 701 if (tr.supportsPadding(s) == S_NO) { 702 paddingError = tr.pad; 703 continue; 704 } 705 try { 706 CipherSpi spi = (CipherSpi)s.newInstance(null); 707 tr.setModePadding(spi); 708 Cipher cipher = new Cipher(spi, transformation); 709 cipher.provider = s.getProvider(); 710 cipher.initCryptoPermission(); 711 return cipher; 712 } catch (Exception e) { 713 failure = e; 714 } 715 } 716 717 // throw NoSuchPaddingException if the problem is with padding 718 if (failure instanceof NoSuchPaddingException) { 719 throw (NoSuchPaddingException)failure; 720 } 721 if (paddingError != null) { 722 throw new NoSuchPaddingException 723 ("Padding not supported: " + paddingError); 724 } 725 throw new NoSuchAlgorithmException 726 ("No such algorithm: " + transformation, failure); 727 } 728 729 // If the requested crypto service is export-controlled, 730 // determine the maximum allowable keysize. 731 private void initCryptoPermission() throws NoSuchAlgorithmException { 732 if (JceSecurity.isRestricted() == false) { 733 cryptoPerm = CryptoAllPermission.INSTANCE; 734 exmech = null; 735 return; 736 } 737 cryptoPerm = getConfiguredPermission(transformation); 738 // Instantiate the exemption mechanism (if required) 739 String exmechName = cryptoPerm.getExemptionMechanism(); 740 if (exmechName != null) { 741 exmech = ExemptionMechanism.getInstance(exmechName); 742 } 743 } 744 745 // max number of debug warnings to print from chooseFirstProvider() 746 private static int warnCount = 10; 747 748 /** 749 * Choose the Spi from the first provider available. Used if 750 * delayed provider selection is not possible because init() 751 * is not the first method called. 752 */ 753 void chooseFirstProvider() { 754 if (spi != null) { 755 return; 756 } 757 synchronized (lock) { 758 if (spi != null) { 759 return; 760 } 761 if (debug != null) { 762 int w = --warnCount; 763 if (w >= 0) { 764 debug.println("Cipher.init() not first method " 765 + "called, disabling delayed provider selection"); 766 if (w == 0) { 767 debug.println("Further warnings of this type will " 768 + "be suppressed"); 769 } 770 new Exception("Call trace").printStackTrace(); 771 } 772 } 773 Exception lastException = null; 774 while ((firstService != null) || serviceIterator.hasNext()) { 775 Service s; 776 CipherSpi thisSpi; 777 if (firstService != null) { 778 s = firstService; 779 thisSpi = firstSpi; 780 firstService = null; 781 firstSpi = null; 782 } else { 783 s = serviceIterator.next(); 784 thisSpi = null; 785 } 786 if (JceSecurity.canUseProvider(s.getProvider()) == false) { 787 continue; 788 } 789 Transform tr = getTransform(s, transforms); 790 if (tr == null) { 791 // should never happen 792 continue; 793 } 794 if (tr.supportsModePadding(s) == S_NO) { 795 continue; 796 } 797 try { 798 if (thisSpi == null) { 799 Object obj = s.newInstance(null); 800 if (obj instanceof CipherSpi == false) { 801 continue; 802 } 803 thisSpi = (CipherSpi)obj; 804 } 805 tr.setModePadding(thisSpi); 806 initCryptoPermission(); 807 spi = thisSpi; 808 provider = s.getProvider(); 809 // not needed any more 810 firstService = null; 811 serviceIterator = null; 812 transforms = null; 813 return; 814 } catch (Exception e) { 815 lastException = e; 816 } 817 } 818 ProviderException e = new ProviderException 819 ("Could not construct CipherSpi instance"); 820 if (lastException != null) { 821 e.initCause(lastException); 822 } 823 throw e; 824 } 825 } 826 827 private static final int I_KEY = 1; 828 private static final int I_PARAMSPEC = 2; 829 private static final int I_PARAMS = 3; 830 private static final int I_CERT = 4; 831 832 private void implInit(CipherSpi thisSpi, int type, int opmode, Key key, 833 AlgorithmParameterSpec paramSpec, AlgorithmParameters params, 834 SecureRandom random) throws InvalidKeyException, 835 InvalidAlgorithmParameterException { 836 switch (type) { 837 case I_KEY: 838 checkCryptoPerm(thisSpi, key); 839 thisSpi.engineInit(opmode, key, random); 840 break; 841 case I_PARAMSPEC: 842 checkCryptoPerm(thisSpi, key, paramSpec); 843 thisSpi.engineInit(opmode, key, paramSpec, random); 844 break; 845 case I_PARAMS: 846 checkCryptoPerm(thisSpi, key, params); 847 thisSpi.engineInit(opmode, key, params, random); 848 break; 849 case I_CERT: 850 checkCryptoPerm(thisSpi, key); 851 thisSpi.engineInit(opmode, key, random); 852 break; 853 default: 854 throw new AssertionError("Internal Cipher error: " + type); 855 } 856 } 857 858 private void chooseProvider(int initType, int opmode, Key key, 859 AlgorithmParameterSpec paramSpec, 860 AlgorithmParameters params, SecureRandom random) 861 throws InvalidKeyException, InvalidAlgorithmParameterException { 862 synchronized (lock) { 863 if (spi != null) { 864 implInit(spi, initType, opmode, key, paramSpec, params, random); 865 return; 866 } 867 Exception lastException = null; 868 while ((firstService != null) || serviceIterator.hasNext()) { 869 Service s; 870 CipherSpi thisSpi; 871 if (firstService != null) { 872 s = firstService; 873 thisSpi = firstSpi; 874 firstService = null; 875 firstSpi = null; 876 } else { 877 s = serviceIterator.next(); 878 thisSpi = null; 879 } 880 // if provider says it does not support this key, ignore it 881 if (s.supportsParameter(key) == false) { 882 continue; 883 } 884 if (JceSecurity.canUseProvider(s.getProvider()) == false) { 885 continue; 886 } 887 Transform tr = getTransform(s, transforms); 888 if (tr == null) { 889 // should never happen 890 continue; 891 } 892 if (tr.supportsModePadding(s) == S_NO) { 893 continue; 894 } 895 try { 896 if (thisSpi == null) { 897 thisSpi = (CipherSpi)s.newInstance(null); 898 } 899 tr.setModePadding(thisSpi); 900 initCryptoPermission(); 901 implInit(thisSpi, initType, opmode, key, paramSpec, 902 params, random); 903 provider = s.getProvider(); 904 this.spi = thisSpi; 905 firstService = null; 906 serviceIterator = null; 907 transforms = null; 908 return; 909 } catch (Exception e) { 910 // NoSuchAlgorithmException from newInstance() 911 // InvalidKeyException from init() 912 // RuntimeException (ProviderException) from init() 913 // SecurityException from crypto permission check 914 if (lastException == null) { 915 lastException = e; 916 } 917 } 918 } 919 // no working provider found, fail 920 if (lastException instanceof InvalidKeyException) { 921 throw (InvalidKeyException)lastException; 922 } 923 if (lastException instanceof InvalidAlgorithmParameterException) { 924 throw (InvalidAlgorithmParameterException)lastException; 925 } 926 if (lastException instanceof RuntimeException) { 927 throw (RuntimeException)lastException; 928 } 929 String kName = (key != null) ? key.getClass().getName() : "(null)"; 930 throw new InvalidKeyException 931 ("No installed provider supports this key: " 932 + kName, lastException); 933 } 934 } 935 936 /** 937 * Returns the provider of this {@code Cipher} object. 938 * 939 * @return the provider of this {@code Cipher} object 940 */ 941 public final Provider getProvider() { 942 chooseFirstProvider(); 943 return this.provider; 944 } 945 946 /** 947 * Returns the algorithm name of this {@code Cipher} object. 948 * 949 * <p>This is the same name that was specified in one of the 950 * {@code getInstance} calls that created this {@code Cipher} 951 * object.. 952 * 953 * @return the algorithm name of this {@code Cipher} object. 954 */ 955 public final String getAlgorithm() { 956 return this.transformation; 957 } 958 959 /** 960 * Returns the block size (in bytes). 961 * 962 * @return the block size (in bytes), or 0 if the underlying algorithm is 963 * not a block cipher 964 */ 965 public final int getBlockSize() { 966 chooseFirstProvider(); 967 return spi.engineGetBlockSize(); 968 } 969 970 /** 971 * Returns the length in bytes that an output buffer would need to be in 972 * order to hold the result of the next {@code update} or 973 * {@code doFinal} operation, given the input length 974 * {@code inputLen} (in bytes). 975 * 976 * <p>This call takes into account any unprocessed (buffered) data from a 977 * previous {@code update} call, padding, and AEAD tagging. 978 * 979 * <p>The actual output length of the next {@code update} or 980 * {@code doFinal} call may be smaller than the length returned by 981 * this method. 982 * 983 * @param inputLen the input length (in bytes) 984 * 985 * @return the required output buffer size (in bytes) 986 * 987 * @exception IllegalStateException if this cipher is in a wrong state 988 * (e.g., has not yet been initialized) 989 */ 990 public final int getOutputSize(int inputLen) { 991 992 if (!initialized && !(this instanceof NullCipher)) { 993 throw new IllegalStateException("Cipher not initialized"); 994 } 995 if (inputLen < 0) { 996 throw new IllegalArgumentException("Input size must be equal " + 997 "to or greater than zero"); 998 } 999 chooseFirstProvider(); 1000 return spi.engineGetOutputSize(inputLen); 1001 } 1002 1003 /** 1004 * Returns the initialization vector (IV) in a new buffer. 1005 * 1006 * <p>This is useful in the case where a random IV was created, 1007 * or in the context of password-based encryption or 1008 * decryption, where the IV is derived from a user-supplied password. 1009 * 1010 * @return the initialization vector in a new buffer, or null if the 1011 * underlying algorithm does not use an IV, or if the IV has not yet 1012 * been set. 1013 */ 1014 public final byte[] getIV() { 1015 chooseFirstProvider(); 1016 return spi.engineGetIV(); 1017 } 1018 1019 /** 1020 * Returns the parameters used with this cipher. 1021 * 1022 * <p>The returned parameters may be the same that were used to initialize 1023 * this cipher, or may contain a combination of default and random 1024 * parameter values used by the underlying cipher implementation if this 1025 * cipher requires algorithm parameters but was not initialized with any. 1026 * 1027 * @return the parameters used with this cipher, or null if this cipher 1028 * does not use any parameters. 1029 */ 1030 public final AlgorithmParameters getParameters() { 1031 chooseFirstProvider(); 1032 return spi.engineGetParameters(); 1033 } 1034 1035 /** 1036 * Returns the exemption mechanism object used with this cipher. 1037 * 1038 * @return the exemption mechanism object used with this cipher, or 1039 * null if this cipher does not use any exemption mechanism. 1040 */ 1041 public final ExemptionMechanism getExemptionMechanism() { 1042 chooseFirstProvider(); 1043 return exmech; 1044 } 1045 1046 // 1047 // Crypto permission check code below 1048 // 1049 private void checkCryptoPerm(CipherSpi checkSpi, Key key) 1050 throws InvalidKeyException { 1051 if (cryptoPerm == CryptoAllPermission.INSTANCE) { 1052 return; 1053 } 1054 // Check if key size and default parameters are within legal limits 1055 AlgorithmParameterSpec params; 1056 try { 1057 params = getAlgorithmParameterSpec(checkSpi.engineGetParameters()); 1058 } catch (InvalidParameterSpecException ipse) { 1059 throw new InvalidKeyException 1060 ("Unsupported default algorithm parameters"); 1061 } 1062 if (!passCryptoPermCheck(checkSpi, key, params)) { 1063 throw new InvalidKeyException( 1064 "Illegal key size or default parameters"); 1065 } 1066 } 1067 1068 private void checkCryptoPerm(CipherSpi checkSpi, Key key, 1069 AlgorithmParameterSpec params) throws InvalidKeyException, 1070 InvalidAlgorithmParameterException { 1071 if (cryptoPerm == CryptoAllPermission.INSTANCE) { 1072 return; 1073 } 1074 // Determine keysize and check if it is within legal limits 1075 if (!passCryptoPermCheck(checkSpi, key, null)) { 1076 throw new InvalidKeyException("Illegal key size"); 1077 } 1078 if ((params != null) && (!passCryptoPermCheck(checkSpi, key, params))) { 1079 throw new InvalidAlgorithmParameterException("Illegal parameters"); 1080 } 1081 } 1082 1083 private void checkCryptoPerm(CipherSpi checkSpi, Key key, 1084 AlgorithmParameters params) 1085 throws InvalidKeyException, InvalidAlgorithmParameterException { 1086 if (cryptoPerm == CryptoAllPermission.INSTANCE) { 1087 return; 1088 } 1089 // Convert the specified parameters into specs and then delegate. 1090 AlgorithmParameterSpec pSpec; 1091 try { 1092 pSpec = getAlgorithmParameterSpec(params); 1093 } catch (InvalidParameterSpecException ipse) { 1094 throw new InvalidAlgorithmParameterException 1095 ("Failed to retrieve algorithm parameter specification"); 1096 } 1097 checkCryptoPerm(checkSpi, key, pSpec); 1098 } 1099 1100 private boolean passCryptoPermCheck(CipherSpi checkSpi, Key key, 1101 AlgorithmParameterSpec params) 1102 throws InvalidKeyException { 1103 String em = cryptoPerm.getExemptionMechanism(); 1104 int keySize = checkSpi.engineGetKeySize(key); 1105 // Use the "algorithm" component of the cipher 1106 // transformation so that the perm check would 1107 // work when the key has the "aliased" algo. 1108 String algComponent; 1109 int index = transformation.indexOf('/'); 1110 if (index != -1) { 1111 algComponent = transformation.substring(0, index); 1112 } else { 1113 algComponent = transformation; 1114 } 1115 CryptoPermission checkPerm = 1116 new CryptoPermission(algComponent, keySize, params, em); 1117 1118 if (!cryptoPerm.implies(checkPerm)) { 1119 if (debug != null) { 1120 debug.println("Crypto Permission check failed"); 1121 debug.println("granted: " + cryptoPerm); 1122 debug.println("requesting: " + checkPerm); 1123 } 1124 return false; 1125 } 1126 if (exmech == null) { 1127 return true; 1128 } 1129 try { 1130 if (!exmech.isCryptoAllowed(key)) { 1131 if (debug != null) { 1132 debug.println(exmech.getName() + " isn't enforced"); 1133 } 1134 return false; 1135 } 1136 } catch (ExemptionMechanismException eme) { 1137 if (debug != null) { 1138 debug.println("Cannot determine whether "+ 1139 exmech.getName() + " has been enforced"); 1140 eme.printStackTrace(); 1141 } 1142 return false; 1143 } 1144 return true; 1145 } 1146 1147 // check if opmode is one of the defined constants 1148 // throw InvalidParameterExeption if not 1149 private static void checkOpmode(int opmode) { 1150 if ((opmode < ENCRYPT_MODE) || (opmode > UNWRAP_MODE)) { 1151 throw new InvalidParameterException("Invalid operation mode"); 1152 } 1153 } 1154 1155 private static String getOpmodeString(int opmode) { 1156 switch (opmode) { 1157 case ENCRYPT_MODE: 1158 return "encryption"; 1159 case DECRYPT_MODE: 1160 return "decryption"; 1161 case WRAP_MODE: 1162 return "key wrapping"; 1163 case UNWRAP_MODE: 1164 return "key unwrapping"; 1165 default: 1166 return ""; 1167 } 1168 } 1169 1170 /** 1171 * Initializes this cipher with a key. 1172 * 1173 * <p>The cipher is initialized for one of the following four operations: 1174 * encryption, decryption, key wrapping or key unwrapping, depending 1175 * on the value of {@code opmode}. 1176 * 1177 * <p>If this cipher requires any algorithm parameters that cannot be 1178 * derived from the given {@code key}, the underlying cipher 1179 * implementation is supposed to generate the required parameters itself 1180 * (using provider-specific default or random values) if it is being 1181 * initialized for encryption or key wrapping, and raise an 1182 * {@code InvalidKeyException} if it is being 1183 * initialized for decryption or key unwrapping. 1184 * The generated parameters can be retrieved using 1185 * {@link #getParameters() getParameters} or 1186 * {@link #getIV() getIV} (if the parameter is an IV). 1187 * 1188 * <p>If this cipher requires algorithm parameters that cannot be 1189 * derived from the input parameters, and there are no reasonable 1190 * provider-specific default values, initialization will 1191 * necessarily fail. 1192 * 1193 * <p>If this cipher (including its underlying feedback or padding scheme) 1194 * requires any random bytes (e.g., for parameter generation), it will get 1195 * them using the {@link java.security.SecureRandom} 1196 * implementation of the highest-priority 1197 * installed provider as the source of randomness. 1198 * (If none of the installed providers supply an implementation of 1199 * SecureRandom, a system-provided source of randomness will be used.) 1200 * 1201 * <p>Note that when a Cipher object is initialized, it loses all 1202 * previously-acquired state. In other words, initializing a Cipher is 1203 * equivalent to creating a new instance of that Cipher and initializing 1204 * it. 1205 * 1206 * @param opmode the operation mode of this cipher (this is one of 1207 * the following: 1208 * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, 1209 * {@code WRAP_MODE} or {@code UNWRAP_MODE}) 1210 * @param key the key 1211 * 1212 * @exception InvalidKeyException if the given key is inappropriate for 1213 * initializing this cipher, or requires 1214 * algorithm parameters that cannot be 1215 * determined from the given key, or if the given key has a keysize that 1216 * exceeds the maximum allowable keysize (as determined from the 1217 * configured jurisdiction policy files). 1218 * @throws UnsupportedOperationException if {@code opmode} is 1219 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1220 * by the underlying {@code CipherSpi}. 1221 */ 1222 public final void init(int opmode, Key key) throws InvalidKeyException { 1223 init(opmode, key, JceSecurity.RANDOM); 1224 } 1225 1226 /** 1227 * Initializes this cipher with a key and a source of randomness. 1228 * 1229 * <p>The cipher is initialized for one of the following four operations: 1230 * encryption, decryption, key wrapping or key unwrapping, depending 1231 * on the value of {@code opmode}. 1232 * 1233 * <p>If this cipher requires any algorithm parameters that cannot be 1234 * derived from the given {@code key}, the underlying cipher 1235 * implementation is supposed to generate the required parameters itself 1236 * (using provider-specific default or random values) if it is being 1237 * initialized for encryption or key wrapping, and raise an 1238 * {@code InvalidKeyException} if it is being 1239 * initialized for decryption or key unwrapping. 1240 * The generated parameters can be retrieved using 1241 * {@link #getParameters() getParameters} or 1242 * {@link #getIV() getIV} (if the parameter is an IV). 1243 * 1244 * <p>If this cipher requires algorithm parameters that cannot be 1245 * derived from the input parameters, and there are no reasonable 1246 * provider-specific default values, initialization will 1247 * necessarily fail. 1248 * 1249 * <p>If this cipher (including its underlying feedback or padding scheme) 1250 * requires any random bytes (e.g., for parameter generation), it will get 1251 * them from {@code random}. 1252 * 1253 * <p>Note that when a Cipher object is initialized, it loses all 1254 * previously-acquired state. In other words, initializing a Cipher is 1255 * equivalent to creating a new instance of that Cipher and initializing 1256 * it. 1257 * 1258 * @param opmode the operation mode of this cipher (this is one of the 1259 * following: 1260 * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, 1261 * {@code WRAP_MODE} or {@code UNWRAP_MODE}) 1262 * @param key the encryption key 1263 * @param random the source of randomness 1264 * 1265 * @exception InvalidKeyException if the given key is inappropriate for 1266 * initializing this cipher, or requires 1267 * algorithm parameters that cannot be 1268 * determined from the given key, or if the given key has a keysize that 1269 * exceeds the maximum allowable keysize (as determined from the 1270 * configured jurisdiction policy files). 1271 * @throws UnsupportedOperationException if {@code opmode} is 1272 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1273 * by the underlying {@code CipherSpi}. 1274 */ 1275 public final void init(int opmode, Key key, SecureRandom random) 1276 throws InvalidKeyException 1277 { 1278 initialized = false; 1279 checkOpmode(opmode); 1280 1281 if (spi != null) { 1282 checkCryptoPerm(spi, key); 1283 spi.engineInit(opmode, key, random); 1284 } else { 1285 try { 1286 chooseProvider(I_KEY, opmode, key, null, null, random); 1287 } catch (InvalidAlgorithmParameterException e) { 1288 // should never occur 1289 throw new InvalidKeyException(e); 1290 } 1291 } 1292 1293 initialized = true; 1294 this.opmode = opmode; 1295 1296 if (!skipDebug && pdebug != null) { 1297 pdebug.println("Cipher." + transformation + " " + 1298 getOpmodeString(opmode) + " algorithm from: " + 1299 getProviderName()); 1300 } 1301 } 1302 1303 /** 1304 * Initializes this cipher with a key and a set of algorithm 1305 * parameters. 1306 * 1307 * <p>The cipher is initialized for one of the following four operations: 1308 * encryption, decryption, key wrapping or key unwrapping, depending 1309 * on the value of {@code opmode}. 1310 * 1311 * <p>If this cipher requires any algorithm parameters and 1312 * {@code params} is null, the underlying cipher implementation is 1313 * supposed to generate the required parameters itself (using 1314 * provider-specific default or random values) if it is being 1315 * initialized for encryption or key wrapping, and raise an 1316 * {@code InvalidAlgorithmParameterException} if it is being 1317 * initialized for decryption or key unwrapping. 1318 * The generated parameters can be retrieved using 1319 * {@link #getParameters() getParameters} or 1320 * {@link #getIV() getIV} (if the parameter is an IV). 1321 * 1322 * <p>If this cipher requires algorithm parameters that cannot be 1323 * derived from the input parameters, and there are no reasonable 1324 * provider-specific default values, initialization will 1325 * necessarily fail. 1326 * 1327 * <p>If this cipher (including its underlying feedback or padding scheme) 1328 * requires any random bytes (e.g., for parameter generation), it will get 1329 * them using the {@link java.security.SecureRandom} 1330 * implementation of the highest-priority 1331 * installed provider as the source of randomness. 1332 * (If none of the installed providers supply an implementation of 1333 * SecureRandom, a system-provided source of randomness will be used.) 1334 * 1335 * <p>Note that when a Cipher object is initialized, it loses all 1336 * previously-acquired state. In other words, initializing a Cipher is 1337 * equivalent to creating a new instance of that Cipher and initializing 1338 * it. 1339 * 1340 * @param opmode the operation mode of this cipher (this is one of the 1341 * following: 1342 * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, 1343 * {@code WRAP_MODE} or {@code UNWRAP_MODE}) 1344 * @param key the encryption key 1345 * @param params the algorithm parameters 1346 * 1347 * @exception InvalidKeyException if the given key is inappropriate for 1348 * initializing this cipher, or its keysize exceeds the maximum allowable 1349 * keysize (as determined from the configured jurisdiction policy files). 1350 * @exception InvalidAlgorithmParameterException if the given algorithm 1351 * parameters are inappropriate for this cipher, 1352 * or this cipher requires 1353 * algorithm parameters and {@code params} is null, or the given 1354 * algorithm parameters imply a cryptographic strength that would exceed 1355 * the legal limits (as determined from the configured jurisdiction 1356 * policy files). 1357 * @throws UnsupportedOperationException if {@code opmode} is 1358 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1359 * by the underlying {@code CipherSpi}. 1360 */ 1361 public final void init(int opmode, Key key, AlgorithmParameterSpec params) 1362 throws InvalidKeyException, InvalidAlgorithmParameterException 1363 { 1364 init(opmode, key, params, JceSecurity.RANDOM); 1365 } 1366 1367 /** 1368 * Initializes this cipher with a key, a set of algorithm 1369 * parameters, and a source of randomness. 1370 * 1371 * <p>The cipher is initialized for one of the following four operations: 1372 * encryption, decryption, key wrapping or key unwrapping, depending 1373 * on the value of {@code opmode}. 1374 * 1375 * <p>If this cipher requires any algorithm parameters and 1376 * {@code params} is null, the underlying cipher implementation is 1377 * supposed to generate the required parameters itself (using 1378 * provider-specific default or random values) if it is being 1379 * initialized for encryption or key wrapping, and raise an 1380 * {@code InvalidAlgorithmParameterException} if it is being 1381 * initialized for decryption or key unwrapping. 1382 * The generated parameters can be retrieved using 1383 * {@link #getParameters() getParameters} or 1384 * {@link #getIV() getIV} (if the parameter is an IV). 1385 * 1386 * <p>If this cipher requires algorithm parameters that cannot be 1387 * derived from the input parameters, and there are no reasonable 1388 * provider-specific default values, initialization will 1389 * necessarily fail. 1390 * 1391 * <p>If this cipher (including its underlying feedback or padding scheme) 1392 * requires any random bytes (e.g., for parameter generation), it will get 1393 * them from {@code random}. 1394 * 1395 * <p>Note that when a Cipher object is initialized, it loses all 1396 * previously-acquired state. In other words, initializing a Cipher is 1397 * equivalent to creating a new instance of that Cipher and initializing 1398 * it. 1399 * 1400 * @param opmode the operation mode of this cipher (this is one of the 1401 * following: 1402 * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, 1403 * {@code WRAP_MODE} or {@code UNWRAP_MODE}) 1404 * @param key the encryption key 1405 * @param params the algorithm parameters 1406 * @param random the source of randomness 1407 * 1408 * @exception InvalidKeyException if the given key is inappropriate for 1409 * initializing this cipher, or its keysize exceeds the maximum allowable 1410 * keysize (as determined from the configured jurisdiction policy files). 1411 * @exception InvalidAlgorithmParameterException if the given algorithm 1412 * parameters are inappropriate for this cipher, 1413 * or this cipher requires 1414 * algorithm parameters and {@code params} is null, or the given 1415 * algorithm parameters imply a cryptographic strength that would exceed 1416 * the legal limits (as determined from the configured jurisdiction 1417 * policy files). 1418 * @throws UnsupportedOperationException if {@code opmode} is 1419 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1420 * by the underlying {@code CipherSpi}. 1421 */ 1422 public final void init(int opmode, Key key, AlgorithmParameterSpec params, 1423 SecureRandom random) 1424 throws InvalidKeyException, InvalidAlgorithmParameterException 1425 { 1426 initialized = false; 1427 checkOpmode(opmode); 1428 1429 if (spi != null) { 1430 checkCryptoPerm(spi, key, params); 1431 spi.engineInit(opmode, key, params, random); 1432 } else { 1433 chooseProvider(I_PARAMSPEC, opmode, key, params, null, random); 1434 } 1435 1436 initialized = true; 1437 this.opmode = opmode; 1438 1439 if (!skipDebug && pdebug != null) { 1440 pdebug.println("Cipher." + transformation + " " + 1441 getOpmodeString(opmode) + " algorithm from: " + 1442 getProviderName()); 1443 } 1444 } 1445 1446 /** 1447 * Initializes this cipher with a key and a set of algorithm 1448 * parameters. 1449 * 1450 * <p>The cipher is initialized for one of the following four operations: 1451 * encryption, decryption, key wrapping or key unwrapping, depending 1452 * on the value of {@code opmode}. 1453 * 1454 * <p>If this cipher requires any algorithm parameters and 1455 * {@code params} is null, the underlying cipher implementation is 1456 * supposed to generate the required parameters itself (using 1457 * provider-specific default or random values) if it is being 1458 * initialized for encryption or key wrapping, and raise an 1459 * {@code InvalidAlgorithmParameterException} if it is being 1460 * initialized for decryption or key unwrapping. 1461 * The generated parameters can be retrieved using 1462 * {@link #getParameters() getParameters} or 1463 * {@link #getIV() getIV} (if the parameter is an IV). 1464 * 1465 * <p>If this cipher requires algorithm parameters that cannot be 1466 * derived from the input parameters, and there are no reasonable 1467 * provider-specific default values, initialization will 1468 * necessarily fail. 1469 * 1470 * <p>If this cipher (including its underlying feedback or padding scheme) 1471 * requires any random bytes (e.g., for parameter generation), it will get 1472 * them using the {@link java.security.SecureRandom} 1473 * implementation of the highest-priority 1474 * installed provider as the source of randomness. 1475 * (If none of the installed providers supply an implementation of 1476 * SecureRandom, a system-provided source of randomness will be used.) 1477 * 1478 * <p>Note that when a Cipher object is initialized, it loses all 1479 * previously-acquired state. In other words, initializing a Cipher is 1480 * equivalent to creating a new instance of that Cipher and initializing 1481 * it. 1482 * 1483 * @param opmode the operation mode of this cipher (this is one of the 1484 * following: {@code ENCRYPT_MODE}, 1485 * {@code DECRYPT_MODE}, {@code WRAP_MODE} 1486 * or {@code UNWRAP_MODE}) 1487 * @param key the encryption key 1488 * @param params the algorithm parameters 1489 * 1490 * @exception InvalidKeyException if the given key is inappropriate for 1491 * initializing this cipher, or its keysize exceeds the maximum allowable 1492 * keysize (as determined from the configured jurisdiction policy files). 1493 * @exception InvalidAlgorithmParameterException if the given algorithm 1494 * parameters are inappropriate for this cipher, 1495 * or this cipher requires 1496 * algorithm parameters and {@code params} is null, or the given 1497 * algorithm parameters imply a cryptographic strength that would exceed 1498 * the legal limits (as determined from the configured jurisdiction 1499 * policy files). 1500 * @throws UnsupportedOperationException if {@code opmode} is 1501 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1502 * by the underlying {@code CipherSpi}. 1503 */ 1504 public final void init(int opmode, Key key, AlgorithmParameters params) 1505 throws InvalidKeyException, InvalidAlgorithmParameterException 1506 { 1507 init(opmode, key, params, JceSecurity.RANDOM); 1508 } 1509 1510 /** 1511 * Initializes this cipher with a key, a set of algorithm 1512 * parameters, and a source of randomness. 1513 * 1514 * <p>The cipher is initialized for one of the following four operations: 1515 * encryption, decryption, key wrapping or key unwrapping, depending 1516 * on the value of {@code opmode}. 1517 * 1518 * <p>If this cipher requires any algorithm parameters and 1519 * {@code params} is null, the underlying cipher implementation is 1520 * supposed to generate the required parameters itself (using 1521 * provider-specific default or random values) if it is being 1522 * initialized for encryption or key wrapping, and raise an 1523 * {@code InvalidAlgorithmParameterException} if it is being 1524 * initialized for decryption or key unwrapping. 1525 * The generated parameters can be retrieved using 1526 * {@link #getParameters() getParameters} or 1527 * {@link #getIV() getIV} (if the parameter is an IV). 1528 * 1529 * <p>If this cipher requires algorithm parameters that cannot be 1530 * derived from the input parameters, and there are no reasonable 1531 * provider-specific default values, initialization will 1532 * necessarily fail. 1533 * 1534 * <p>If this cipher (including its underlying feedback or padding scheme) 1535 * requires any random bytes (e.g., for parameter generation), it will get 1536 * them from {@code random}. 1537 * 1538 * <p>Note that when a Cipher object is initialized, it loses all 1539 * previously-acquired state. In other words, initializing a Cipher is 1540 * equivalent to creating a new instance of that Cipher and initializing 1541 * it. 1542 * 1543 * @param opmode the operation mode of this cipher (this is one of the 1544 * following: {@code ENCRYPT_MODE}, 1545 * {@code DECRYPT_MODE}, {@code WRAP_MODE} 1546 * or {@code UNWRAP_MODE}) 1547 * @param key the encryption key 1548 * @param params the algorithm parameters 1549 * @param random the source of randomness 1550 * 1551 * @exception InvalidKeyException if the given key is inappropriate for 1552 * initializing this cipher, or its keysize exceeds the maximum allowable 1553 * keysize (as determined from the configured jurisdiction policy files). 1554 * @exception InvalidAlgorithmParameterException if the given algorithm 1555 * parameters are inappropriate for this cipher, 1556 * or this cipher requires 1557 * algorithm parameters and {@code params} is null, or the given 1558 * algorithm parameters imply a cryptographic strength that would exceed 1559 * the legal limits (as determined from the configured jurisdiction 1560 * policy files). 1561 * @throws UnsupportedOperationException if {@code opmode} is 1562 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1563 * by the underlying {@code CipherSpi}. 1564 */ 1565 public final void init(int opmode, Key key, AlgorithmParameters params, 1566 SecureRandom random) 1567 throws InvalidKeyException, InvalidAlgorithmParameterException 1568 { 1569 initialized = false; 1570 checkOpmode(opmode); 1571 1572 if (spi != null) { 1573 checkCryptoPerm(spi, key, params); 1574 spi.engineInit(opmode, key, params, random); 1575 } else { 1576 chooseProvider(I_PARAMS, opmode, key, null, params, random); 1577 } 1578 1579 initialized = true; 1580 this.opmode = opmode; 1581 1582 if (!skipDebug && pdebug != null) { 1583 pdebug.println("Cipher." + transformation + " " + 1584 getOpmodeString(opmode) + " algorithm from: " + 1585 getProviderName()); 1586 } 1587 } 1588 1589 /** 1590 * Initializes this cipher with the public key from the given certificate. 1591 * <p> The cipher is initialized for one of the following four operations: 1592 * encryption, decryption, key wrapping or key unwrapping, depending 1593 * on the value of {@code opmode}. 1594 * 1595 * <p>If the certificate is of type X.509 and has a <i>key usage</i> 1596 * extension field marked as critical, and the value of the <i>key usage</i> 1597 * extension field implies that the public key in 1598 * the certificate and its corresponding private key are not 1599 * supposed to be used for the operation represented by the value 1600 * of {@code opmode}, 1601 * an {@code InvalidKeyException} 1602 * is thrown. 1603 * 1604 * <p> If this cipher requires any algorithm parameters that cannot be 1605 * derived from the public key in the given certificate, the underlying 1606 * cipher 1607 * implementation is supposed to generate the required parameters itself 1608 * (using provider-specific default or random values) if it is being 1609 * initialized for encryption or key wrapping, and raise an 1610 * {@code InvalidKeyException} if it is being initialized for decryption or 1611 * key unwrapping. 1612 * The generated parameters can be retrieved using 1613 * {@link #getParameters() getParameters} or 1614 * {@link #getIV() getIV} (if the parameter is an IV). 1615 * 1616 * <p>If this cipher requires algorithm parameters that cannot be 1617 * derived from the input parameters, and there are no reasonable 1618 * provider-specific default values, initialization will 1619 * necessarily fail. 1620 * 1621 * <p>If this cipher (including its underlying feedback or padding scheme) 1622 * requires any random bytes (e.g., for parameter generation), it will get 1623 * them using the 1624 * {@code SecureRandom} 1625 * implementation of the highest-priority 1626 * installed provider as the source of randomness. 1627 * (If none of the installed providers supply an implementation of 1628 * SecureRandom, a system-provided source of randomness will be used.) 1629 * 1630 * <p>Note that when a Cipher object is initialized, it loses all 1631 * previously-acquired state. In other words, initializing a Cipher is 1632 * equivalent to creating a new instance of that Cipher and initializing 1633 * it. 1634 * 1635 * @param opmode the operation mode of this cipher (this is one of the 1636 * following: 1637 * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, 1638 * {@code WRAP_MODE} or {@code UNWRAP_MODE}) 1639 * @param certificate the certificate 1640 * 1641 * @exception InvalidKeyException if the public key in the given 1642 * certificate is inappropriate for initializing this cipher, or this 1643 * cipher requires algorithm parameters that cannot be determined from the 1644 * public key in the given certificate, or the keysize of the public key 1645 * in the given certificate has a keysize that exceeds the maximum 1646 * allowable keysize (as determined by the configured jurisdiction policy 1647 * files). 1648 * @throws UnsupportedOperationException if {@code opmode} is 1649 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1650 * by the underlying {@code CipherSpi}. 1651 */ 1652 public final void init(int opmode, Certificate certificate) 1653 throws InvalidKeyException 1654 { 1655 init(opmode, certificate, JceSecurity.RANDOM); 1656 } 1657 1658 /** 1659 * Initializes this cipher with the public key from the given certificate 1660 * and 1661 * a source of randomness. 1662 * 1663 * <p>The cipher is initialized for one of the following four operations: 1664 * encryption, decryption, key wrapping 1665 * or key unwrapping, depending on 1666 * the value of {@code opmode}. 1667 * 1668 * <p>If the certificate is of type X.509 and has a <i>key usage</i> 1669 * extension field marked as critical, and the value of the <i>key usage</i> 1670 * extension field implies that the public key in 1671 * the certificate and its corresponding private key are not 1672 * supposed to be used for the operation represented by the value of 1673 * {@code opmode}, 1674 * an {@code InvalidKeyException} 1675 * is thrown. 1676 * 1677 * <p>If this cipher requires any algorithm parameters that cannot be 1678 * derived from the public key in the given {@code certificate}, 1679 * the underlying cipher 1680 * implementation is supposed to generate the required parameters itself 1681 * (using provider-specific default or random values) if it is being 1682 * initialized for encryption or key wrapping, and raise an 1683 * {@code InvalidKeyException} if it is being 1684 * initialized for decryption or key unwrapping. 1685 * The generated parameters can be retrieved using 1686 * {@link #getParameters() getParameters} or 1687 * {@link #getIV() getIV} (if the parameter is an IV). 1688 * 1689 * <p>If this cipher requires algorithm parameters that cannot be 1690 * derived from the input parameters, and there are no reasonable 1691 * provider-specific default values, initialization will 1692 * necessarily fail. 1693 * 1694 * <p>If this cipher (including its underlying feedback or padding scheme) 1695 * requires any random bytes (e.g., for parameter generation), it will get 1696 * them from {@code random}. 1697 * 1698 * <p>Note that when a Cipher object is initialized, it loses all 1699 * previously-acquired state. In other words, initializing a Cipher is 1700 * equivalent to creating a new instance of that Cipher and initializing 1701 * it. 1702 * 1703 * @param opmode the operation mode of this cipher (this is one of the 1704 * following: 1705 * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, 1706 * {@code WRAP_MODE} or {@code UNWRAP_MODE}) 1707 * @param certificate the certificate 1708 * @param random the source of randomness 1709 * 1710 * @exception InvalidKeyException if the public key in the given 1711 * certificate is inappropriate for initializing this cipher, or this 1712 * cipher 1713 * requires algorithm parameters that cannot be determined from the 1714 * public key in the given certificate, or the keysize of the public key 1715 * in the given certificate has a keysize that exceeds the maximum 1716 * allowable keysize (as determined by the configured jurisdiction policy 1717 * files). 1718 * @throws UnsupportedOperationException if {@code opmode} is 1719 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1720 * by the underlying {@code CipherSpi}. 1721 */ 1722 public final void init(int opmode, Certificate certificate, 1723 SecureRandom random) 1724 throws InvalidKeyException 1725 { 1726 initialized = false; 1727 checkOpmode(opmode); 1728 1729 // Check key usage if the certificate is of 1730 // type X.509. 1731 if (certificate instanceof java.security.cert.X509Certificate) { 1732 // Check whether the cert has a key usage extension 1733 // marked as a critical extension. 1734 X509Certificate cert = (X509Certificate)certificate; 1735 Set<String> critSet = cert.getCriticalExtensionOIDs(); 1736 1737 if (critSet != null && !critSet.isEmpty() 1738 && critSet.contains(KEY_USAGE_EXTENSION_OID)) { 1739 boolean[] keyUsageInfo = cert.getKeyUsage(); 1740 // keyUsageInfo[2] is for keyEncipherment; 1741 // keyUsageInfo[3] is for dataEncipherment. 1742 if ((keyUsageInfo != null) && 1743 (((opmode == Cipher.ENCRYPT_MODE) && 1744 (keyUsageInfo.length > 3) && 1745 (keyUsageInfo[3] == false)) || 1746 ((opmode == Cipher.WRAP_MODE) && 1747 (keyUsageInfo.length > 2) && 1748 (keyUsageInfo[2] == false)))) { 1749 throw new InvalidKeyException("Wrong key usage"); 1750 } 1751 } 1752 } 1753 1754 PublicKey publicKey = 1755 (certificate==null? null:certificate.getPublicKey()); 1756 1757 if (spi != null) { 1758 checkCryptoPerm(spi, publicKey); 1759 spi.engineInit(opmode, publicKey, random); 1760 } else { 1761 try { 1762 chooseProvider(I_CERT, opmode, publicKey, null, null, random); 1763 } catch (InvalidAlgorithmParameterException e) { 1764 // should never occur 1765 throw new InvalidKeyException(e); 1766 } 1767 } 1768 1769 initialized = true; 1770 this.opmode = opmode; 1771 1772 if (!skipDebug && pdebug != null) { 1773 pdebug.println("Cipher." + transformation + " " + 1774 getOpmodeString(opmode) + " algorithm from: " + 1775 getProviderName()); 1776 } 1777 } 1778 1779 /** 1780 * Ensures that Cipher is in a valid state for update() and doFinal() 1781 * calls - should be initialized and in ENCRYPT_MODE or DECRYPT_MODE. 1782 * @throws IllegalStateException if Cipher object is not in valid state. 1783 */ 1784 private void checkCipherState() { 1785 if (!(this instanceof NullCipher)) { 1786 if (!initialized) { 1787 throw new IllegalStateException("Cipher not initialized"); 1788 } 1789 if ((opmode != Cipher.ENCRYPT_MODE) && 1790 (opmode != Cipher.DECRYPT_MODE)) { 1791 throw new IllegalStateException("Cipher not initialized " + 1792 "for encryption/decryption"); 1793 } 1794 } 1795 } 1796 1797 /** 1798 * Continues a multiple-part encryption or decryption operation 1799 * (depending on how this cipher was initialized), processing another data 1800 * part. 1801 * 1802 * <p>The bytes in the {@code input} buffer are processed, and the 1803 * result is stored in a new buffer. 1804 * 1805 * <p>If {@code input} has a length of zero, this method returns 1806 * {@code null}. 1807 * 1808 * @param input the input buffer 1809 * 1810 * @return the new buffer with the result, or null if the underlying 1811 * cipher is a block cipher and the input data is too short to result in a 1812 * new block. 1813 * 1814 * @exception IllegalStateException if this cipher is in a wrong state 1815 * (e.g., has not been initialized) 1816 */ 1817 public final byte[] update(byte[] input) { 1818 checkCipherState(); 1819 1820 // Input sanity check 1821 if (input == null) { 1822 throw new IllegalArgumentException("Null input buffer"); 1823 } 1824 1825 chooseFirstProvider(); 1826 if (input.length == 0) { 1827 return null; 1828 } 1829 return spi.engineUpdate(input, 0, input.length); 1830 } 1831 1832 /** 1833 * Continues a multiple-part encryption or decryption operation 1834 * (depending on how this cipher was initialized), processing another data 1835 * part. 1836 * 1837 * <p>The first {@code inputLen} bytes in the {@code input} 1838 * buffer, starting at {@code inputOffset} inclusive, are processed, 1839 * and the result is stored in a new buffer. 1840 * 1841 * <p>If {@code inputLen} is zero, this method returns 1842 * {@code null}. 1843 * 1844 * @param input the input buffer 1845 * @param inputOffset the offset in {@code input} where the input 1846 * starts 1847 * @param inputLen the input length 1848 * 1849 * @return the new buffer with the result, or null if the underlying 1850 * cipher is a block cipher and the input data is too short to result in a 1851 * new block. 1852 * 1853 * @exception IllegalStateException if this cipher is in a wrong state 1854 * (e.g., has not been initialized) 1855 */ 1856 public final byte[] update(byte[] input, int inputOffset, int inputLen) { 1857 checkCipherState(); 1858 1859 // Input sanity check 1860 if (input == null || inputOffset < 0 1861 || inputLen > (input.length - inputOffset) || inputLen < 0) { 1862 throw new IllegalArgumentException("Bad arguments"); 1863 } 1864 1865 chooseFirstProvider(); 1866 if (inputLen == 0) { 1867 return null; 1868 } 1869 return spi.engineUpdate(input, inputOffset, inputLen); 1870 } 1871 1872 /** 1873 * Continues a multiple-part encryption or decryption operation 1874 * (depending on how this cipher was initialized), processing another data 1875 * part. 1876 * 1877 * <p>The first {@code inputLen} bytes in the {@code input} 1878 * buffer, starting at {@code inputOffset} inclusive, are processed, 1879 * and the result is stored in the {@code output} buffer. 1880 * 1881 * <p>If the {@code output} buffer is too small to hold the result, 1882 * a {@code ShortBufferException} is thrown. In this case, repeat this 1883 * call with a larger output buffer. Use 1884 * {@link #getOutputSize(int) getOutputSize} to determine how big 1885 * the output buffer should be. 1886 * 1887 * <p>If {@code inputLen} is zero, this method returns 1888 * a length of zero. 1889 * 1890 * <p>Note: this method should be copy-safe, which means the 1891 * {@code input} and {@code output} buffers can reference 1892 * the same byte array and no unprocessed input data is overwritten 1893 * when the result is copied into the output buffer. 1894 * 1895 * @param input the input buffer 1896 * @param inputOffset the offset in {@code input} where the input 1897 * starts 1898 * @param inputLen the input length 1899 * @param output the buffer for the result 1900 * 1901 * @return the number of bytes stored in {@code output} 1902 * 1903 * @exception IllegalStateException if this cipher is in a wrong state 1904 * (e.g., has not been initialized) 1905 * @exception ShortBufferException if the given output buffer is too small 1906 * to hold the result 1907 */ 1908 public final int update(byte[] input, int inputOffset, int inputLen, 1909 byte[] output) 1910 throws ShortBufferException { 1911 checkCipherState(); 1912 1913 // Input sanity check 1914 if (input == null || inputOffset < 0 1915 || inputLen > (input.length - inputOffset) || inputLen < 0) { 1916 throw new IllegalArgumentException("Bad arguments"); 1917 } 1918 1919 chooseFirstProvider(); 1920 if (inputLen == 0) { 1921 return 0; 1922 } 1923 return spi.engineUpdate(input, inputOffset, inputLen, 1924 output, 0); 1925 } 1926 1927 /** 1928 * Continues a multiple-part encryption or decryption operation 1929 * (depending on how this cipher was initialized), processing another data 1930 * part. 1931 * 1932 * <p>The first {@code inputLen} bytes in the {@code input} 1933 * buffer, starting at {@code inputOffset} inclusive, are processed, 1934 * and the result is stored in the {@code output} buffer, starting at 1935 * {@code outputOffset} inclusive. 1936 * 1937 * <p>If the {@code output} buffer is too small to hold the result, 1938 * a {@code ShortBufferException} is thrown. In this case, repeat this 1939 * call with a larger output buffer. Use 1940 * {@link #getOutputSize(int) getOutputSize} to determine how big 1941 * the output buffer should be. 1942 * 1943 * <p>If {@code inputLen} is zero, this method returns 1944 * a length of zero. 1945 * 1946 * <p>Note: this method should be copy-safe, which means the 1947 * {@code input} and {@code output} buffers can reference 1948 * the same byte array and no unprocessed input data is overwritten 1949 * when the result is copied into the output buffer. 1950 * 1951 * @param input the input buffer 1952 * @param inputOffset the offset in {@code input} where the input 1953 * starts 1954 * @param inputLen the input length 1955 * @param output the buffer for the result 1956 * @param outputOffset the offset in {@code output} where the result 1957 * is stored 1958 * 1959 * @return the number of bytes stored in {@code output} 1960 * 1961 * @exception IllegalStateException if this cipher is in a wrong state 1962 * (e.g., has not been initialized) 1963 * @exception ShortBufferException if the given output buffer is too small 1964 * to hold the result 1965 */ 1966 public final int update(byte[] input, int inputOffset, int inputLen, 1967 byte[] output, int outputOffset) 1968 throws ShortBufferException { 1969 checkCipherState(); 1970 1971 // Input sanity check 1972 if (input == null || inputOffset < 0 1973 || inputLen > (input.length - inputOffset) || inputLen < 0 1974 || outputOffset < 0) { 1975 throw new IllegalArgumentException("Bad arguments"); 1976 } 1977 1978 chooseFirstProvider(); 1979 if (inputLen == 0) { 1980 return 0; 1981 } 1982 return spi.engineUpdate(input, inputOffset, inputLen, 1983 output, outputOffset); 1984 } 1985 1986 /** 1987 * Continues a multiple-part encryption or decryption operation 1988 * (depending on how this cipher was initialized), processing another data 1989 * part. 1990 * 1991 * <p>All {@code input.remaining()} bytes starting at 1992 * {@code input.position()} are processed. The result is stored 1993 * in the output buffer. 1994 * Upon return, the input buffer's position will be equal 1995 * to its limit; its limit will not have changed. The output buffer's 1996 * position will have advanced by n, where n is the value returned 1997 * by this method; the output buffer's limit will not have changed. 1998 * 1999 * <p>If {@code output.remaining()} bytes are insufficient to 2000 * hold the result, a {@code ShortBufferException} is thrown. 2001 * In this case, repeat this call with a larger output buffer. Use 2002 * {@link #getOutputSize(int) getOutputSize} to determine how big 2003 * the output buffer should be. 2004 * 2005 * <p>Note: this method should be copy-safe, which means the 2006 * {@code input} and {@code output} buffers can reference 2007 * the same block of memory and no unprocessed input data is overwritten 2008 * when the result is copied into the output buffer. 2009 * 2010 * @param input the input ByteBuffer 2011 * @param output the output ByteByffer 2012 * 2013 * @return the number of bytes stored in {@code output} 2014 * 2015 * @exception IllegalStateException if this cipher is in a wrong state 2016 * (e.g., has not been initialized) 2017 * @exception IllegalArgumentException if input and output are the 2018 * same object 2019 * @exception ReadOnlyBufferException if the output buffer is read-only 2020 * @exception ShortBufferException if there is insufficient space in the 2021 * output buffer 2022 * @since 1.5 2023 */ 2024 public final int update(ByteBuffer input, ByteBuffer output) 2025 throws ShortBufferException { 2026 checkCipherState(); 2027 2028 if ((input == null) || (output == null)) { 2029 throw new IllegalArgumentException("Buffers must not be null"); 2030 } 2031 if (input == output) { 2032 throw new IllegalArgumentException("Input and output buffers must " 2033 + "not be the same object, consider using buffer.duplicate()"); 2034 } 2035 if (output.isReadOnly()) { 2036 throw new ReadOnlyBufferException(); 2037 } 2038 2039 chooseFirstProvider(); 2040 return spi.engineUpdate(input, output); 2041 } 2042 2043 /** 2044 * Finishes a multiple-part encryption or decryption operation, depending 2045 * on how this cipher was initialized. 2046 * 2047 * <p>Input data that may have been buffered during a previous 2048 * {@code update} operation is processed, with padding (if requested) 2049 * being applied. 2050 * If an AEAD mode such as GCM/CCM is being used, the authentication 2051 * tag is appended in the case of encryption, or verified in the 2052 * case of decryption. 2053 * The result is stored in a new buffer. 2054 * 2055 * <p>Upon finishing, this method resets this cipher object to the state 2056 * it was in when previously initialized via a call to {@code init}. 2057 * That is, the object is reset and available to encrypt or decrypt 2058 * (depending on the operation mode that was specified in the call to 2059 * {@code init}) more data. 2060 * 2061 * <p>Note: if any exception is thrown, this cipher object may need to 2062 * be reset before it can be used again. 2063 * 2064 * @return the new buffer with the result 2065 * 2066 * @exception IllegalStateException if this cipher is in a wrong state 2067 * (e.g., has not been initialized) 2068 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2069 * no padding has been requested (only in encryption mode), and the total 2070 * input length of the data processed by this cipher is not a multiple of 2071 * block size; or if this encryption algorithm is unable to 2072 * process the input data provided. 2073 * @exception BadPaddingException if this cipher is in decryption mode, 2074 * and (un)padding has been requested, but the decrypted data is not 2075 * bounded by the appropriate padding bytes 2076 * @exception AEADBadTagException if this cipher is decrypting in an 2077 * AEAD mode (such as GCM/CCM), and the received authentication tag 2078 * does not match the calculated value 2079 */ 2080 public final byte[] doFinal() 2081 throws IllegalBlockSizeException, BadPaddingException { 2082 checkCipherState(); 2083 2084 chooseFirstProvider(); 2085 return spi.engineDoFinal(null, 0, 0); 2086 } 2087 2088 /** 2089 * Finishes a multiple-part encryption or decryption operation, depending 2090 * on how this cipher was initialized. 2091 * 2092 * <p>Input data that may have been buffered during a previous 2093 * {@code update} operation is processed, with padding (if requested) 2094 * being applied. 2095 * If an AEAD mode such as GCM/CCM is being used, the authentication 2096 * tag is appended in the case of encryption, or verified in the 2097 * case of decryption. 2098 * The result is stored in the {@code output} buffer, starting at 2099 * {@code outputOffset} inclusive. 2100 * 2101 * <p>If the {@code output} buffer is too small to hold the result, 2102 * a {@code ShortBufferException} is thrown. In this case, repeat this 2103 * call with a larger output buffer. Use 2104 * {@link #getOutputSize(int) getOutputSize} to determine how big 2105 * the output buffer should be. 2106 * 2107 * <p>Upon finishing, this method resets this cipher object to the state 2108 * it was in when previously initialized via a call to {@code init}. 2109 * That is, the object is reset and available to encrypt or decrypt 2110 * (depending on the operation mode that was specified in the call to 2111 * {@code init}) more data. 2112 * 2113 * <p>Note: if any exception is thrown, this cipher object may need to 2114 * be reset before it can be used again. 2115 * 2116 * @param output the buffer for the result 2117 * @param outputOffset the offset in {@code output} where the result 2118 * is stored 2119 * 2120 * @return the number of bytes stored in {@code output} 2121 * 2122 * @exception IllegalStateException if this cipher is in a wrong state 2123 * (e.g., has not been initialized) 2124 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2125 * no padding has been requested (only in encryption mode), and the total 2126 * input length of the data processed by this cipher is not a multiple of 2127 * block size; or if this encryption algorithm is unable to 2128 * process the input data provided. 2129 * @exception ShortBufferException if the given output buffer is too small 2130 * to hold the result 2131 * @exception BadPaddingException if this cipher is in decryption mode, 2132 * and (un)padding has been requested, but the decrypted data is not 2133 * bounded by the appropriate padding bytes 2134 * @exception AEADBadTagException if this cipher is decrypting in an 2135 * AEAD mode (such as GCM/CCM), and the received authentication tag 2136 * does not match the calculated value 2137 */ 2138 public final int doFinal(byte[] output, int outputOffset) 2139 throws IllegalBlockSizeException, ShortBufferException, 2140 BadPaddingException { 2141 checkCipherState(); 2142 2143 // Input sanity check 2144 if ((output == null) || (outputOffset < 0)) { 2145 throw new IllegalArgumentException("Bad arguments"); 2146 } 2147 2148 chooseFirstProvider(); 2149 return spi.engineDoFinal(null, 0, 0, output, outputOffset); 2150 } 2151 2152 /** 2153 * Encrypts or decrypts data in a single-part operation, or finishes a 2154 * multiple-part operation. The data is encrypted or decrypted, 2155 * depending on how this cipher was initialized. 2156 * 2157 * <p>The bytes in the {@code input} buffer, and any input bytes that 2158 * may have been buffered during a previous {@code update} operation, 2159 * are processed, with padding (if requested) being applied. 2160 * If an AEAD mode such as GCM/CCM is being used, the authentication 2161 * tag is appended in the case of encryption, or verified in the 2162 * case of decryption. 2163 * The result is stored in a new buffer. 2164 * 2165 * <p>Upon finishing, this method resets this cipher object to the state 2166 * it was in when previously initialized via a call to {@code init}. 2167 * That is, the object is reset and available to encrypt or decrypt 2168 * (depending on the operation mode that was specified in the call to 2169 * {@code init}) more data. 2170 * 2171 * <p>Note: if any exception is thrown, this cipher object may need to 2172 * be reset before it can be used again. 2173 * 2174 * @param input the input buffer 2175 * 2176 * @return the new buffer with the result 2177 * 2178 * @exception IllegalStateException if this cipher is in a wrong state 2179 * (e.g., has not been initialized) 2180 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2181 * no padding has been requested (only in encryption mode), and the total 2182 * input length of the data processed by this cipher is not a multiple of 2183 * block size; or if this encryption algorithm is unable to 2184 * process the input data provided. 2185 * @exception BadPaddingException if this cipher is in decryption mode, 2186 * and (un)padding has been requested, but the decrypted data is not 2187 * bounded by the appropriate padding bytes 2188 * @exception AEADBadTagException if this cipher is decrypting in an 2189 * AEAD mode (such as GCM/CCM), and the received authentication tag 2190 * does not match the calculated value 2191 */ 2192 public final byte[] doFinal(byte[] input) 2193 throws IllegalBlockSizeException, BadPaddingException { 2194 checkCipherState(); 2195 2196 // Input sanity check 2197 if (input == null) { 2198 throw new IllegalArgumentException("Null input buffer"); 2199 } 2200 2201 chooseFirstProvider(); 2202 return spi.engineDoFinal(input, 0, input.length); 2203 } 2204 2205 /** 2206 * Encrypts or decrypts data in a single-part operation, or finishes a 2207 * multiple-part operation. The data is encrypted or decrypted, 2208 * depending on how this cipher was initialized. 2209 * 2210 * <p>The first {@code inputLen} bytes in the {@code input} 2211 * buffer, starting at {@code inputOffset} inclusive, and any input 2212 * bytes that may have been buffered during a previous {@code update} 2213 * operation, are processed, with padding (if requested) being applied. 2214 * If an AEAD mode such as GCM/CCM is being used, the authentication 2215 * tag is appended in the case of encryption, or verified in the 2216 * case of decryption. 2217 * The result is stored in a new buffer. 2218 * 2219 * <p>Upon finishing, this method resets this cipher object to the state 2220 * it was in when previously initialized via a call to {@code init}. 2221 * That is, the object is reset and available to encrypt or decrypt 2222 * (depending on the operation mode that was specified in the call to 2223 * {@code init}) more data. 2224 * 2225 * <p>Note: if any exception is thrown, this cipher object may need to 2226 * be reset before it can be used again. 2227 * 2228 * @param input the input buffer 2229 * @param inputOffset the offset in {@code input} where the input 2230 * starts 2231 * @param inputLen the input length 2232 * 2233 * @return the new buffer with the result 2234 * 2235 * @exception IllegalStateException if this cipher is in a wrong state 2236 * (e.g., has not been initialized) 2237 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2238 * no padding has been requested (only in encryption mode), and the total 2239 * input length of the data processed by this cipher is not a multiple of 2240 * block size; or if this encryption algorithm is unable to 2241 * process the input data provided. 2242 * @exception BadPaddingException if this cipher is in decryption mode, 2243 * and (un)padding has been requested, but the decrypted data is not 2244 * bounded by the appropriate padding bytes 2245 * @exception AEADBadTagException if this cipher is decrypting in an 2246 * AEAD mode (such as GCM/CCM), and the received authentication tag 2247 * does not match the calculated value 2248 */ 2249 public final byte[] doFinal(byte[] input, int inputOffset, int inputLen) 2250 throws IllegalBlockSizeException, BadPaddingException { 2251 checkCipherState(); 2252 2253 // Input sanity check 2254 if (input == null || inputOffset < 0 2255 || inputLen > (input.length - inputOffset) || inputLen < 0) { 2256 throw new IllegalArgumentException("Bad arguments"); 2257 } 2258 2259 chooseFirstProvider(); 2260 return spi.engineDoFinal(input, inputOffset, inputLen); 2261 } 2262 2263 /** 2264 * Encrypts or decrypts data in a single-part operation, or finishes a 2265 * multiple-part operation. The data is encrypted or decrypted, 2266 * depending on how this cipher was initialized. 2267 * 2268 * <p>The first {@code inputLen} bytes in the {@code input} 2269 * buffer, starting at {@code inputOffset} inclusive, and any input 2270 * bytes that may have been buffered during a previous {@code update} 2271 * operation, are processed, with padding (if requested) being applied. 2272 * If an AEAD mode such as GCM/CCM is being used, the authentication 2273 * tag is appended in the case of encryption, or verified in the 2274 * case of decryption. 2275 * The result is stored in the {@code output} buffer. 2276 * 2277 * <p>If the {@code output} buffer is too small to hold the result, 2278 * a {@code ShortBufferException} is thrown. In this case, repeat this 2279 * call with a larger output buffer. Use 2280 * {@link #getOutputSize(int) getOutputSize} to determine how big 2281 * the output buffer should be. 2282 * 2283 * <p>Upon finishing, this method resets this cipher object to the state 2284 * it was in when previously initialized via a call to {@code init}. 2285 * That is, the object is reset and available to encrypt or decrypt 2286 * (depending on the operation mode that was specified in the call to 2287 * {@code init}) more data. 2288 * 2289 * <p>Note: if any exception is thrown, this cipher object may need to 2290 * be reset before it can be used again. 2291 * 2292 * <p>Note: this method should be copy-safe, which means the 2293 * {@code input} and {@code output} buffers can reference 2294 * the same byte array and no unprocessed input data is overwritten 2295 * when the result is copied into the output buffer. 2296 * 2297 * @param input the input buffer 2298 * @param inputOffset the offset in {@code input} where the input 2299 * starts 2300 * @param inputLen the input length 2301 * @param output the buffer for the result 2302 * 2303 * @return the number of bytes stored in {@code output} 2304 * 2305 * @exception IllegalStateException if this cipher is in a wrong state 2306 * (e.g., has not been initialized) 2307 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2308 * no padding has been requested (only in encryption mode), and the total 2309 * input length of the data processed by this cipher is not a multiple of 2310 * block size; or if this encryption algorithm is unable to 2311 * process the input data provided. 2312 * @exception ShortBufferException if the given output buffer is too small 2313 * to hold the result 2314 * @exception BadPaddingException if this cipher is in decryption mode, 2315 * and (un)padding has been requested, but the decrypted data is not 2316 * bounded by the appropriate padding bytes 2317 * @exception AEADBadTagException if this cipher is decrypting in an 2318 * AEAD mode (such as GCM/CCM), and the received authentication tag 2319 * does not match the calculated value 2320 */ 2321 public final int doFinal(byte[] input, int inputOffset, int inputLen, 2322 byte[] output) 2323 throws ShortBufferException, IllegalBlockSizeException, 2324 BadPaddingException { 2325 checkCipherState(); 2326 2327 // Input sanity check 2328 if (input == null || inputOffset < 0 2329 || inputLen > (input.length - inputOffset) || inputLen < 0) { 2330 throw new IllegalArgumentException("Bad arguments"); 2331 } 2332 2333 chooseFirstProvider(); 2334 return spi.engineDoFinal(input, inputOffset, inputLen, 2335 output, 0); 2336 } 2337 2338 /** 2339 * Encrypts or decrypts data in a single-part operation, or finishes a 2340 * multiple-part operation. The data is encrypted or decrypted, 2341 * depending on how this cipher was initialized. 2342 * 2343 * <p>The first {@code inputLen} bytes in the {@code input} 2344 * buffer, starting at {@code inputOffset} inclusive, and any input 2345 * bytes that may have been buffered during a previous 2346 * {@code update} operation, are processed, with padding 2347 * (if requested) being applied. 2348 * If an AEAD mode such as GCM/CCM is being used, the authentication 2349 * tag is appended in the case of encryption, or verified in the 2350 * case of decryption. 2351 * The result is stored in the {@code output} buffer, starting at 2352 * {@code outputOffset} inclusive. 2353 * 2354 * <p>If the {@code output} buffer is too small to hold the result, 2355 * a {@code ShortBufferException} is thrown. In this case, repeat this 2356 * call with a larger output buffer. Use 2357 * {@link #getOutputSize(int) getOutputSize} to determine how big 2358 * the output buffer should be. 2359 * 2360 * <p>Upon finishing, this method resets this cipher object to the state 2361 * it was in when previously initialized via a call to {@code init}. 2362 * That is, the object is reset and available to encrypt or decrypt 2363 * (depending on the operation mode that was specified in the call to 2364 * {@code init}) more data. 2365 * 2366 * <p>Note: if any exception is thrown, this cipher object may need to 2367 * be reset before it can be used again. 2368 * 2369 * <p>Note: this method should be copy-safe, which means the 2370 * {@code input} and {@code output} buffers can reference 2371 * the same byte array and no unprocessed input data is overwritten 2372 * when the result is copied into the output buffer. 2373 * 2374 * @param input the input buffer 2375 * @param inputOffset the offset in {@code input} where the input 2376 * starts 2377 * @param inputLen the input length 2378 * @param output the buffer for the result 2379 * @param outputOffset the offset in {@code output} where the result 2380 * is stored 2381 * 2382 * @return the number of bytes stored in {@code output} 2383 * 2384 * @exception IllegalStateException if this cipher is in a wrong state 2385 * (e.g., has not been initialized) 2386 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2387 * no padding has been requested (only in encryption mode), and the total 2388 * input length of the data processed by this cipher is not a multiple of 2389 * block size; or if this encryption algorithm is unable to 2390 * process the input data provided. 2391 * @exception ShortBufferException if the given output buffer is too small 2392 * to hold the result 2393 * @exception BadPaddingException if this cipher is in decryption mode, 2394 * and (un)padding has been requested, but the decrypted data is not 2395 * bounded by the appropriate padding bytes 2396 * @exception AEADBadTagException if this cipher is decrypting in an 2397 * AEAD mode (such as GCM/CCM), and the received authentication tag 2398 * does not match the calculated value 2399 */ 2400 public final int doFinal(byte[] input, int inputOffset, int inputLen, 2401 byte[] output, int outputOffset) 2402 throws ShortBufferException, IllegalBlockSizeException, 2403 BadPaddingException { 2404 checkCipherState(); 2405 2406 // Input sanity check 2407 if (input == null || inputOffset < 0 2408 || inputLen > (input.length - inputOffset) || inputLen < 0 2409 || outputOffset < 0) { 2410 throw new IllegalArgumentException("Bad arguments"); 2411 } 2412 2413 chooseFirstProvider(); 2414 return spi.engineDoFinal(input, inputOffset, inputLen, 2415 output, outputOffset); 2416 } 2417 2418 /** 2419 * Encrypts or decrypts data in a single-part operation, or finishes a 2420 * multiple-part operation. The data is encrypted or decrypted, 2421 * depending on how this cipher was initialized. 2422 * 2423 * <p>All {@code input.remaining()} bytes starting at 2424 * {@code input.position()} are processed. 2425 * If an AEAD mode such as GCM/CCM is being used, the authentication 2426 * tag is appended in the case of encryption, or verified in the 2427 * case of decryption. 2428 * The result is stored in the output buffer. 2429 * Upon return, the input buffer's position will be equal 2430 * to its limit; its limit will not have changed. The output buffer's 2431 * position will have advanced by n, where n is the value returned 2432 * by this method; the output buffer's limit will not have changed. 2433 * 2434 * <p>If {@code output.remaining()} bytes are insufficient to 2435 * hold the result, a {@code ShortBufferException} is thrown. 2436 * In this case, repeat this call with a larger output buffer. Use 2437 * {@link #getOutputSize(int) getOutputSize} to determine how big 2438 * the output buffer should be. 2439 * 2440 * <p>Upon finishing, this method resets this cipher object to the state 2441 * it was in when previously initialized via a call to {@code init}. 2442 * That is, the object is reset and available to encrypt or decrypt 2443 * (depending on the operation mode that was specified in the call to 2444 * {@code init}) more data. 2445 * 2446 * <p>Note: if any exception is thrown, this cipher object may need to 2447 * be reset before it can be used again. 2448 * 2449 * <p>Note: this method should be copy-safe, which means the 2450 * {@code input} and {@code output} buffers can reference 2451 * the same byte array and no unprocessed input data is overwritten 2452 * when the result is copied into the output buffer. 2453 * 2454 * @param input the input ByteBuffer 2455 * @param output the output ByteBuffer 2456 * 2457 * @return the number of bytes stored in {@code output} 2458 * 2459 * @exception IllegalStateException if this cipher is in a wrong state 2460 * (e.g., has not been initialized) 2461 * @exception IllegalArgumentException if input and output are the 2462 * same object 2463 * @exception ReadOnlyBufferException if the output buffer is read-only 2464 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2465 * no padding has been requested (only in encryption mode), and the total 2466 * input length of the data processed by this cipher is not a multiple of 2467 * block size; or if this encryption algorithm is unable to 2468 * process the input data provided. 2469 * @exception ShortBufferException if there is insufficient space in the 2470 * output buffer 2471 * @exception BadPaddingException if this cipher is in decryption mode, 2472 * and (un)padding has been requested, but the decrypted data is not 2473 * bounded by the appropriate padding bytes 2474 * @exception AEADBadTagException if this cipher is decrypting in an 2475 * AEAD mode (such as GCM/CCM), and the received authentication tag 2476 * does not match the calculated value 2477 * 2478 * @since 1.5 2479 */ 2480 public final int doFinal(ByteBuffer input, ByteBuffer output) 2481 throws ShortBufferException, IllegalBlockSizeException, 2482 BadPaddingException { 2483 checkCipherState(); 2484 2485 if ((input == null) || (output == null)) { 2486 throw new IllegalArgumentException("Buffers must not be null"); 2487 } 2488 if (input == output) { 2489 throw new IllegalArgumentException("Input and output buffers must " 2490 + "not be the same object, consider using buffer.duplicate()"); 2491 } 2492 if (output.isReadOnly()) { 2493 throw new ReadOnlyBufferException(); 2494 } 2495 2496 chooseFirstProvider(); 2497 return spi.engineDoFinal(input, output); 2498 } 2499 2500 /** 2501 * Wrap a key. 2502 * 2503 * @param key the key to be wrapped. 2504 * 2505 * @return the wrapped key. 2506 * 2507 * @exception IllegalStateException if this cipher is in a wrong 2508 * state (e.g., has not been initialized). 2509 * 2510 * @exception IllegalBlockSizeException if this cipher is a block 2511 * cipher, no padding has been requested, and the length of the 2512 * encoding of the key to be wrapped is not a 2513 * multiple of the block size. 2514 * 2515 * @exception InvalidKeyException if it is impossible or unsafe to 2516 * wrap the key with this cipher (e.g., a hardware protected key is 2517 * being passed to a software-only cipher). 2518 * 2519 * @throws UnsupportedOperationException if the corresponding method in the 2520 * {@code CipherSpi} is not supported. 2521 */ 2522 public final byte[] wrap(Key key) 2523 throws IllegalBlockSizeException, InvalidKeyException { 2524 if (!(this instanceof NullCipher)) { 2525 if (!initialized) { 2526 throw new IllegalStateException("Cipher not initialized"); 2527 } 2528 if (opmode != Cipher.WRAP_MODE) { 2529 throw new IllegalStateException("Cipher not initialized " + 2530 "for wrapping keys"); 2531 } 2532 } 2533 2534 chooseFirstProvider(); 2535 return spi.engineWrap(key); 2536 } 2537 2538 /** 2539 * Unwrap a previously wrapped key. 2540 * 2541 * @param wrappedKey the key to be unwrapped. 2542 * 2543 * @param wrappedKeyAlgorithm the algorithm associated with the wrapped 2544 * key. 2545 * 2546 * @param wrappedKeyType the type of the wrapped key. This must be one of 2547 * {@code SECRET_KEY}, {@code PRIVATE_KEY}, or 2548 * {@code PUBLIC_KEY}. 2549 * 2550 * @return the unwrapped key. 2551 * 2552 * @exception IllegalStateException if this cipher is in a wrong state 2553 * (e.g., has not been initialized). 2554 * 2555 * @exception NoSuchAlgorithmException if no installed providers 2556 * can create keys of type {@code wrappedKeyType} for the 2557 * {@code wrappedKeyAlgorithm}. 2558 * 2559 * @exception InvalidKeyException if {@code wrappedKey} does not 2560 * represent a wrapped key of type {@code wrappedKeyType} for 2561 * the {@code wrappedKeyAlgorithm}. 2562 * 2563 * @throws UnsupportedOperationException if the corresponding method in the 2564 * {@code CipherSpi} is not supported. 2565 */ 2566 public final Key unwrap(byte[] wrappedKey, 2567 String wrappedKeyAlgorithm, 2568 int wrappedKeyType) 2569 throws InvalidKeyException, NoSuchAlgorithmException { 2570 2571 if (!(this instanceof NullCipher)) { 2572 if (!initialized) { 2573 throw new IllegalStateException("Cipher not initialized"); 2574 } 2575 if (opmode != Cipher.UNWRAP_MODE) { 2576 throw new IllegalStateException("Cipher not initialized " + 2577 "for unwrapping keys"); 2578 } 2579 } 2580 if ((wrappedKeyType != SECRET_KEY) && 2581 (wrappedKeyType != PRIVATE_KEY) && 2582 (wrappedKeyType != PUBLIC_KEY)) { 2583 throw new InvalidParameterException("Invalid key type"); 2584 } 2585 2586 chooseFirstProvider(); 2587 return spi.engineUnwrap(wrappedKey, 2588 wrappedKeyAlgorithm, 2589 wrappedKeyType); 2590 } 2591 2592 private AlgorithmParameterSpec getAlgorithmParameterSpec( 2593 AlgorithmParameters params) 2594 throws InvalidParameterSpecException { 2595 if (params == null) { 2596 return null; 2597 } 2598 2599 String alg = params.getAlgorithm().toUpperCase(Locale.ENGLISH); 2600 2601 if (alg.equalsIgnoreCase("RC2")) { 2602 return params.getParameterSpec(RC2ParameterSpec.class); 2603 } 2604 2605 if (alg.equalsIgnoreCase("RC5")) { 2606 return params.getParameterSpec(RC5ParameterSpec.class); 2607 } 2608 2609 if (alg.startsWith("PBE")) { 2610 return params.getParameterSpec(PBEParameterSpec.class); 2611 } 2612 2613 if (alg.startsWith("DES")) { 2614 return params.getParameterSpec(IvParameterSpec.class); 2615 } 2616 return null; 2617 } 2618 2619 private static CryptoPermission getConfiguredPermission( 2620 String transformation) throws NullPointerException, 2621 NoSuchAlgorithmException { 2622 if (transformation == null) throw new NullPointerException(); 2623 String[] parts = tokenizeTransformation(transformation); 2624 return JceSecurityManager.INSTANCE.getCryptoPermission(parts[0]); 2625 } 2626 2627 /** 2628 * Returns the maximum key length for the specified transformation 2629 * according to the installed JCE jurisdiction policy files. If 2630 * JCE unlimited strength jurisdiction policy files are installed, 2631 * Integer.MAX_VALUE will be returned. 2632 * For more information on the default key sizes and the JCE jurisdiction 2633 * policy files, please see the Cryptographic defaults and limitations in 2634 * the {@extLink security_guide_jdk_providers JDK Providers Documentation}. 2635 * 2636 * @param transformation the cipher transformation. 2637 * @return the maximum key length in bits or Integer.MAX_VALUE. 2638 * @exception NullPointerException if {@code transformation} is null. 2639 * @exception NoSuchAlgorithmException if {@code transformation} 2640 * is not a valid transformation, i.e. in the form of "algorithm" or 2641 * "algorithm/mode/padding". 2642 * @since 1.5 2643 */ 2644 public static final int getMaxAllowedKeyLength(String transformation) 2645 throws NoSuchAlgorithmException { 2646 CryptoPermission cp = getConfiguredPermission(transformation); 2647 return cp.getMaxKeySize(); 2648 } 2649 2650 /** 2651 * Returns an AlgorithmParameterSpec object which contains 2652 * the maximum cipher parameter value according to the 2653 * jurisdiction policy file. If JCE unlimited strength jurisdiction 2654 * policy files are installed or there is no maximum limit on the 2655 * parameters for the specified transformation in the policy file, 2656 * null will be returned. 2657 * 2658 * @param transformation the cipher transformation. 2659 * @return an AlgorithmParameterSpec which holds the maximum 2660 * value or null. 2661 * @exception NullPointerException if {@code transformation} 2662 * is null. 2663 * @exception NoSuchAlgorithmException if {@code transformation} 2664 * is not a valid transformation, i.e. in the form of "algorithm" or 2665 * "algorithm/mode/padding". 2666 * @since 1.5 2667 */ 2668 public static final AlgorithmParameterSpec getMaxAllowedParameterSpec( 2669 String transformation) throws NoSuchAlgorithmException { 2670 CryptoPermission cp = getConfiguredPermission(transformation); 2671 return cp.getAlgorithmParameterSpec(); 2672 } 2673 2674 /** 2675 * Continues a multi-part update of the Additional Authentication 2676 * Data (AAD). 2677 * <p> 2678 * Calls to this method provide AAD to the cipher when operating in 2679 * modes such as AEAD (GCM/CCM). If this cipher is operating in 2680 * either GCM or CCM mode, all AAD must be supplied before beginning 2681 * operations on the ciphertext (via the {@code update} and 2682 * {@code doFinal} methods). 2683 * 2684 * @param src the buffer containing the Additional Authentication Data 2685 * 2686 * @throws IllegalArgumentException if the {@code src} 2687 * byte array is null 2688 * @throws IllegalStateException if this cipher is in a wrong state 2689 * (e.g., has not been initialized), does not accept AAD, or if 2690 * operating in either GCM or CCM mode and one of the {@code update} 2691 * methods has already been called for the active 2692 * encryption/decryption operation 2693 * @throws UnsupportedOperationException if the corresponding method 2694 * in the {@code CipherSpi} has not been overridden by an 2695 * implementation 2696 * 2697 * @since 1.7 2698 */ 2699 public final void updateAAD(byte[] src) { 2700 if (src == null) { 2701 throw new IllegalArgumentException("src buffer is null"); 2702 } 2703 2704 updateAAD(src, 0, src.length); 2705 } 2706 2707 /** 2708 * Continues a multi-part update of the Additional Authentication 2709 * Data (AAD), using a subset of the provided buffer. 2710 * <p> 2711 * Calls to this method provide AAD to the cipher when operating in 2712 * modes such as AEAD (GCM/CCM). If this cipher is operating in 2713 * either GCM or CCM mode, all AAD must be supplied before beginning 2714 * operations on the ciphertext (via the {@code update} 2715 * and {@code doFinal} methods). 2716 * 2717 * @param src the buffer containing the AAD 2718 * @param offset the offset in {@code src} where the AAD input starts 2719 * @param len the number of AAD bytes 2720 * 2721 * @throws IllegalArgumentException if the {@code src} 2722 * byte array is null, or the {@code offset} or {@code length} 2723 * is less than 0, or the sum of the {@code offset} and 2724 * {@code len} is greater than the length of the 2725 * {@code src} byte array 2726 * @throws IllegalStateException if this cipher is in a wrong state 2727 * (e.g., has not been initialized), does not accept AAD, or if 2728 * operating in either GCM or CCM mode and one of the {@code update} 2729 * methods has already been called for the active 2730 * encryption/decryption operation 2731 * @throws UnsupportedOperationException if the corresponding method 2732 * in the {@code CipherSpi} has not been overridden by an 2733 * implementation 2734 * 2735 * @since 1.7 2736 */ 2737 public final void updateAAD(byte[] src, int offset, int len) { 2738 checkCipherState(); 2739 2740 // Input sanity check 2741 if ((src == null) || (offset < 0) || (len < 0) 2742 || len > (src.length - offset)) { 2743 throw new IllegalArgumentException("Bad arguments"); 2744 } 2745 2746 chooseFirstProvider(); 2747 if (len == 0) { 2748 return; 2749 } 2750 spi.engineUpdateAAD(src, offset, len); 2751 } 2752 2753 /** 2754 * Continues a multi-part update of the Additional Authentication 2755 * Data (AAD). 2756 * <p> 2757 * Calls to this method provide AAD to the cipher when operating in 2758 * modes such as AEAD (GCM/CCM). If this cipher is operating in 2759 * either GCM or CCM mode, all AAD must be supplied before beginning 2760 * operations on the ciphertext (via the {@code update} 2761 * and {@code doFinal} methods). 2762 * <p> 2763 * All {@code src.remaining()} bytes starting at 2764 * {@code src.position()} are processed. 2765 * Upon return, the input buffer's position will be equal 2766 * to its limit; its limit will not have changed. 2767 * 2768 * @param src the buffer containing the AAD 2769 * 2770 * @throws IllegalArgumentException if the {@code src ByteBuffer} 2771 * is null 2772 * @throws IllegalStateException if this cipher is in a wrong state 2773 * (e.g., has not been initialized), does not accept AAD, or if 2774 * operating in either GCM or CCM mode and one of the {@code update} 2775 * methods has already been called for the active 2776 * encryption/decryption operation 2777 * @throws UnsupportedOperationException if the corresponding method 2778 * in the {@code CipherSpi} has not been overridden by an 2779 * implementation 2780 * 2781 * @since 1.7 2782 */ 2783 public final void updateAAD(ByteBuffer src) { 2784 checkCipherState(); 2785 2786 // Input sanity check 2787 if (src == null) { 2788 throw new IllegalArgumentException("src ByteBuffer is null"); 2789 } 2790 2791 chooseFirstProvider(); 2792 if (src.remaining() == 0) { 2793 return; 2794 } 2795 spi.engineUpdateAAD(src); 2796 } 2797 }