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</code> 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>DES</i>), and may be followed by a feedback mode and 63 * padding scheme. 64 * 65 * <p> A transformation is of the form: 66 * 67 * <ul> 68 * <li>"<i>algorithm/mode/padding</i>" or 69 * 70 * <li>"<i>algorithm</i>" 71 * </ul> 72 * 73 * <P> (in the latter case, 74 * provider-specific default values for the mode and padding scheme are used). 75 * For example, the following is a valid transformation: 76 * 77 * <pre> 78 * Cipher c = Cipher.getInstance("<i>DES/CBC/PKCS5Padding</i>"); 79 * </pre> 80 * 81 * Using modes such as <code>CFB</code> and <code>OFB</code>, 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>DES/CFB8/NoPadding</code>" and 86 * "<code>DES/OFB32/PKCS5Padding</code>" transformations. If no such 87 * number is specified, a provider-specific default is used. (For 88 * example, the SunJCE provider uses a default of 64 bits for DES.) 89 * Thus, block ciphers can be turned into byte-oriented stream ciphers by 90 * using an 8 bit mode such as CFB8 or OFB8. 91 * <p> 92 * Modes such as Authenticated Encryption with Associated Data (AEAD) 93 * provide authenticity assurances for both confidential data and 94 * Additional Associated Data (AAD) that is not encrypted. (Please see 95 * <a href="http://www.ietf.org/rfc/rfc5116.txt"> RFC 5116 </a> for more 96 * information on AEAD and AEAD algorithms such as GCM/CCM.) Both 97 * confidential and AAD data can be used when calculating the 98 * authentication tag (similar to a {@link Mac}). This tag is appended 99 * to the ciphertext during encryption, and is verified on decryption. 100 * <p> 101 * AEAD modes such as GCM/CCM perform all AAD authenticity calculations 102 * before starting the ciphertext authenticity calculations. To avoid 103 * implementations having to internally buffer ciphertext, all AAD data 104 * must be supplied to GCM/CCM implementations (via the {@code 105 * updateAAD} methods) <b>before</b> the ciphertext is processed (via 106 * the {@code update} and {@code doFinal} methods). 107 * <p> 108 * Note that GCM mode has a uniqueness requirement on IVs used in 109 * encryption with a given key. When IVs are repeated for GCM 110 * encryption, such usages are subject to forgery attacks. Thus, after 111 * each encryption operation using GCM mode, callers should re-initialize 112 * the cipher objects with GCM parameters which has a different IV value. 113 * <pre> 114 * GCMParameterSpec s = ...; 115 * cipher.init(..., s); 116 * 117 * // If the GCM parameters were generated by the provider, it can 118 * // be retrieved by: 119 * // cipher.getParameters().getParameterSpec(GCMParameterSpec.class); 120 * 121 * cipher.updateAAD(...); // AAD 122 * cipher.update(...); // Multi-part update 123 * cipher.doFinal(...); // conclusion of operation 124 * 125 * // Use a different IV value for every encryption 126 * byte[] newIv = ...; 127 * s = new GCMParameterSpec(s.getTLen(), newIv); 128 * cipher.init(..., s); 129 * ... 130 * 131 * </pre> 132 * Every implementation of the Java platform is required to support 133 * the following standard <code>Cipher</code> transformations with the keysizes 134 * in parentheses: 135 * <ul> 136 * <li><tt>AES/CBC/NoPadding</tt> (128)</li> 137 * <li><tt>AES/CBC/PKCS5Padding</tt> (128)</li> 138 * <li><tt>AES/ECB/NoPadding</tt> (128)</li> 139 * <li><tt>AES/ECB/PKCS5Padding</tt> (128)</li> 140 * <li><tt>DES/CBC/NoPadding</tt> (56)</li> 141 * <li><tt>DES/CBC/PKCS5Padding</tt> (56)</li> 142 * <li><tt>DES/ECB/NoPadding</tt> (56)</li> 143 * <li><tt>DES/ECB/PKCS5Padding</tt> (56)</li> 144 * <li><tt>DESede/CBC/NoPadding</tt> (168)</li> 145 * <li><tt>DESede/CBC/PKCS5Padding</tt> (168)</li> 146 * <li><tt>DESede/ECB/NoPadding</tt> (168)</li> 147 * <li><tt>DESede/ECB/PKCS5Padding</tt> (168)</li> 148 * <li><tt>RSA/ECB/PKCS1Padding</tt> (1024, 2048)</li> 149 * <li><tt>RSA/ECB/OAEPWithSHA-1AndMGF1Padding</tt> (1024, 2048)</li> 150 * <li><tt>RSA/ECB/OAEPWithSHA-256AndMGF1Padding</tt> (1024, 2048)</li> 151 * </ul> 152 * These transformations are described in the 153 * <a href="{@docRoot}/../technotes/guides/security/StandardNames.html#Cipher"> 154 * Cipher section</a> of the 155 * Java Cryptography Architecture Standard Algorithm Name Documentation. 156 * Consult the release documentation for your implementation to see if any 157 * other transformations are supported. 158 * 159 * @author Jan Luehe 160 * @see KeyGenerator 161 * @see SecretKey 162 * @since 1.4 163 */ 164 165 public class Cipher { 166 167 private static final Debug debug = 168 Debug.getInstance("jca", "Cipher"); 169 170 private static final Debug pdebug = 449 list.add(new Transform(alg, "/" + mode, null, pad)); 450 list.add(new Transform(alg, "//" + pad, mode, null)); 451 list.add(new Transform(alg, "", mode, pad)); 452 return list; 453 } 454 } 455 456 // get the transform matching the specified service 457 private static Transform getTransform(Service s, 458 List<Transform> transforms) { 459 String alg = s.getAlgorithm().toUpperCase(Locale.ENGLISH); 460 for (Transform tr : transforms) { 461 if (alg.endsWith(tr.suffix)) { 462 return tr; 463 } 464 } 465 return null; 466 } 467 468 /** 469 * Returns a <code>Cipher</code> object that implements the specified 470 * transformation. 471 * 472 * <p> This method traverses the list of registered security Providers, 473 * starting with the most preferred Provider. 474 * A new Cipher object encapsulating the 475 * CipherSpi implementation from the first 476 * Provider that supports the specified algorithm is returned. 477 * 478 * <p> Note that the list of registered providers may be retrieved via 479 * the {@link Security#getProviders() Security.getProviders()} method. 480 * 481 * @param transformation the name of the transformation, e.g., 482 * <i>DES/CBC/PKCS5Padding</i>. 483 * See the Cipher section in the <a href= 484 * "{@docRoot}/../technotes/guides/security/StandardNames.html#Cipher"> 485 * Java Cryptography Architecture Standard Algorithm Name Documentation</a> 486 * for information about standard transformation names. 487 * 488 * @return a cipher that implements the requested transformation. 489 * 490 * @exception NoSuchAlgorithmException if <code>transformation</code> 491 * is null, empty, in an invalid format, 492 * or if no Provider supports a CipherSpi implementation for the 493 * specified algorithm. 494 * 495 * @exception NoSuchPaddingException if <code>transformation</code> 496 * contains a padding scheme that is not available. 497 * 498 * @see java.security.Provider 499 */ 500 public static final Cipher getInstance(String transformation) 501 throws NoSuchAlgorithmException, NoSuchPaddingException 502 { 503 List<Transform> transforms = getTransforms(transformation); 504 List<ServiceId> cipherServices = new ArrayList<>(transforms.size()); 505 for (Transform transform : transforms) { 506 cipherServices.add(new ServiceId("Cipher", transform.transform)); 507 } 508 List<Service> services = GetInstance.getServices(cipherServices); 509 // make sure there is at least one service from a signed provider 510 // and that it can use the specified mode and padding 511 Iterator<Service> t = services.iterator(); 512 Exception failure = null; 513 while (t.hasNext()) { 514 Service s = t.next(); 515 if (JceSecurity.canUseProvider(s.getProvider()) == false) { 525 // does not support mode or padding we need, ignore 526 continue; 527 } 528 if (canuse == S_YES) { 529 return new Cipher(null, s, t, transformation, transforms); 530 } else { // S_MAYBE, try out if it works 531 try { 532 CipherSpi spi = (CipherSpi)s.newInstance(null); 533 tr.setModePadding(spi); 534 return new Cipher(spi, s, t, transformation, transforms); 535 } catch (Exception e) { 536 failure = e; 537 } 538 } 539 } 540 throw new NoSuchAlgorithmException 541 ("Cannot find any provider supporting " + transformation, failure); 542 } 543 544 /** 545 * Returns a <code>Cipher</code> object that implements the specified 546 * transformation. 547 * 548 * <p> A new Cipher object encapsulating the 549 * CipherSpi implementation from the specified provider 550 * is returned. The specified provider must be registered 551 * in the security provider list. 552 * 553 * <p> Note that the list of registered providers may be retrieved via 554 * the {@link Security#getProviders() Security.getProviders()} method. 555 * 556 * @param transformation the name of the transformation, 557 * e.g., <i>DES/CBC/PKCS5Padding</i>. 558 * See the Cipher section in the <a href= 559 * "{@docRoot}/../technotes/guides/security/StandardNames.html#Cipher"> 560 * Java Cryptography Architecture Standard Algorithm Name Documentation</a> 561 * for information about standard transformation names. 562 * 563 * @param provider the name of the provider. 564 * 565 * @return a cipher that implements the requested transformation. 566 * 567 * @exception NoSuchAlgorithmException if <code>transformation</code> 568 * is null, empty, in an invalid format, 569 * or if a CipherSpi implementation for the specified algorithm 570 * is not available from the specified provider. 571 * 572 * @exception NoSuchProviderException if the specified provider is not 573 * registered in the security provider list. 574 * 575 * @exception NoSuchPaddingException if <code>transformation</code> 576 * contains a padding scheme that is not available. 577 * 578 * @exception IllegalArgumentException if the <code>provider</code> 579 * is null or empty. 580 * 581 * @see java.security.Provider 582 */ 583 public static final Cipher getInstance(String transformation, 584 String provider) 585 throws NoSuchAlgorithmException, NoSuchProviderException, 586 NoSuchPaddingException 587 { 588 if ((provider == null) || (provider.length() == 0)) { 589 throw new IllegalArgumentException("Missing provider"); 590 } 591 Provider p = Security.getProvider(provider); 592 if (p == null) { 593 throw new NoSuchProviderException("No such provider: " + 594 provider); 595 } 596 return getInstance(transformation, p); 597 } 598 599 /** 600 * Returns a <code>Cipher</code> object that implements the specified 601 * transformation. 602 * 603 * <p> A new Cipher object encapsulating the 604 * CipherSpi implementation from the specified Provider 605 * object is returned. Note that the specified Provider object 606 * does not have to be registered in the provider list. 607 * 608 * @param transformation the name of the transformation, 609 * e.g., <i>DES/CBC/PKCS5Padding</i>. 610 * See the Cipher section in the <a href= 611 * "{@docRoot}/../technotes/guides/security/StandardNames.html#Cipher"> 612 * Java Cryptography Architecture Standard Algorithm Name Documentation</a> 613 * for information about standard transformation names. 614 * 615 * @param provider the provider. 616 * 617 * @return a cipher that implements the requested transformation. 618 * 619 * @exception NoSuchAlgorithmException if <code>transformation</code> 620 * is null, empty, in an invalid format, 621 * or if a CipherSpi implementation for the specified algorithm 622 * is not available from the specified Provider object. 623 * 624 * @exception NoSuchPaddingException if <code>transformation</code> 625 * contains a padding scheme that is not available. 626 * 627 * @exception IllegalArgumentException if the <code>provider</code> 628 * is null. 629 * 630 * @see java.security.Provider 631 */ 632 public static final Cipher getInstance(String transformation, 633 Provider provider) 634 throws NoSuchAlgorithmException, NoSuchPaddingException 635 { 636 if (provider == null) { 637 throw new IllegalArgumentException("Missing provider"); 638 } 639 Exception failure = null; 640 List<Transform> transforms = getTransforms(transformation); 641 boolean providerChecked = false; 642 String paddingError = null; 643 for (Transform tr : transforms) { 644 Service s = provider.getService("Cipher", tr.transform); 645 if (s == null) { 646 continue; 647 } 880 } 881 } 882 // no working provider found, fail 883 if (lastException instanceof InvalidKeyException) { 884 throw (InvalidKeyException)lastException; 885 } 886 if (lastException instanceof InvalidAlgorithmParameterException) { 887 throw (InvalidAlgorithmParameterException)lastException; 888 } 889 if (lastException instanceof RuntimeException) { 890 throw (RuntimeException)lastException; 891 } 892 String kName = (key != null) ? key.getClass().getName() : "(null)"; 893 throw new InvalidKeyException 894 ("No installed provider supports this key: " 895 + kName, lastException); 896 } 897 } 898 899 /** 900 * Returns the provider of this <code>Cipher</code> object. 901 * 902 * @return the provider of this <code>Cipher</code> object 903 */ 904 public final Provider getProvider() { 905 chooseFirstProvider(); 906 return this.provider; 907 } 908 909 /** 910 * Returns the algorithm name of this <code>Cipher</code> object. 911 * 912 * <p>This is the same name that was specified in one of the 913 * <code>getInstance</code> calls that created this <code>Cipher</code> 914 * object.. 915 * 916 * @return the algorithm name of this <code>Cipher</code> object. 917 */ 918 public final String getAlgorithm() { 919 return this.transformation; 920 } 921 922 /** 923 * Returns the block size (in bytes). 924 * 925 * @return the block size (in bytes), or 0 if the underlying algorithm is 926 * not a block cipher 927 */ 928 public final int getBlockSize() { 929 chooseFirstProvider(); 930 return spi.engineGetBlockSize(); 931 } 932 933 /** 934 * Returns the length in bytes that an output buffer would need to be in 935 * order to hold the result of the next <code>update</code> or 936 * <code>doFinal</code> operation, given the input length 937 * <code>inputLen</code> (in bytes). 938 * 939 * <p>This call takes into account any unprocessed (buffered) data from a 940 * previous <code>update</code> call, padding, and AEAD tagging. 941 * 942 * <p>The actual output length of the next <code>update</code> or 943 * <code>doFinal</code> call may be smaller than the length returned by 944 * this method. 945 * 946 * @param inputLen the input length (in bytes) 947 * 948 * @return the required output buffer size (in bytes) 949 * 950 * @exception IllegalStateException if this cipher is in a wrong state 951 * (e.g., has not yet been initialized) 952 */ 953 public final int getOutputSize(int inputLen) { 954 955 if (!initialized && !(this instanceof NullCipher)) { 956 throw new IllegalStateException("Cipher not initialized"); 957 } 958 if (inputLen < 0) { 959 throw new IllegalArgumentException("Input size must be equal " + 960 "to or greater than zero"); 961 } 962 chooseFirstProvider(); 963 return spi.engineGetOutputSize(inputLen); 1118 private static String getOpmodeString(int opmode) { 1119 switch (opmode) { 1120 case ENCRYPT_MODE: 1121 return "encryption"; 1122 case DECRYPT_MODE: 1123 return "decryption"; 1124 case WRAP_MODE: 1125 return "key wrapping"; 1126 case UNWRAP_MODE: 1127 return "key unwrapping"; 1128 default: 1129 return ""; 1130 } 1131 } 1132 1133 /** 1134 * Initializes this cipher with a key. 1135 * 1136 * <p>The cipher is initialized for one of the following four operations: 1137 * encryption, decryption, key wrapping or key unwrapping, depending 1138 * on the value of <code>opmode</code>. 1139 * 1140 * <p>If this cipher requires any algorithm parameters that cannot be 1141 * derived from the given <code>key</code>, the underlying cipher 1142 * implementation is supposed to generate the required parameters itself 1143 * (using provider-specific default or random values) if it is being 1144 * initialized for encryption or key wrapping, and raise an 1145 * <code>InvalidKeyException</code> if it is being 1146 * initialized for decryption or key unwrapping. 1147 * The generated parameters can be retrieved using 1148 * {@link #getParameters() getParameters} or 1149 * {@link #getIV() getIV} (if the parameter is an IV). 1150 * 1151 * <p>If this cipher requires algorithm parameters that cannot be 1152 * derived from the input parameters, and there are no reasonable 1153 * provider-specific default values, initialization will 1154 * necessarily fail. 1155 * 1156 * <p>If this cipher (including its underlying feedback or padding scheme) 1157 * requires any random bytes (e.g., for parameter generation), it will get 1158 * them using the {@link java.security.SecureRandom} 1159 * implementation of the highest-priority 1160 * installed provider as the source of randomness. 1161 * (If none of the installed providers supply an implementation of 1162 * SecureRandom, a system-provided source of randomness will be used.) 1163 * 1164 * <p>Note that when a Cipher object is initialized, it loses all 1165 * previously-acquired state. In other words, initializing a Cipher is 1166 * equivalent to creating a new instance of that Cipher and initializing 1167 * it. 1168 * 1169 * @param opmode the operation mode of this cipher (this is one of 1170 * the following: 1171 * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>, 1172 * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>) 1173 * @param key the key 1174 * 1175 * @exception InvalidKeyException if the given key is inappropriate for 1176 * initializing this cipher, or requires 1177 * algorithm parameters that cannot be 1178 * determined from the given key, or if the given key has a keysize that 1179 * exceeds the maximum allowable keysize (as determined from the 1180 * configured jurisdiction policy files). 1181 * @throws UnsupportedOperationException if (@code opmode} is 1182 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1183 * by the underlying {@code CipherSpi}. 1184 */ 1185 public final void init(int opmode, Key key) throws InvalidKeyException { 1186 init(opmode, key, JceSecurity.RANDOM); 1187 } 1188 1189 /** 1190 * Initializes this cipher with a key and a source of randomness. 1191 * 1192 * <p>The cipher is initialized for one of the following four operations: 1193 * encryption, decryption, key wrapping or key unwrapping, depending 1194 * on the value of <code>opmode</code>. 1195 * 1196 * <p>If this cipher requires any algorithm parameters that cannot be 1197 * derived from the given <code>key</code>, the underlying cipher 1198 * implementation is supposed to generate the required parameters itself 1199 * (using provider-specific default or random values) if it is being 1200 * initialized for encryption or key wrapping, and raise an 1201 * <code>InvalidKeyException</code> if it is being 1202 * initialized for decryption or key unwrapping. 1203 * The generated parameters can be retrieved using 1204 * {@link #getParameters() getParameters} or 1205 * {@link #getIV() getIV} (if the parameter is an IV). 1206 * 1207 * <p>If this cipher requires algorithm parameters that cannot be 1208 * derived from the input parameters, and there are no reasonable 1209 * provider-specific default values, initialization will 1210 * necessarily fail. 1211 * 1212 * <p>If this cipher (including its underlying feedback or padding scheme) 1213 * requires any random bytes (e.g., for parameter generation), it will get 1214 * them from <code>random</code>. 1215 * 1216 * <p>Note that when a Cipher object is initialized, it loses all 1217 * previously-acquired state. In other words, initializing a Cipher is 1218 * equivalent to creating a new instance of that Cipher and initializing 1219 * it. 1220 * 1221 * @param opmode the operation mode of this cipher (this is one of the 1222 * following: 1223 * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>, 1224 * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>) 1225 * @param key the encryption key 1226 * @param random the source of randomness 1227 * 1228 * @exception InvalidKeyException if the given key is inappropriate for 1229 * initializing this cipher, or requires 1230 * algorithm parameters that cannot be 1231 * determined from the given key, or if the given key has a keysize that 1232 * exceeds the maximum allowable keysize (as determined from the 1233 * configured jurisdiction policy files). 1234 * @throws UnsupportedOperationException if (@code opmode} is 1235 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1236 * by the underlying {@code CipherSpi}. 1237 */ 1238 public final void init(int opmode, Key key, SecureRandom random) 1239 throws InvalidKeyException 1240 { 1241 initialized = false; 1242 checkOpmode(opmode); 1243 1244 if (spi != null) { 1252 throw new InvalidKeyException(e); 1253 } 1254 } 1255 1256 initialized = true; 1257 this.opmode = opmode; 1258 1259 if (!skipDebug && pdebug != null) { 1260 pdebug.println("Cipher." + transformation + " " + 1261 getOpmodeString(opmode) + " algorithm from: " + 1262 this.provider.getName()); 1263 } 1264 } 1265 1266 /** 1267 * Initializes this cipher with a key and a set of algorithm 1268 * parameters. 1269 * 1270 * <p>The cipher is initialized for one of the following four operations: 1271 * encryption, decryption, key wrapping or key unwrapping, depending 1272 * on the value of <code>opmode</code>. 1273 * 1274 * <p>If this cipher requires any algorithm parameters and 1275 * <code>params</code> is null, the underlying cipher implementation is 1276 * supposed to generate the required parameters itself (using 1277 * provider-specific default or random values) if it is being 1278 * initialized for encryption or key wrapping, and raise an 1279 * <code>InvalidAlgorithmParameterException</code> if it is being 1280 * initialized for decryption or key unwrapping. 1281 * The generated parameters can be retrieved using 1282 * {@link #getParameters() getParameters} or 1283 * {@link #getIV() getIV} (if the parameter is an IV). 1284 * 1285 * <p>If this cipher requires algorithm parameters that cannot be 1286 * derived from the input parameters, and there are no reasonable 1287 * provider-specific default values, initialization will 1288 * necessarily fail. 1289 * 1290 * <p>If this cipher (including its underlying feedback or padding scheme) 1291 * requires any random bytes (e.g., for parameter generation), it will get 1292 * them using the {@link java.security.SecureRandom} 1293 * implementation of the highest-priority 1294 * installed provider as the source of randomness. 1295 * (If none of the installed providers supply an implementation of 1296 * SecureRandom, a system-provided source of randomness will be used.) 1297 * 1298 * <p>Note that when a Cipher object is initialized, it loses all 1299 * previously-acquired state. In other words, initializing a Cipher is 1300 * equivalent to creating a new instance of that Cipher and initializing 1301 * it. 1302 * 1303 * @param opmode the operation mode of this cipher (this is one of the 1304 * following: 1305 * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>, 1306 * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>) 1307 * @param key the encryption key 1308 * @param params the algorithm parameters 1309 * 1310 * @exception InvalidKeyException if the given key is inappropriate for 1311 * initializing this cipher, or its keysize exceeds the maximum allowable 1312 * keysize (as determined from the configured jurisdiction policy files). 1313 * @exception InvalidAlgorithmParameterException if the given algorithm 1314 * parameters are inappropriate for this cipher, 1315 * or this cipher requires 1316 * algorithm parameters and <code>params</code> is null, or the given 1317 * algorithm parameters imply a cryptographic strength that would exceed 1318 * the legal limits (as determined from the configured jurisdiction 1319 * policy files). 1320 * @throws UnsupportedOperationException if (@code opmode} is 1321 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1322 * by the underlying {@code CipherSpi}. 1323 */ 1324 public final void init(int opmode, Key key, AlgorithmParameterSpec params) 1325 throws InvalidKeyException, InvalidAlgorithmParameterException 1326 { 1327 init(opmode, key, params, JceSecurity.RANDOM); 1328 } 1329 1330 /** 1331 * Initializes this cipher with a key, a set of algorithm 1332 * parameters, and a source of randomness. 1333 * 1334 * <p>The cipher is initialized for one of the following four operations: 1335 * encryption, decryption, key wrapping or key unwrapping, depending 1336 * on the value of <code>opmode</code>. 1337 * 1338 * <p>If this cipher requires any algorithm parameters and 1339 * <code>params</code> is null, the underlying cipher implementation is 1340 * supposed to generate the required parameters itself (using 1341 * provider-specific default or random values) if it is being 1342 * initialized for encryption or key wrapping, and raise an 1343 * <code>InvalidAlgorithmParameterException</code> if it is being 1344 * initialized for decryption or key unwrapping. 1345 * The generated parameters can be retrieved using 1346 * {@link #getParameters() getParameters} or 1347 * {@link #getIV() getIV} (if the parameter is an IV). 1348 * 1349 * <p>If this cipher requires algorithm parameters that cannot be 1350 * derived from the input parameters, and there are no reasonable 1351 * provider-specific default values, initialization will 1352 * necessarily fail. 1353 * 1354 * <p>If this cipher (including its underlying feedback or padding scheme) 1355 * requires any random bytes (e.g., for parameter generation), it will get 1356 * them from <code>random</code>. 1357 * 1358 * <p>Note that when a Cipher object is initialized, it loses all 1359 * previously-acquired state. In other words, initializing a Cipher is 1360 * equivalent to creating a new instance of that Cipher and initializing 1361 * it. 1362 * 1363 * @param opmode the operation mode of this cipher (this is one of the 1364 * following: 1365 * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>, 1366 * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>) 1367 * @param key the encryption key 1368 * @param params the algorithm parameters 1369 * @param random the source of randomness 1370 * 1371 * @exception InvalidKeyException if the given key is inappropriate for 1372 * initializing this cipher, or its keysize exceeds the maximum allowable 1373 * keysize (as determined from the configured jurisdiction policy files). 1374 * @exception InvalidAlgorithmParameterException if the given algorithm 1375 * parameters are inappropriate for this cipher, 1376 * or this cipher requires 1377 * algorithm parameters and <code>params</code> is null, or the given 1378 * algorithm parameters imply a cryptographic strength that would exceed 1379 * the legal limits (as determined from the configured jurisdiction 1380 * policy files). 1381 * @throws UnsupportedOperationException if (@code opmode} is 1382 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1383 * by the underlying {@code CipherSpi}. 1384 */ 1385 public final void init(int opmode, Key key, AlgorithmParameterSpec params, 1386 SecureRandom random) 1387 throws InvalidKeyException, InvalidAlgorithmParameterException 1388 { 1389 initialized = false; 1390 checkOpmode(opmode); 1391 1392 if (spi != null) { 1393 checkCryptoPerm(spi, key, params); 1394 spi.engineInit(opmode, key, params, random); 1395 } else { 1396 chooseProvider(I_PARAMSPEC, opmode, key, params, null, random); 1397 } 1398 1399 initialized = true; 1400 this.opmode = opmode; 1401 1402 if (!skipDebug && pdebug != null) { 1403 pdebug.println("Cipher." + transformation + " " + 1404 getOpmodeString(opmode) + " algorithm from: " + 1405 this.provider.getName()); 1406 } 1407 } 1408 1409 /** 1410 * Initializes this cipher with a key and a set of algorithm 1411 * parameters. 1412 * 1413 * <p>The cipher is initialized for one of the following four operations: 1414 * encryption, decryption, key wrapping or key unwrapping, depending 1415 * on the value of <code>opmode</code>. 1416 * 1417 * <p>If this cipher requires any algorithm parameters and 1418 * <code>params</code> is null, the underlying cipher implementation is 1419 * supposed to generate the required parameters itself (using 1420 * provider-specific default or random values) if it is being 1421 * initialized for encryption or key wrapping, and raise an 1422 * <code>InvalidAlgorithmParameterException</code> if it is being 1423 * initialized for decryption or key unwrapping. 1424 * The generated parameters can be retrieved using 1425 * {@link #getParameters() getParameters} or 1426 * {@link #getIV() getIV} (if the parameter is an IV). 1427 * 1428 * <p>If this cipher requires algorithm parameters that cannot be 1429 * derived from the input parameters, and there are no reasonable 1430 * provider-specific default values, initialization will 1431 * necessarily fail. 1432 * 1433 * <p>If this cipher (including its underlying feedback or padding scheme) 1434 * requires any random bytes (e.g., for parameter generation), it will get 1435 * them using the {@link java.security.SecureRandom} 1436 * implementation of the highest-priority 1437 * installed provider as the source of randomness. 1438 * (If none of the installed providers supply an implementation of 1439 * SecureRandom, a system-provided source of randomness will be used.) 1440 * 1441 * <p>Note that when a Cipher object is initialized, it loses all 1442 * previously-acquired state. In other words, initializing a Cipher is 1443 * equivalent to creating a new instance of that Cipher and initializing 1444 * it. 1445 * 1446 * @param opmode the operation mode of this cipher (this is one of the 1447 * following: <code>ENCRYPT_MODE</code>, 1448 * <code>DECRYPT_MODE</code>, <code>WRAP_MODE</code> 1449 * or <code>UNWRAP_MODE</code>) 1450 * @param key the encryption key 1451 * @param params the algorithm parameters 1452 * 1453 * @exception InvalidKeyException if the given key is inappropriate for 1454 * initializing this cipher, or its keysize exceeds the maximum allowable 1455 * keysize (as determined from the configured jurisdiction policy files). 1456 * @exception InvalidAlgorithmParameterException if the given algorithm 1457 * parameters are inappropriate for this cipher, 1458 * or this cipher requires 1459 * algorithm parameters and <code>params</code> is null, or the given 1460 * algorithm parameters imply a cryptographic strength that would exceed 1461 * the legal limits (as determined from the configured jurisdiction 1462 * policy files). 1463 * @throws UnsupportedOperationException if (@code opmode} is 1464 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1465 * by the underlying {@code CipherSpi}. 1466 */ 1467 public final void init(int opmode, Key key, AlgorithmParameters params) 1468 throws InvalidKeyException, InvalidAlgorithmParameterException 1469 { 1470 init(opmode, key, params, JceSecurity.RANDOM); 1471 } 1472 1473 /** 1474 * Initializes this cipher with a key, a set of algorithm 1475 * parameters, and a source of randomness. 1476 * 1477 * <p>The cipher is initialized for one of the following four operations: 1478 * encryption, decryption, key wrapping or key unwrapping, depending 1479 * on the value of <code>opmode</code>. 1480 * 1481 * <p>If this cipher requires any algorithm parameters and 1482 * <code>params</code> is null, the underlying cipher implementation is 1483 * supposed to generate the required parameters itself (using 1484 * provider-specific default or random values) if it is being 1485 * initialized for encryption or key wrapping, and raise an 1486 * <code>InvalidAlgorithmParameterException</code> if it is being 1487 * initialized for decryption or key unwrapping. 1488 * The generated parameters can be retrieved using 1489 * {@link #getParameters() getParameters} or 1490 * {@link #getIV() getIV} (if the parameter is an IV). 1491 * 1492 * <p>If this cipher requires algorithm parameters that cannot be 1493 * derived from the input parameters, and there are no reasonable 1494 * provider-specific default values, initialization will 1495 * necessarily fail. 1496 * 1497 * <p>If this cipher (including its underlying feedback or padding scheme) 1498 * requires any random bytes (e.g., for parameter generation), it will get 1499 * them from <code>random</code>. 1500 * 1501 * <p>Note that when a Cipher object is initialized, it loses all 1502 * previously-acquired state. In other words, initializing a Cipher is 1503 * equivalent to creating a new instance of that Cipher and initializing 1504 * it. 1505 * 1506 * @param opmode the operation mode of this cipher (this is one of the 1507 * following: <code>ENCRYPT_MODE</code>, 1508 * <code>DECRYPT_MODE</code>, <code>WRAP_MODE</code> 1509 * or <code>UNWRAP_MODE</code>) 1510 * @param key the encryption key 1511 * @param params the algorithm parameters 1512 * @param random the source of randomness 1513 * 1514 * @exception InvalidKeyException if the given key is inappropriate for 1515 * initializing this cipher, or its keysize exceeds the maximum allowable 1516 * keysize (as determined from the configured jurisdiction policy files). 1517 * @exception InvalidAlgorithmParameterException if the given algorithm 1518 * parameters are inappropriate for this cipher, 1519 * or this cipher requires 1520 * algorithm parameters and <code>params</code> is null, or the given 1521 * algorithm parameters imply a cryptographic strength that would exceed 1522 * the legal limits (as determined from the configured jurisdiction 1523 * policy files). 1524 * @throws UnsupportedOperationException if (@code opmode} is 1525 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1526 * by the underlying {@code CipherSpi}. 1527 */ 1528 public final void init(int opmode, Key key, AlgorithmParameters params, 1529 SecureRandom random) 1530 throws InvalidKeyException, InvalidAlgorithmParameterException 1531 { 1532 initialized = false; 1533 checkOpmode(opmode); 1534 1535 if (spi != null) { 1536 checkCryptoPerm(spi, key, params); 1537 spi.engineInit(opmode, key, params, random); 1538 } else { 1539 chooseProvider(I_PARAMS, opmode, key, null, params, random); 1540 } 1541 1542 initialized = true; 1543 this.opmode = opmode; 1544 1545 if (!skipDebug && pdebug != null) { 1546 pdebug.println("Cipher." + transformation + " " + 1547 getOpmodeString(opmode) + " algorithm from: " + 1548 this.provider.getName()); 1549 } 1550 } 1551 1552 /** 1553 * Initializes this cipher with the public key from the given certificate. 1554 * <p> The cipher is initialized for one of the following four operations: 1555 * encryption, decryption, key wrapping or key unwrapping, depending 1556 * on the value of <code>opmode</code>. 1557 * 1558 * <p>If the certificate is of type X.509 and has a <i>key usage</i> 1559 * extension field marked as critical, and the value of the <i>key usage</i> 1560 * extension field implies that the public key in 1561 * the certificate and its corresponding private key are not 1562 * supposed to be used for the operation represented by the value 1563 * of <code>opmode</code>, 1564 * an <code>InvalidKeyException</code> 1565 * is thrown. 1566 * 1567 * <p> If this cipher requires any algorithm parameters that cannot be 1568 * derived from the public key in the given certificate, the underlying 1569 * cipher 1570 * implementation is supposed to generate the required parameters itself 1571 * (using provider-specific default or random values) if it is being 1572 * initialized for encryption or key wrapping, and raise an <code> 1573 * InvalidKeyException</code> if it is being initialized for decryption or 1574 * key unwrapping. 1575 * The generated parameters can be retrieved using 1576 * {@link #getParameters() getParameters} or 1577 * {@link #getIV() getIV} (if the parameter is an IV). 1578 * 1579 * <p>If this cipher requires algorithm parameters that cannot be 1580 * derived from the input parameters, and there are no reasonable 1581 * provider-specific default values, initialization will 1582 * necessarily fail. 1583 * 1584 * <p>If this cipher (including its underlying feedback or padding scheme) 1585 * requires any random bytes (e.g., for parameter generation), it will get 1586 * them using the 1587 * <code>SecureRandom</code> 1588 * implementation of the highest-priority 1589 * installed provider as the source of randomness. 1590 * (If none of the installed providers supply an implementation of 1591 * SecureRandom, a system-provided source of randomness will be used.) 1592 * 1593 * <p>Note that when a Cipher object is initialized, it loses all 1594 * previously-acquired state. In other words, initializing a Cipher is 1595 * equivalent to creating a new instance of that Cipher and initializing 1596 * it. 1597 * 1598 * @param opmode the operation mode of this cipher (this is one of the 1599 * following: 1600 * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>, 1601 * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>) 1602 * @param certificate the certificate 1603 * 1604 * @exception InvalidKeyException if the public key in the given 1605 * certificate is inappropriate for initializing this cipher, or this 1606 * cipher requires algorithm parameters that cannot be determined from the 1607 * public key in the given certificate, or the keysize of the public key 1608 * in the given certificate has a keysize that exceeds the maximum 1609 * allowable keysize (as determined by the configured jurisdiction policy 1610 * files). 1611 * @throws UnsupportedOperationException if (@code opmode} is 1612 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1613 * by the underlying {@code CipherSpi}. 1614 */ 1615 public final void init(int opmode, Certificate certificate) 1616 throws InvalidKeyException 1617 { 1618 init(opmode, certificate, JceSecurity.RANDOM); 1619 } 1620 1621 /** 1622 * Initializes this cipher with the public key from the given certificate 1623 * and 1624 * a source of randomness. 1625 * 1626 * <p>The cipher is initialized for one of the following four operations: 1627 * encryption, decryption, key wrapping 1628 * or key unwrapping, depending on 1629 * the value of <code>opmode</code>. 1630 * 1631 * <p>If the certificate is of type X.509 and has a <i>key usage</i> 1632 * extension field marked as critical, and the value of the <i>key usage</i> 1633 * extension field implies that the public key in 1634 * the certificate and its corresponding private key are not 1635 * supposed to be used for the operation represented by the value of 1636 * <code>opmode</code>, 1637 * an <code>InvalidKeyException</code> 1638 * is thrown. 1639 * 1640 * <p>If this cipher requires any algorithm parameters that cannot be 1641 * derived from the public key in the given <code>certificate</code>, 1642 * the underlying cipher 1643 * implementation is supposed to generate the required parameters itself 1644 * (using provider-specific default or random values) if it is being 1645 * initialized for encryption or key wrapping, and raise an 1646 * <code>InvalidKeyException</code> if it is being 1647 * initialized for decryption or key unwrapping. 1648 * The generated parameters can be retrieved using 1649 * {@link #getParameters() getParameters} or 1650 * {@link #getIV() getIV} (if the parameter is an IV). 1651 * 1652 * <p>If this cipher requires algorithm parameters that cannot be 1653 * derived from the input parameters, and there are no reasonable 1654 * provider-specific default values, initialization will 1655 * necessarily fail. 1656 * 1657 * <p>If this cipher (including its underlying feedback or padding scheme) 1658 * requires any random bytes (e.g., for parameter generation), it will get 1659 * them from <code>random</code>. 1660 * 1661 * <p>Note that when a Cipher object is initialized, it loses all 1662 * previously-acquired state. In other words, initializing a Cipher is 1663 * equivalent to creating a new instance of that Cipher and initializing 1664 * it. 1665 * 1666 * @param opmode the operation mode of this cipher (this is one of the 1667 * following: 1668 * <code>ENCRYPT_MODE</code>, <code>DECRYPT_MODE</code>, 1669 * <code>WRAP_MODE</code> or <code>UNWRAP_MODE</code>) 1670 * @param certificate the certificate 1671 * @param random the source of randomness 1672 * 1673 * @exception InvalidKeyException if the public key in the given 1674 * certificate is inappropriate for initializing this cipher, or this 1675 * cipher 1676 * requires algorithm parameters that cannot be determined from the 1677 * public key in the given certificate, or the keysize of the public key 1678 * in the given certificate has a keysize that exceeds the maximum 1679 * allowable keysize (as determined by the configured jurisdiction policy 1680 * files). 1681 * @throws UnsupportedOperationException if (@code opmode} is 1682 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1683 * by the underlying {@code CipherSpi}. 1684 */ 1685 public final void init(int opmode, Certificate certificate, 1686 SecureRandom random) 1687 throws InvalidKeyException 1688 { 1689 initialized = false; 1745 * @throws IllegalStateException if Cipher object is not in valid state. 1746 */ 1747 private void checkCipherState() { 1748 if (!(this instanceof NullCipher)) { 1749 if (!initialized) { 1750 throw new IllegalStateException("Cipher not initialized"); 1751 } 1752 if ((opmode != Cipher.ENCRYPT_MODE) && 1753 (opmode != Cipher.DECRYPT_MODE)) { 1754 throw new IllegalStateException("Cipher not initialized " + 1755 "for encryption/decryption"); 1756 } 1757 } 1758 } 1759 1760 /** 1761 * Continues a multiple-part encryption or decryption operation 1762 * (depending on how this cipher was initialized), processing another data 1763 * part. 1764 * 1765 * <p>The bytes in the <code>input</code> buffer are processed, and the 1766 * result is stored in a new buffer. 1767 * 1768 * <p>If <code>input</code> has a length of zero, this method returns 1769 * <code>null</code>. 1770 * 1771 * @param input the input buffer 1772 * 1773 * @return the new buffer with the result, or null if the underlying 1774 * cipher is a block cipher and the input data is too short to result in a 1775 * new block. 1776 * 1777 * @exception IllegalStateException if this cipher is in a wrong state 1778 * (e.g., has not been initialized) 1779 */ 1780 public final byte[] update(byte[] input) { 1781 checkCipherState(); 1782 1783 // Input sanity check 1784 if (input == null) { 1785 throw new IllegalArgumentException("Null input buffer"); 1786 } 1787 1788 chooseFirstProvider(); 1789 if (input.length == 0) { 1790 return null; 1791 } 1792 return spi.engineUpdate(input, 0, input.length); 1793 } 1794 1795 /** 1796 * Continues a multiple-part encryption or decryption operation 1797 * (depending on how this cipher was initialized), processing another data 1798 * part. 1799 * 1800 * <p>The first <code>inputLen</code> bytes in the <code>input</code> 1801 * buffer, starting at <code>inputOffset</code> inclusive, are processed, 1802 * and the result is stored in a new buffer. 1803 * 1804 * <p>If <code>inputLen</code> is zero, this method returns 1805 * <code>null</code>. 1806 * 1807 * @param input the input buffer 1808 * @param inputOffset the offset in <code>input</code> where the input 1809 * starts 1810 * @param inputLen the input length 1811 * 1812 * @return the new buffer with the result, or null if the underlying 1813 * cipher is a block cipher and the input data is too short to result in a 1814 * new block. 1815 * 1816 * @exception IllegalStateException if this cipher is in a wrong state 1817 * (e.g., has not been initialized) 1818 */ 1819 public final byte[] update(byte[] input, int inputOffset, int inputLen) { 1820 checkCipherState(); 1821 1822 // Input sanity check 1823 if (input == null || inputOffset < 0 1824 || inputLen > (input.length - inputOffset) || inputLen < 0) { 1825 throw new IllegalArgumentException("Bad arguments"); 1826 } 1827 1828 chooseFirstProvider(); 1829 if (inputLen == 0) { 1830 return null; 1831 } 1832 return spi.engineUpdate(input, inputOffset, inputLen); 1833 } 1834 1835 /** 1836 * Continues a multiple-part encryption or decryption operation 1837 * (depending on how this cipher was initialized), processing another data 1838 * part. 1839 * 1840 * <p>The first <code>inputLen</code> bytes in the <code>input</code> 1841 * buffer, starting at <code>inputOffset</code> inclusive, are processed, 1842 * and the result is stored in the <code>output</code> buffer. 1843 * 1844 * <p>If the <code>output</code> buffer is too small to hold the result, 1845 * a <code>ShortBufferException</code> is thrown. In this case, repeat this 1846 * call with a larger output buffer. Use 1847 * {@link #getOutputSize(int) getOutputSize} to determine how big 1848 * the output buffer should be. 1849 * 1850 * <p>If <code>inputLen</code> is zero, this method returns 1851 * a length of zero. 1852 * 1853 * <p>Note: this method should be copy-safe, which means the 1854 * <code>input</code> and <code>output</code> buffers can reference 1855 * the same byte array and no unprocessed input data is overwritten 1856 * when the result is copied into the output buffer. 1857 * 1858 * @param input the input buffer 1859 * @param inputOffset the offset in <code>input</code> where the input 1860 * starts 1861 * @param inputLen the input length 1862 * @param output the buffer for the result 1863 * 1864 * @return the number of bytes stored in <code>output</code> 1865 * 1866 * @exception IllegalStateException if this cipher is in a wrong state 1867 * (e.g., has not been initialized) 1868 * @exception ShortBufferException if the given output buffer is too small 1869 * to hold the result 1870 */ 1871 public final int update(byte[] input, int inputOffset, int inputLen, 1872 byte[] output) 1873 throws ShortBufferException { 1874 checkCipherState(); 1875 1876 // Input sanity check 1877 if (input == null || inputOffset < 0 1878 || inputLen > (input.length - inputOffset) || inputLen < 0) { 1879 throw new IllegalArgumentException("Bad arguments"); 1880 } 1881 1882 chooseFirstProvider(); 1883 if (inputLen == 0) { 1884 return 0; 1885 } 1886 return spi.engineUpdate(input, inputOffset, inputLen, 1887 output, 0); 1888 } 1889 1890 /** 1891 * Continues a multiple-part encryption or decryption operation 1892 * (depending on how this cipher was initialized), processing another data 1893 * part. 1894 * 1895 * <p>The first <code>inputLen</code> bytes in the <code>input</code> 1896 * buffer, starting at <code>inputOffset</code> inclusive, are processed, 1897 * and the result is stored in the <code>output</code> buffer, starting at 1898 * <code>outputOffset</code> inclusive. 1899 * 1900 * <p>If the <code>output</code> buffer is too small to hold the result, 1901 * a <code>ShortBufferException</code> is thrown. In this case, repeat this 1902 * call with a larger output buffer. Use 1903 * {@link #getOutputSize(int) getOutputSize} to determine how big 1904 * the output buffer should be. 1905 * 1906 * <p>If <code>inputLen</code> is zero, this method returns 1907 * a length of zero. 1908 * 1909 * <p>Note: this method should be copy-safe, which means the 1910 * <code>input</code> and <code>output</code> buffers can reference 1911 * the same byte array and no unprocessed input data is overwritten 1912 * when the result is copied into the output buffer. 1913 * 1914 * @param input the input buffer 1915 * @param inputOffset the offset in <code>input</code> where the input 1916 * starts 1917 * @param inputLen the input length 1918 * @param output the buffer for the result 1919 * @param outputOffset the offset in <code>output</code> where the result 1920 * is stored 1921 * 1922 * @return the number of bytes stored in <code>output</code> 1923 * 1924 * @exception IllegalStateException if this cipher is in a wrong state 1925 * (e.g., has not been initialized) 1926 * @exception ShortBufferException if the given output buffer is too small 1927 * to hold the result 1928 */ 1929 public final int update(byte[] input, int inputOffset, int inputLen, 1930 byte[] output, int outputOffset) 1931 throws ShortBufferException { 1932 checkCipherState(); 1933 1934 // Input sanity check 1935 if (input == null || inputOffset < 0 1936 || inputLen > (input.length - inputOffset) || inputLen < 0 1937 || outputOffset < 0) { 1938 throw new IllegalArgumentException("Bad arguments"); 1939 } 1940 1941 chooseFirstProvider(); 1942 if (inputLen == 0) { 1943 return 0; 1944 } 1945 return spi.engineUpdate(input, inputOffset, inputLen, 1946 output, outputOffset); 1947 } 1948 1949 /** 1950 * Continues a multiple-part encryption or decryption operation 1951 * (depending on how this cipher was initialized), processing another data 1952 * part. 1953 * 1954 * <p>All <code>input.remaining()</code> bytes starting at 1955 * <code>input.position()</code> are processed. The result is stored 1956 * in the output buffer. 1957 * Upon return, the input buffer's position will be equal 1958 * to its limit; its limit will not have changed. The output buffer's 1959 * position will have advanced by n, where n is the value returned 1960 * by this method; the output buffer's limit will not have changed. 1961 * 1962 * <p>If <code>output.remaining()</code> bytes are insufficient to 1963 * hold the result, a <code>ShortBufferException</code> is thrown. 1964 * In this case, repeat this call with a larger output buffer. Use 1965 * {@link #getOutputSize(int) getOutputSize} to determine how big 1966 * the output buffer should be. 1967 * 1968 * <p>Note: this method should be copy-safe, which means the 1969 * <code>input</code> and <code>output</code> buffers can reference 1970 * the same block of memory and no unprocessed input data is overwritten 1971 * when the result is copied into the output buffer. 1972 * 1973 * @param input the input ByteBuffer 1974 * @param output the output ByteByffer 1975 * 1976 * @return the number of bytes stored in <code>output</code> 1977 * 1978 * @exception IllegalStateException if this cipher is in a wrong state 1979 * (e.g., has not been initialized) 1980 * @exception IllegalArgumentException if input and output are the 1981 * same object 1982 * @exception ReadOnlyBufferException if the output buffer is read-only 1983 * @exception ShortBufferException if there is insufficient space in the 1984 * output buffer 1985 * @since 1.5 1986 */ 1987 public final int update(ByteBuffer input, ByteBuffer output) 1988 throws ShortBufferException { 1989 checkCipherState(); 1990 1991 if ((input == null) || (output == null)) { 1992 throw new IllegalArgumentException("Buffers must not be null"); 1993 } 1994 if (input == output) { 1995 throw new IllegalArgumentException("Input and output buffers must " 1996 + "not be the same object, consider using buffer.duplicate()"); 1997 } 1998 if (output.isReadOnly()) { 1999 throw new ReadOnlyBufferException(); 2000 } 2001 2002 chooseFirstProvider(); 2003 return spi.engineUpdate(input, output); 2004 } 2005 2006 /** 2007 * Finishes a multiple-part encryption or decryption operation, depending 2008 * on how this cipher was initialized. 2009 * 2010 * <p>Input data that may have been buffered during a previous 2011 * <code>update</code> operation is processed, with padding (if requested) 2012 * being applied. 2013 * If an AEAD mode such as GCM/CCM is being used, the authentication 2014 * tag is appended in the case of encryption, or verified in the 2015 * case of decryption. 2016 * The result is stored in a new buffer. 2017 * 2018 * <p>Upon finishing, this method resets this cipher object to the state 2019 * it was in when previously initialized via a call to <code>init</code>. 2020 * That is, the object is reset and available to encrypt or decrypt 2021 * (depending on the operation mode that was specified in the call to 2022 * <code>init</code>) more data. 2023 * 2024 * <p>Note: if any exception is thrown, this cipher object may need to 2025 * be reset before it can be used again. 2026 * 2027 * @return the new buffer with the result 2028 * 2029 * @exception IllegalStateException if this cipher is in a wrong state 2030 * (e.g., has not been initialized) 2031 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2032 * no padding has been requested (only in encryption mode), and the total 2033 * input length of the data processed by this cipher is not a multiple of 2034 * block size; or if this encryption algorithm is unable to 2035 * process the input data provided. 2036 * @exception BadPaddingException if this cipher is in decryption mode, 2037 * and (un)padding has been requested, but the decrypted data is not 2038 * bounded by the appropriate padding bytes 2039 * @exception AEADBadTagException if this cipher is decrypting in an 2040 * AEAD mode (such as GCM/CCM), and the received authentication tag 2041 * does not match the calculated value 2042 */ 2043 public final byte[] doFinal() 2044 throws IllegalBlockSizeException, BadPaddingException { 2045 checkCipherState(); 2046 2047 chooseFirstProvider(); 2048 return spi.engineDoFinal(null, 0, 0); 2049 } 2050 2051 /** 2052 * Finishes a multiple-part encryption or decryption operation, depending 2053 * on how this cipher was initialized. 2054 * 2055 * <p>Input data that may have been buffered during a previous 2056 * <code>update</code> operation is processed, with padding (if requested) 2057 * being applied. 2058 * If an AEAD mode such as GCM/CCM is being used, the authentication 2059 * tag is appended in the case of encryption, or verified in the 2060 * case of decryption. 2061 * The result is stored in the <code>output</code> buffer, starting at 2062 * <code>outputOffset</code> inclusive. 2063 * 2064 * <p>If the <code>output</code> buffer is too small to hold the result, 2065 * a <code>ShortBufferException</code> is thrown. In this case, repeat this 2066 * call with a larger output buffer. Use 2067 * {@link #getOutputSize(int) getOutputSize} to determine how big 2068 * the output buffer should be. 2069 * 2070 * <p>Upon finishing, this method resets this cipher object to the state 2071 * it was in when previously initialized via a call to <code>init</code>. 2072 * That is, the object is reset and available to encrypt or decrypt 2073 * (depending on the operation mode that was specified in the call to 2074 * <code>init</code>) more data. 2075 * 2076 * <p>Note: if any exception is thrown, this cipher object may need to 2077 * be reset before it can be used again. 2078 * 2079 * @param output the buffer for the result 2080 * @param outputOffset the offset in <code>output</code> where the result 2081 * is stored 2082 * 2083 * @return the number of bytes stored in <code>output</code> 2084 * 2085 * @exception IllegalStateException if this cipher is in a wrong state 2086 * (e.g., has not been initialized) 2087 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2088 * no padding has been requested (only in encryption mode), and the total 2089 * input length of the data processed by this cipher is not a multiple of 2090 * block size; or if this encryption algorithm is unable to 2091 * process the input data provided. 2092 * @exception ShortBufferException if the given output buffer is too small 2093 * to hold the result 2094 * @exception BadPaddingException if this cipher is in decryption mode, 2095 * and (un)padding has been requested, but the decrypted data is not 2096 * bounded by the appropriate padding bytes 2097 * @exception AEADBadTagException if this cipher is decrypting in an 2098 * AEAD mode (such as GCM/CCM), and the received authentication tag 2099 * does not match the calculated value 2100 */ 2101 public final int doFinal(byte[] output, int outputOffset) 2102 throws IllegalBlockSizeException, ShortBufferException, 2103 BadPaddingException { 2104 checkCipherState(); 2105 2106 // Input sanity check 2107 if ((output == null) || (outputOffset < 0)) { 2108 throw new IllegalArgumentException("Bad arguments"); 2109 } 2110 2111 chooseFirstProvider(); 2112 return spi.engineDoFinal(null, 0, 0, output, outputOffset); 2113 } 2114 2115 /** 2116 * Encrypts or decrypts data in a single-part operation, or finishes a 2117 * multiple-part operation. The data is encrypted or decrypted, 2118 * depending on how this cipher was initialized. 2119 * 2120 * <p>The bytes in the <code>input</code> buffer, and any input bytes that 2121 * may have been buffered during a previous <code>update</code> operation, 2122 * are processed, with padding (if requested) being applied. 2123 * If an AEAD mode such as GCM/CCM is being used, the authentication 2124 * tag is appended in the case of encryption, or verified in the 2125 * case of decryption. 2126 * The result is stored in a new buffer. 2127 * 2128 * <p>Upon finishing, this method resets this cipher object to the state 2129 * it was in when previously initialized via a call to <code>init</code>. 2130 * That is, the object is reset and available to encrypt or decrypt 2131 * (depending on the operation mode that was specified in the call to 2132 * <code>init</code>) more data. 2133 * 2134 * <p>Note: if any exception is thrown, this cipher object may need to 2135 * be reset before it can be used again. 2136 * 2137 * @param input the input buffer 2138 * 2139 * @return the new buffer with the result 2140 * 2141 * @exception IllegalStateException if this cipher is in a wrong state 2142 * (e.g., has not been initialized) 2143 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2144 * no padding has been requested (only in encryption mode), and the total 2145 * input length of the data processed by this cipher is not a multiple of 2146 * block size; or if this encryption algorithm is unable to 2147 * process the input data provided. 2148 * @exception BadPaddingException if this cipher is in decryption mode, 2149 * and (un)padding has been requested, but the decrypted data is not 2150 * bounded by the appropriate padding bytes 2151 * @exception AEADBadTagException if this cipher is decrypting in an 2152 * AEAD mode (such as GCM/CCM), and the received authentication tag 2153 * does not match the calculated value 2154 */ 2155 public final byte[] doFinal(byte[] input) 2156 throws IllegalBlockSizeException, BadPaddingException { 2157 checkCipherState(); 2158 2159 // Input sanity check 2160 if (input == null) { 2161 throw new IllegalArgumentException("Null input buffer"); 2162 } 2163 2164 chooseFirstProvider(); 2165 return spi.engineDoFinal(input, 0, input.length); 2166 } 2167 2168 /** 2169 * Encrypts or decrypts data in a single-part operation, or finishes a 2170 * multiple-part operation. The data is encrypted or decrypted, 2171 * depending on how this cipher was initialized. 2172 * 2173 * <p>The first <code>inputLen</code> bytes in the <code>input</code> 2174 * buffer, starting at <code>inputOffset</code> inclusive, and any input 2175 * bytes that may have been buffered during a previous <code>update</code> 2176 * operation, are processed, with padding (if requested) being applied. 2177 * If an AEAD mode such as GCM/CCM is being used, the authentication 2178 * tag is appended in the case of encryption, or verified in the 2179 * case of decryption. 2180 * The result is stored in a new buffer. 2181 * 2182 * <p>Upon finishing, this method resets this cipher object to the state 2183 * it was in when previously initialized via a call to <code>init</code>. 2184 * That is, the object is reset and available to encrypt or decrypt 2185 * (depending on the operation mode that was specified in the call to 2186 * <code>init</code>) more data. 2187 * 2188 * <p>Note: if any exception is thrown, this cipher object may need to 2189 * be reset before it can be used again. 2190 * 2191 * @param input the input buffer 2192 * @param inputOffset the offset in <code>input</code> where the input 2193 * starts 2194 * @param inputLen the input length 2195 * 2196 * @return the new buffer with the result 2197 * 2198 * @exception IllegalStateException if this cipher is in a wrong state 2199 * (e.g., has not been initialized) 2200 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2201 * no padding has been requested (only in encryption mode), and the total 2202 * input length of the data processed by this cipher is not a multiple of 2203 * block size; or if this encryption algorithm is unable to 2204 * process the input data provided. 2205 * @exception BadPaddingException if this cipher is in decryption mode, 2206 * and (un)padding has been requested, but the decrypted data is not 2207 * bounded by the appropriate padding bytes 2208 * @exception AEADBadTagException if this cipher is decrypting in an 2209 * AEAD mode (such as GCM/CCM), and the received authentication tag 2210 * does not match the calculated value 2211 */ 2212 public final byte[] doFinal(byte[] input, int inputOffset, int inputLen) 2213 throws IllegalBlockSizeException, BadPaddingException { 2214 checkCipherState(); 2215 2216 // Input sanity check 2217 if (input == null || inputOffset < 0 2218 || inputLen > (input.length - inputOffset) || inputLen < 0) { 2219 throw new IllegalArgumentException("Bad arguments"); 2220 } 2221 2222 chooseFirstProvider(); 2223 return spi.engineDoFinal(input, inputOffset, inputLen); 2224 } 2225 2226 /** 2227 * Encrypts or decrypts data in a single-part operation, or finishes a 2228 * multiple-part operation. The data is encrypted or decrypted, 2229 * depending on how this cipher was initialized. 2230 * 2231 * <p>The first <code>inputLen</code> bytes in the <code>input</code> 2232 * buffer, starting at <code>inputOffset</code> inclusive, and any input 2233 * bytes that may have been buffered during a previous <code>update</code> 2234 * operation, are processed, with padding (if requested) being applied. 2235 * If an AEAD mode such as GCM/CCM is being used, the authentication 2236 * tag is appended in the case of encryption, or verified in the 2237 * case of decryption. 2238 * The result is stored in the <code>output</code> buffer. 2239 * 2240 * <p>If the <code>output</code> buffer is too small to hold the result, 2241 * a <code>ShortBufferException</code> is thrown. In this case, repeat this 2242 * call with a larger output buffer. Use 2243 * {@link #getOutputSize(int) getOutputSize} to determine how big 2244 * the output buffer should be. 2245 * 2246 * <p>Upon finishing, this method resets this cipher object to the state 2247 * it was in when previously initialized via a call to <code>init</code>. 2248 * That is, the object is reset and available to encrypt or decrypt 2249 * (depending on the operation mode that was specified in the call to 2250 * <code>init</code>) more data. 2251 * 2252 * <p>Note: if any exception is thrown, this cipher object may need to 2253 * be reset before it can be used again. 2254 * 2255 * <p>Note: this method should be copy-safe, which means the 2256 * <code>input</code> and <code>output</code> buffers can reference 2257 * the same byte array and no unprocessed input data is overwritten 2258 * when the result is copied into the output buffer. 2259 * 2260 * @param input the input buffer 2261 * @param inputOffset the offset in <code>input</code> where the input 2262 * starts 2263 * @param inputLen the input length 2264 * @param output the buffer for the result 2265 * 2266 * @return the number of bytes stored in <code>output</code> 2267 * 2268 * @exception IllegalStateException if this cipher is in a wrong state 2269 * (e.g., has not been initialized) 2270 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2271 * no padding has been requested (only in encryption mode), and the total 2272 * input length of the data processed by this cipher is not a multiple of 2273 * block size; or if this encryption algorithm is unable to 2274 * process the input data provided. 2275 * @exception ShortBufferException if the given output buffer is too small 2276 * to hold the result 2277 * @exception BadPaddingException if this cipher is in decryption mode, 2278 * and (un)padding has been requested, but the decrypted data is not 2279 * bounded by the appropriate padding bytes 2280 * @exception AEADBadTagException if this cipher is decrypting in an 2281 * AEAD mode (such as GCM/CCM), and the received authentication tag 2282 * does not match the calculated value 2283 */ 2284 public final int doFinal(byte[] input, int inputOffset, int inputLen, 2285 byte[] output) 2286 throws ShortBufferException, IllegalBlockSizeException, 2287 BadPaddingException { 2288 checkCipherState(); 2289 2290 // Input sanity check 2291 if (input == null || inputOffset < 0 2292 || inputLen > (input.length - inputOffset) || inputLen < 0) { 2293 throw new IllegalArgumentException("Bad arguments"); 2294 } 2295 2296 chooseFirstProvider(); 2297 return spi.engineDoFinal(input, inputOffset, inputLen, 2298 output, 0); 2299 } 2300 2301 /** 2302 * Encrypts or decrypts data in a single-part operation, or finishes a 2303 * multiple-part operation. The data is encrypted or decrypted, 2304 * depending on how this cipher was initialized. 2305 * 2306 * <p>The first <code>inputLen</code> bytes in the <code>input</code> 2307 * buffer, starting at <code>inputOffset</code> inclusive, and any input 2308 * bytes that may have been buffered during a previous 2309 * <code>update</code> operation, are processed, with padding 2310 * (if requested) being applied. 2311 * If an AEAD mode such as GCM/CCM is being used, the authentication 2312 * tag is appended in the case of encryption, or verified in the 2313 * case of decryption. 2314 * The result is stored in the <code>output</code> buffer, starting at 2315 * <code>outputOffset</code> inclusive. 2316 * 2317 * <p>If the <code>output</code> buffer is too small to hold the result, 2318 * a <code>ShortBufferException</code> is thrown. In this case, repeat this 2319 * call with a larger output buffer. Use 2320 * {@link #getOutputSize(int) getOutputSize} to determine how big 2321 * the output buffer should be. 2322 * 2323 * <p>Upon finishing, this method resets this cipher object to the state 2324 * it was in when previously initialized via a call to <code>init</code>. 2325 * That is, the object is reset and available to encrypt or decrypt 2326 * (depending on the operation mode that was specified in the call to 2327 * <code>init</code>) more data. 2328 * 2329 * <p>Note: if any exception is thrown, this cipher object may need to 2330 * be reset before it can be used again. 2331 * 2332 * <p>Note: this method should be copy-safe, which means the 2333 * <code>input</code> and <code>output</code> buffers can reference 2334 * the same byte array and no unprocessed input data is overwritten 2335 * when the result is copied into the output buffer. 2336 * 2337 * @param input the input buffer 2338 * @param inputOffset the offset in <code>input</code> where the input 2339 * starts 2340 * @param inputLen the input length 2341 * @param output the buffer for the result 2342 * @param outputOffset the offset in <code>output</code> where the result 2343 * is stored 2344 * 2345 * @return the number of bytes stored in <code>output</code> 2346 * 2347 * @exception IllegalStateException if this cipher is in a wrong state 2348 * (e.g., has not been initialized) 2349 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2350 * no padding has been requested (only in encryption mode), and the total 2351 * input length of the data processed by this cipher is not a multiple of 2352 * block size; or if this encryption algorithm is unable to 2353 * process the input data provided. 2354 * @exception ShortBufferException if the given output buffer is too small 2355 * to hold the result 2356 * @exception BadPaddingException if this cipher is in decryption mode, 2357 * and (un)padding has been requested, but the decrypted data is not 2358 * bounded by the appropriate padding bytes 2359 * @exception AEADBadTagException if this cipher is decrypting in an 2360 * AEAD mode (such as GCM/CCM), and the received authentication tag 2361 * does not match the calculated value 2362 */ 2363 public final int doFinal(byte[] input, int inputOffset, int inputLen, 2364 byte[] output, int outputOffset) 2365 throws ShortBufferException, IllegalBlockSizeException, 2366 BadPaddingException { 2367 checkCipherState(); 2368 2369 // Input sanity check 2370 if (input == null || inputOffset < 0 2371 || inputLen > (input.length - inputOffset) || inputLen < 0 2372 || outputOffset < 0) { 2373 throw new IllegalArgumentException("Bad arguments"); 2374 } 2375 2376 chooseFirstProvider(); 2377 return spi.engineDoFinal(input, inputOffset, inputLen, 2378 output, outputOffset); 2379 } 2380 2381 /** 2382 * Encrypts or decrypts data in a single-part operation, or finishes a 2383 * multiple-part operation. The data is encrypted or decrypted, 2384 * depending on how this cipher was initialized. 2385 * 2386 * <p>All <code>input.remaining()</code> bytes starting at 2387 * <code>input.position()</code> are processed. 2388 * If an AEAD mode such as GCM/CCM is being used, the authentication 2389 * tag is appended in the case of encryption, or verified in the 2390 * case of decryption. 2391 * The result is stored in the output buffer. 2392 * Upon return, the input buffer's position will be equal 2393 * to its limit; its limit will not have changed. The output buffer's 2394 * position will have advanced by n, where n is the value returned 2395 * by this method; the output buffer's limit will not have changed. 2396 * 2397 * <p>If <code>output.remaining()</code> bytes are insufficient to 2398 * hold the result, a <code>ShortBufferException</code> is thrown. 2399 * In this case, repeat this call with a larger output buffer. Use 2400 * {@link #getOutputSize(int) getOutputSize} to determine how big 2401 * the output buffer should be. 2402 * 2403 * <p>Upon finishing, this method resets this cipher object to the state 2404 * it was in when previously initialized via a call to <code>init</code>. 2405 * That is, the object is reset and available to encrypt or decrypt 2406 * (depending on the operation mode that was specified in the call to 2407 * <code>init</code>) more data. 2408 * 2409 * <p>Note: if any exception is thrown, this cipher object may need to 2410 * be reset before it can be used again. 2411 * 2412 * <p>Note: this method should be copy-safe, which means the 2413 * <code>input</code> and <code>output</code> buffers can reference 2414 * the same byte array and no unprocessed input data is overwritten 2415 * when the result is copied into the output buffer. 2416 * 2417 * @param input the input ByteBuffer 2418 * @param output the output ByteBuffer 2419 * 2420 * @return the number of bytes stored in <code>output</code> 2421 * 2422 * @exception IllegalStateException if this cipher is in a wrong state 2423 * (e.g., has not been initialized) 2424 * @exception IllegalArgumentException if input and output are the 2425 * same object 2426 * @exception ReadOnlyBufferException if the output buffer is read-only 2427 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2428 * no padding has been requested (only in encryption mode), and the total 2429 * input length of the data processed by this cipher is not a multiple of 2430 * block size; or if this encryption algorithm is unable to 2431 * process the input data provided. 2432 * @exception ShortBufferException if there is insufficient space in the 2433 * output buffer 2434 * @exception BadPaddingException if this cipher is in decryption mode, 2435 * and (un)padding has been requested, but the decrypted data is not 2436 * bounded by the appropriate padding bytes 2437 * @exception AEADBadTagException if this cipher is decrypting in an 2438 * AEAD mode (such as GCM/CCM), and the received authentication tag 2439 * does not match the calculated value 2440 * 2490 } 2491 if (opmode != Cipher.WRAP_MODE) { 2492 throw new IllegalStateException("Cipher not initialized " + 2493 "for wrapping keys"); 2494 } 2495 } 2496 2497 chooseFirstProvider(); 2498 return spi.engineWrap(key); 2499 } 2500 2501 /** 2502 * Unwrap a previously wrapped key. 2503 * 2504 * @param wrappedKey the key to be unwrapped. 2505 * 2506 * @param wrappedKeyAlgorithm the algorithm associated with the wrapped 2507 * key. 2508 * 2509 * @param wrappedKeyType the type of the wrapped key. This must be one of 2510 * <code>SECRET_KEY</code>, <code>PRIVATE_KEY</code>, or 2511 * <code>PUBLIC_KEY</code>. 2512 * 2513 * @return the unwrapped key. 2514 * 2515 * @exception IllegalStateException if this cipher is in a wrong state 2516 * (e.g., has not been initialized). 2517 * 2518 * @exception NoSuchAlgorithmException if no installed providers 2519 * can create keys of type <code>wrappedKeyType</code> for the 2520 * <code>wrappedKeyAlgorithm</code>. 2521 * 2522 * @exception InvalidKeyException if <code>wrappedKey</code> does not 2523 * represent a wrapped key of type <code>wrappedKeyType</code> for 2524 * the <code>wrappedKeyAlgorithm</code>. 2525 * 2526 * @throws UnsupportedOperationException if the corresponding method in the 2527 * {@code CipherSpi} is not supported. 2528 */ 2529 public final Key unwrap(byte[] wrappedKey, 2530 String wrappedKeyAlgorithm, 2531 int wrappedKeyType) 2532 throws InvalidKeyException, NoSuchAlgorithmException { 2533 2534 if (!(this instanceof NullCipher)) { 2535 if (!initialized) { 2536 throw new IllegalStateException("Cipher not initialized"); 2537 } 2538 if (opmode != Cipher.UNWRAP_MODE) { 2539 throw new IllegalStateException("Cipher not initialized " + 2540 "for unwrapping keys"); 2541 } 2542 } 2543 if ((wrappedKeyType != SECRET_KEY) && 2544 (wrappedKeyType != PRIVATE_KEY) && 2583 String transformation) throws NullPointerException, 2584 NoSuchAlgorithmException { 2585 if (transformation == null) throw new NullPointerException(); 2586 String[] parts = tokenizeTransformation(transformation); 2587 return JceSecurityManager.INSTANCE.getCryptoPermission(parts[0]); 2588 } 2589 2590 /** 2591 * Returns the maximum key length for the specified transformation 2592 * according to the installed JCE jurisdiction policy files. If 2593 * JCE unlimited strength jurisdiction policy files are installed, 2594 * Integer.MAX_VALUE will be returned. 2595 * For more information on default key size in JCE jurisdiction 2596 * policy files, please see Appendix E in the 2597 * <a href= 2598 * "{@docRoot}/../technotes/guides/security/crypto/CryptoSpec.html#AppC"> 2599 * Java Cryptography Architecture Reference Guide</a>. 2600 * 2601 * @param transformation the cipher transformation. 2602 * @return the maximum key length in bits or Integer.MAX_VALUE. 2603 * @exception NullPointerException if <code>transformation</code> is null. 2604 * @exception NoSuchAlgorithmException if <code>transformation</code> 2605 * is not a valid transformation, i.e. in the form of "algorithm" or 2606 * "algorithm/mode/padding". 2607 * @since 1.5 2608 */ 2609 public static final int getMaxAllowedKeyLength(String transformation) 2610 throws NoSuchAlgorithmException { 2611 CryptoPermission cp = getConfiguredPermission(transformation); 2612 return cp.getMaxKeySize(); 2613 } 2614 2615 /** 2616 * Returns an AlgorithmParameterSpec object which contains 2617 * the maximum cipher parameter value according to the 2618 * jurisdiction policy file. If JCE unlimited strength jurisdiction 2619 * policy files are installed or there is no maximum limit on the 2620 * parameters for the specified transformation in the policy file, 2621 * null will be returned. 2622 * 2623 * @param transformation the cipher transformation. 2624 * @return an AlgorithmParameterSpec which holds the maximum 2625 * value or null. 2626 * @exception NullPointerException if <code>transformation</code> 2627 * is null. 2628 * @exception NoSuchAlgorithmException if <code>transformation</code> 2629 * is not a valid transformation, i.e. in the form of "algorithm" or 2630 * "algorithm/mode/padding". 2631 * @since 1.5 2632 */ 2633 public static final AlgorithmParameterSpec getMaxAllowedParameterSpec( 2634 String transformation) throws NoSuchAlgorithmException { 2635 CryptoPermission cp = getConfiguredPermission(transformation); 2636 return cp.getAlgorithmParameterSpec(); 2637 } 2638 2639 /** 2640 * Continues a multi-part update of the Additional Authentication 2641 * Data (AAD). 2642 * <p> 2643 * Calls to this method provide AAD to the cipher when operating in 2644 * modes such as AEAD (GCM/CCM). If this cipher is operating in 2645 * either GCM or CCM mode, all AAD must be supplied before beginning 2646 * operations on the ciphertext (via the {@code update} and {@code 2647 * doFinal} methods). 2648 * 2649 * @param src the buffer containing the Additional Authentication Data 2650 * 2651 * @throws IllegalArgumentException if the {@code src} 2652 * byte array is null 2653 * @throws IllegalStateException if this cipher is in a wrong state 2654 * (e.g., has not been initialized), does not accept AAD, or if 2655 * operating in either GCM or CCM mode and one of the {@code update} 2656 * methods has already been called for the active 2657 * encryption/decryption operation 2658 * @throws UnsupportedOperationException if the corresponding method 2659 * in the {@code CipherSpi} has not been overridden by an 2660 * implementation 2661 * 2662 * @since 1.7 2663 */ 2664 public final void updateAAD(byte[] src) { 2665 if (src == null) { 2666 throw new IllegalArgumentException("src buffer is null"); 2667 } 2668 2669 updateAAD(src, 0, src.length); 2670 } 2671 2672 /** 2673 * Continues a multi-part update of the Additional Authentication 2674 * Data (AAD), using a subset of the provided buffer. 2675 * <p> 2676 * Calls to this method provide AAD to the cipher when operating in 2677 * modes such as AEAD (GCM/CCM). If this cipher is operating in 2678 * either GCM or CCM mode, all AAD must be supplied before beginning 2679 * operations on the ciphertext (via the {@code update} and {@code 2680 * doFinal} methods). 2681 * 2682 * @param src the buffer containing the AAD 2683 * @param offset the offset in {@code src} where the AAD input starts 2684 * @param len the number of AAD bytes 2685 * 2686 * @throws IllegalArgumentException if the {@code src} 2687 * byte array is null, or the {@code offset} or {@code length} 2688 * is less than 0, or the sum of the {@code offset} and 2689 * {@code len} is greater than the length of the 2690 * {@code src} byte array 2691 * @throws IllegalStateException if this cipher is in a wrong state 2692 * (e.g., has not been initialized), does not accept AAD, or if 2693 * operating in either GCM or CCM mode and one of the {@code update} 2694 * methods has already been called for the active 2695 * encryption/decryption operation 2696 * @throws UnsupportedOperationException if the corresponding method 2697 * in the {@code CipherSpi} has not been overridden by an 2698 * implementation 2699 * 2700 * @since 1.7 2705 // Input sanity check 2706 if ((src == null) || (offset < 0) || (len < 0) 2707 || ((len + offset) > src.length)) { 2708 throw new IllegalArgumentException("Bad arguments"); 2709 } 2710 2711 chooseFirstProvider(); 2712 if (len == 0) { 2713 return; 2714 } 2715 spi.engineUpdateAAD(src, offset, len); 2716 } 2717 2718 /** 2719 * Continues a multi-part update of the Additional Authentication 2720 * Data (AAD). 2721 * <p> 2722 * Calls to this method provide AAD to the cipher when operating in 2723 * modes such as AEAD (GCM/CCM). If this cipher is operating in 2724 * either GCM or CCM mode, all AAD must be supplied before beginning 2725 * operations on the ciphertext (via the {@code update} and {@code 2726 * doFinal} methods). 2727 * <p> 2728 * All {@code src.remaining()} bytes starting at 2729 * {@code src.position()} are processed. 2730 * Upon return, the input buffer's position will be equal 2731 * to its limit; its limit will not have changed. 2732 * 2733 * @param src the buffer containing the AAD 2734 * 2735 * @throws IllegalArgumentException if the {@code src ByteBuffer} 2736 * is null 2737 * @throws IllegalStateException if this cipher is in a wrong state 2738 * (e.g., has not been initialized), does not accept AAD, or if 2739 * operating in either GCM or CCM mode and one of the {@code update} 2740 * methods has already been called for the active 2741 * encryption/decryption operation 2742 * @throws UnsupportedOperationException if the corresponding method 2743 * in the {@code CipherSpi} has not been overridden by an 2744 * implementation 2745 * 2746 * @since 1.7 | 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>DES</i>), and may be followed by a feedback mode and 63 * padding scheme. 64 * 65 * <p> A transformation is of the form: 66 * 67 * <ul> 68 * <li>"<i>algorithm/mode/padding</i>" or 69 * 70 * <li>"<i>algorithm</i>" 71 * </ul> 72 * 73 * <P> (in the latter case, 74 * provider-specific default values for the mode and padding scheme are used). 75 * For example, the following is a valid transformation: 76 * 77 * <pre> 78 * Cipher c = Cipher.getInstance("<i>DES/CBC/PKCS5Padding</i>"); 79 * </pre> 80 * 81 * 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 DES/CFB8/NoPadding}" and 86 * "{@code DES/OFB32/PKCS5Padding}" transformations. If no such 87 * number is specified, a provider-specific default is used. (For 88 * example, the SunJCE provider uses a default of 64 bits for DES.) 89 * Thus, block ciphers can be turned into byte-oriented stream ciphers by 90 * using an 8 bit mode such as CFB8 or OFB8. 91 * <p> 92 * Modes such as Authenticated Encryption with Associated Data (AEAD) 93 * provide authenticity assurances for both confidential data and 94 * Additional Associated Data (AAD) that is not encrypted. (Please see 95 * <a href="http://www.ietf.org/rfc/rfc5116.txt"> RFC 5116 </a> for more 96 * information on AEAD and AEAD algorithms such as GCM/CCM.) Both 97 * confidential and AAD data can be used when calculating the 98 * authentication tag (similar to a {@link Mac}). This tag is appended 99 * to the ciphertext during encryption, and is verified on decryption. 100 * <p> 101 * AEAD modes such as GCM/CCM perform all AAD authenticity calculations 102 * before starting the ciphertext authenticity calculations. To avoid 103 * implementations having to internally buffer ciphertext, all AAD data 104 * must be supplied to GCM/CCM implementations (via the {@code updateAAD} 105 * methods) <b>before</b> the ciphertext is processed (via 106 * the {@code update} and {@code doFinal} methods). 107 * <p> 108 * Note that GCM mode has a uniqueness requirement on IVs used in 109 * encryption with a given key. When IVs are repeated for GCM 110 * encryption, such usages are subject to forgery attacks. Thus, after 111 * each encryption operation using GCM mode, callers should re-initialize 112 * the cipher objects with GCM parameters which has a different IV value. 113 * <pre> 114 * GCMParameterSpec s = ...; 115 * cipher.init(..., s); 116 * 117 * // If the GCM parameters were generated by the provider, it can 118 * // be retrieved by: 119 * // cipher.getParameters().getParameterSpec(GCMParameterSpec.class); 120 * 121 * cipher.updateAAD(...); // AAD 122 * cipher.update(...); // Multi-part update 123 * cipher.doFinal(...); // conclusion of operation 124 * 125 * // Use a different IV value for every encryption 126 * byte[] newIv = ...; 127 * s = new GCMParameterSpec(s.getTLen(), newIv); 128 * cipher.init(..., s); 129 * ... 130 * 131 * </pre> 132 * Every implementation of the Java platform is required to support 133 * the following standard {@code Cipher} transformations with the keysizes 134 * in parentheses: 135 * <ul> 136 * <li>{@code AES/CBC/NoPadding} (128)</li> 137 * <li>{@code AES/CBC/PKCS5Padding} (128)</li> 138 * <li>{@code AES/ECB/NoPadding} (128)</li> 139 * <li>{@code AES/ECB/PKCS5Padding} (128)</li> 140 * <li>{@code DES/CBC/NoPadding} (56)</li> 141 * <li>{@code DES/CBC/PKCS5Padding} (56)</li> 142 * <li>{@code DES/ECB/NoPadding} (56)</li> 143 * <li>{@code DES/ECB/PKCS5Padding} (56)</li> 144 * <li>{@code DESede/CBC/NoPadding} (168)</li> 145 * <li>{@code DESede/CBC/PKCS5Padding} (168)</li> 146 * <li>{@code DESede/ECB/NoPadding} (168)</li> 147 * <li>{@code DESede/ECB/PKCS5Padding} (168)</li> 148 * <li>{@code RSA/ECB/PKCS1Padding} (1024, 2048)</li> 149 * <li>{@code RSA/ECB/OAEPWithSHA-1AndMGF1Padding} (1024, 2048)</li> 150 * <li>{@code RSA/ECB/OAEPWithSHA-256AndMGF1Padding} (1024, 2048)</li> 151 * </ul> 152 * These transformations are described in the 153 * <a href="{@docRoot}/../technotes/guides/security/StandardNames.html#Cipher"> 154 * Cipher section</a> of the 155 * Java Cryptography Architecture Standard Algorithm Name Documentation. 156 * Consult the release documentation for your implementation to see if any 157 * other transformations are supported. 158 * 159 * @author Jan Luehe 160 * @see KeyGenerator 161 * @see SecretKey 162 * @since 1.4 163 */ 164 165 public class Cipher { 166 167 private static final Debug debug = 168 Debug.getInstance("jca", "Cipher"); 169 170 private static final Debug pdebug = 449 list.add(new Transform(alg, "/" + mode, null, pad)); 450 list.add(new Transform(alg, "//" + pad, mode, null)); 451 list.add(new Transform(alg, "", mode, pad)); 452 return list; 453 } 454 } 455 456 // get the transform matching the specified service 457 private static Transform getTransform(Service s, 458 List<Transform> transforms) { 459 String alg = s.getAlgorithm().toUpperCase(Locale.ENGLISH); 460 for (Transform tr : transforms) { 461 if (alg.endsWith(tr.suffix)) { 462 return tr; 463 } 464 } 465 return null; 466 } 467 468 /** 469 * Returns a {@code Cipher} object that implements the specified 470 * transformation. 471 * 472 * <p> This method traverses the list of registered security Providers, 473 * starting with the most preferred Provider. 474 * A new Cipher object encapsulating the 475 * CipherSpi implementation from the first 476 * Provider that supports the specified algorithm is returned. 477 * 478 * <p> Note that the list of registered providers may be retrieved via 479 * the {@link Security#getProviders() Security.getProviders()} method. 480 * 481 * @param transformation the name of the transformation, e.g., 482 * <i>DES/CBC/PKCS5Padding</i>. 483 * See the Cipher section in the <a href= 484 * "{@docRoot}/../technotes/guides/security/StandardNames.html#Cipher"> 485 * Java Cryptography Architecture Standard Algorithm Name Documentation</a> 486 * for information about standard transformation names. 487 * 488 * @return a cipher that implements the requested transformation. 489 * 490 * @exception NoSuchAlgorithmException if {@code transformation} 491 * is null, empty, in an invalid format, 492 * or if no Provider supports a CipherSpi implementation for the 493 * specified algorithm. 494 * 495 * @exception NoSuchPaddingException if {@code transformation} 496 * contains a padding scheme that is not available. 497 * 498 * @see java.security.Provider 499 */ 500 public static final Cipher getInstance(String transformation) 501 throws NoSuchAlgorithmException, NoSuchPaddingException 502 { 503 List<Transform> transforms = getTransforms(transformation); 504 List<ServiceId> cipherServices = new ArrayList<>(transforms.size()); 505 for (Transform transform : transforms) { 506 cipherServices.add(new ServiceId("Cipher", transform.transform)); 507 } 508 List<Service> services = GetInstance.getServices(cipherServices); 509 // make sure there is at least one service from a signed provider 510 // and that it can use the specified mode and padding 511 Iterator<Service> t = services.iterator(); 512 Exception failure = null; 513 while (t.hasNext()) { 514 Service s = t.next(); 515 if (JceSecurity.canUseProvider(s.getProvider()) == false) { 525 // does not support mode or padding we need, ignore 526 continue; 527 } 528 if (canuse == S_YES) { 529 return new Cipher(null, s, t, transformation, transforms); 530 } else { // S_MAYBE, try out if it works 531 try { 532 CipherSpi spi = (CipherSpi)s.newInstance(null); 533 tr.setModePadding(spi); 534 return new Cipher(spi, s, t, transformation, transforms); 535 } catch (Exception e) { 536 failure = e; 537 } 538 } 539 } 540 throw new NoSuchAlgorithmException 541 ("Cannot find any provider supporting " + transformation, failure); 542 } 543 544 /** 545 * Returns a {@code Cipher} object that implements the specified 546 * transformation. 547 * 548 * <p> A new Cipher object encapsulating the 549 * CipherSpi implementation from the specified provider 550 * is returned. The specified provider must be registered 551 * in the security provider list. 552 * 553 * <p> Note that the list of registered providers may be retrieved via 554 * the {@link Security#getProviders() Security.getProviders()} method. 555 * 556 * @param transformation the name of the transformation, 557 * e.g., <i>DES/CBC/PKCS5Padding</i>. 558 * See the Cipher section in the <a href= 559 * "{@docRoot}/../technotes/guides/security/StandardNames.html#Cipher"> 560 * Java Cryptography Architecture Standard Algorithm Name Documentation</a> 561 * for information about standard transformation names. 562 * 563 * @param provider the name of the provider. 564 * 565 * @return a cipher that implements the requested transformation. 566 * 567 * @exception NoSuchAlgorithmException if {@code transformation} 568 * is null, empty, in an invalid format, 569 * or if a CipherSpi implementation for the specified algorithm 570 * is not available from the specified provider. 571 * 572 * @exception NoSuchProviderException if the specified provider is not 573 * registered in the security provider list. 574 * 575 * @exception NoSuchPaddingException if {@code transformation} 576 * contains a padding scheme that is not available. 577 * 578 * @exception IllegalArgumentException if the {@code provider} 579 * is null or empty. 580 * 581 * @see java.security.Provider 582 */ 583 public static final Cipher getInstance(String transformation, 584 String provider) 585 throws NoSuchAlgorithmException, NoSuchProviderException, 586 NoSuchPaddingException 587 { 588 if ((provider == null) || (provider.length() == 0)) { 589 throw new IllegalArgumentException("Missing provider"); 590 } 591 Provider p = Security.getProvider(provider); 592 if (p == null) { 593 throw new NoSuchProviderException("No such provider: " + 594 provider); 595 } 596 return getInstance(transformation, p); 597 } 598 599 /** 600 * Returns a {@code Cipher} object that implements the specified 601 * transformation. 602 * 603 * <p> A new Cipher object encapsulating the 604 * CipherSpi implementation from the specified Provider 605 * object is returned. Note that the specified Provider object 606 * does not have to be registered in the provider list. 607 * 608 * @param transformation the name of the transformation, 609 * e.g., <i>DES/CBC/PKCS5Padding</i>. 610 * See the Cipher section in the <a href= 611 * "{@docRoot}/../technotes/guides/security/StandardNames.html#Cipher"> 612 * Java Cryptography Architecture Standard Algorithm Name Documentation</a> 613 * for information about standard transformation names. 614 * 615 * @param provider the provider. 616 * 617 * @return a cipher that implements the requested transformation. 618 * 619 * @exception NoSuchAlgorithmException if {@code transformation} 620 * is null, empty, in an invalid format, 621 * or if a CipherSpi implementation for the specified algorithm 622 * is not available from the specified Provider object. 623 * 624 * @exception NoSuchPaddingException if {@code transformation} 625 * contains a padding scheme that is not available. 626 * 627 * @exception IllegalArgumentException if the {@code provider} 628 * is null. 629 * 630 * @see java.security.Provider 631 */ 632 public static final Cipher getInstance(String transformation, 633 Provider provider) 634 throws NoSuchAlgorithmException, NoSuchPaddingException 635 { 636 if (provider == null) { 637 throw new IllegalArgumentException("Missing provider"); 638 } 639 Exception failure = null; 640 List<Transform> transforms = getTransforms(transformation); 641 boolean providerChecked = false; 642 String paddingError = null; 643 for (Transform tr : transforms) { 644 Service s = provider.getService("Cipher", tr.transform); 645 if (s == null) { 646 continue; 647 } 880 } 881 } 882 // no working provider found, fail 883 if (lastException instanceof InvalidKeyException) { 884 throw (InvalidKeyException)lastException; 885 } 886 if (lastException instanceof InvalidAlgorithmParameterException) { 887 throw (InvalidAlgorithmParameterException)lastException; 888 } 889 if (lastException instanceof RuntimeException) { 890 throw (RuntimeException)lastException; 891 } 892 String kName = (key != null) ? key.getClass().getName() : "(null)"; 893 throw new InvalidKeyException 894 ("No installed provider supports this key: " 895 + kName, lastException); 896 } 897 } 898 899 /** 900 * Returns the provider of this {@code Cipher} object. 901 * 902 * @return the provider of this {@code Cipher} object 903 */ 904 public final Provider getProvider() { 905 chooseFirstProvider(); 906 return this.provider; 907 } 908 909 /** 910 * Returns the algorithm name of this {@code Cipher} object. 911 * 912 * <p>This is the same name that was specified in one of the 913 * {@code getInstance} calls that created this {@code Cipher} 914 * object.. 915 * 916 * @return the algorithm name of this {@code Cipher} object. 917 */ 918 public final String getAlgorithm() { 919 return this.transformation; 920 } 921 922 /** 923 * Returns the block size (in bytes). 924 * 925 * @return the block size (in bytes), or 0 if the underlying algorithm is 926 * not a block cipher 927 */ 928 public final int getBlockSize() { 929 chooseFirstProvider(); 930 return spi.engineGetBlockSize(); 931 } 932 933 /** 934 * Returns the length in bytes that an output buffer would need to be in 935 * order to hold the result of the next {@code update} or 936 * {@code doFinal} operation, given the input length 937 * {@code inputLen} (in bytes). 938 * 939 * <p>This call takes into account any unprocessed (buffered) data from a 940 * previous {@code update} call, padding, and AEAD tagging. 941 * 942 * <p>The actual output length of the next {@code update} or 943 * {@code doFinal} call may be smaller than the length returned by 944 * this method. 945 * 946 * @param inputLen the input length (in bytes) 947 * 948 * @return the required output buffer size (in bytes) 949 * 950 * @exception IllegalStateException if this cipher is in a wrong state 951 * (e.g., has not yet been initialized) 952 */ 953 public final int getOutputSize(int inputLen) { 954 955 if (!initialized && !(this instanceof NullCipher)) { 956 throw new IllegalStateException("Cipher not initialized"); 957 } 958 if (inputLen < 0) { 959 throw new IllegalArgumentException("Input size must be equal " + 960 "to or greater than zero"); 961 } 962 chooseFirstProvider(); 963 return spi.engineGetOutputSize(inputLen); 1118 private static String getOpmodeString(int opmode) { 1119 switch (opmode) { 1120 case ENCRYPT_MODE: 1121 return "encryption"; 1122 case DECRYPT_MODE: 1123 return "decryption"; 1124 case WRAP_MODE: 1125 return "key wrapping"; 1126 case UNWRAP_MODE: 1127 return "key unwrapping"; 1128 default: 1129 return ""; 1130 } 1131 } 1132 1133 /** 1134 * Initializes this cipher with a key. 1135 * 1136 * <p>The cipher is initialized for one of the following four operations: 1137 * encryption, decryption, key wrapping or key unwrapping, depending 1138 * on the value of {@code opmode}. 1139 * 1140 * <p>If this cipher requires any algorithm parameters that cannot be 1141 * derived from the given {@code key}, the underlying cipher 1142 * implementation is supposed to generate the required parameters itself 1143 * (using provider-specific default or random values) if it is being 1144 * initialized for encryption or key wrapping, and raise an 1145 * {@code InvalidKeyException} if it is being 1146 * initialized for decryption or key unwrapping. 1147 * The generated parameters can be retrieved using 1148 * {@link #getParameters() getParameters} or 1149 * {@link #getIV() getIV} (if the parameter is an IV). 1150 * 1151 * <p>If this cipher requires algorithm parameters that cannot be 1152 * derived from the input parameters, and there are no reasonable 1153 * provider-specific default values, initialization will 1154 * necessarily fail. 1155 * 1156 * <p>If this cipher (including its underlying feedback or padding scheme) 1157 * requires any random bytes (e.g., for parameter generation), it will get 1158 * them using the {@link java.security.SecureRandom} 1159 * implementation of the highest-priority 1160 * installed provider as the source of randomness. 1161 * (If none of the installed providers supply an implementation of 1162 * SecureRandom, a system-provided source of randomness will be used.) 1163 * 1164 * <p>Note that when a Cipher object is initialized, it loses all 1165 * previously-acquired state. In other words, initializing a Cipher is 1166 * equivalent to creating a new instance of that Cipher and initializing 1167 * it. 1168 * 1169 * @param opmode the operation mode of this cipher (this is one of 1170 * the following: 1171 * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, 1172 * {@code WRAP_MODE} or {@code UNWRAP_MODE}) 1173 * @param key the key 1174 * 1175 * @exception InvalidKeyException if the given key is inappropriate for 1176 * initializing this cipher, or requires 1177 * algorithm parameters that cannot be 1178 * determined from the given key, or if the given key has a keysize that 1179 * exceeds the maximum allowable keysize (as determined from the 1180 * configured jurisdiction policy files). 1181 * @throws UnsupportedOperationException if (@code opmode} is 1182 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1183 * by the underlying {@code CipherSpi}. 1184 */ 1185 public final void init(int opmode, Key key) throws InvalidKeyException { 1186 init(opmode, key, JceSecurity.RANDOM); 1187 } 1188 1189 /** 1190 * Initializes this cipher with a key and a source of randomness. 1191 * 1192 * <p>The cipher is initialized for one of the following four operations: 1193 * encryption, decryption, key wrapping or key unwrapping, depending 1194 * on the value of {@code opmode}. 1195 * 1196 * <p>If this cipher requires any algorithm parameters that cannot be 1197 * derived from the given {@code key}, the underlying cipher 1198 * implementation is supposed to generate the required parameters itself 1199 * (using provider-specific default or random values) if it is being 1200 * initialized for encryption or key wrapping, and raise an 1201 * {@code InvalidKeyException} if it is being 1202 * initialized for decryption or key unwrapping. 1203 * The generated parameters can be retrieved using 1204 * {@link #getParameters() getParameters} or 1205 * {@link #getIV() getIV} (if the parameter is an IV). 1206 * 1207 * <p>If this cipher requires algorithm parameters that cannot be 1208 * derived from the input parameters, and there are no reasonable 1209 * provider-specific default values, initialization will 1210 * necessarily fail. 1211 * 1212 * <p>If this cipher (including its underlying feedback or padding scheme) 1213 * requires any random bytes (e.g., for parameter generation), it will get 1214 * them from {@code random}. 1215 * 1216 * <p>Note that when a Cipher object is initialized, it loses all 1217 * previously-acquired state. In other words, initializing a Cipher is 1218 * equivalent to creating a new instance of that Cipher and initializing 1219 * it. 1220 * 1221 * @param opmode the operation mode of this cipher (this is one of the 1222 * following: 1223 * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, 1224 * {@code WRAP_MODE} or {@code UNWRAP_MODE}) 1225 * @param key the encryption key 1226 * @param random the source of randomness 1227 * 1228 * @exception InvalidKeyException if the given key is inappropriate for 1229 * initializing this cipher, or requires 1230 * algorithm parameters that cannot be 1231 * determined from the given key, or if the given key has a keysize that 1232 * exceeds the maximum allowable keysize (as determined from the 1233 * configured jurisdiction policy files). 1234 * @throws UnsupportedOperationException if (@code opmode} is 1235 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1236 * by the underlying {@code CipherSpi}. 1237 */ 1238 public final void init(int opmode, Key key, SecureRandom random) 1239 throws InvalidKeyException 1240 { 1241 initialized = false; 1242 checkOpmode(opmode); 1243 1244 if (spi != null) { 1252 throw new InvalidKeyException(e); 1253 } 1254 } 1255 1256 initialized = true; 1257 this.opmode = opmode; 1258 1259 if (!skipDebug && pdebug != null) { 1260 pdebug.println("Cipher." + transformation + " " + 1261 getOpmodeString(opmode) + " algorithm from: " + 1262 this.provider.getName()); 1263 } 1264 } 1265 1266 /** 1267 * Initializes this cipher with a key and a set of algorithm 1268 * parameters. 1269 * 1270 * <p>The cipher is initialized for one of the following four operations: 1271 * encryption, decryption, key wrapping or key unwrapping, depending 1272 * on the value of {@code opmode}. 1273 * 1274 * <p>If this cipher requires any algorithm parameters and 1275 * {@code params} is null, the underlying cipher implementation is 1276 * supposed to generate the required parameters itself (using 1277 * provider-specific default or random values) if it is being 1278 * initialized for encryption or key wrapping, and raise an 1279 * {@code InvalidAlgorithmParameterException} if it is being 1280 * initialized for decryption or key unwrapping. 1281 * The generated parameters can be retrieved using 1282 * {@link #getParameters() getParameters} or 1283 * {@link #getIV() getIV} (if the parameter is an IV). 1284 * 1285 * <p>If this cipher requires algorithm parameters that cannot be 1286 * derived from the input parameters, and there are no reasonable 1287 * provider-specific default values, initialization will 1288 * necessarily fail. 1289 * 1290 * <p>If this cipher (including its underlying feedback or padding scheme) 1291 * requires any random bytes (e.g., for parameter generation), it will get 1292 * them using the {@link java.security.SecureRandom} 1293 * implementation of the highest-priority 1294 * installed provider as the source of randomness. 1295 * (If none of the installed providers supply an implementation of 1296 * SecureRandom, a system-provided source of randomness will be used.) 1297 * 1298 * <p>Note that when a Cipher object is initialized, it loses all 1299 * previously-acquired state. In other words, initializing a Cipher is 1300 * equivalent to creating a new instance of that Cipher and initializing 1301 * it. 1302 * 1303 * @param opmode the operation mode of this cipher (this is one of the 1304 * following: 1305 * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, 1306 * {@code WRAP_MODE} or {@code UNWRAP_MODE}) 1307 * @param key the encryption key 1308 * @param params the algorithm parameters 1309 * 1310 * @exception InvalidKeyException if the given key is inappropriate for 1311 * initializing this cipher, or its keysize exceeds the maximum allowable 1312 * keysize (as determined from the configured jurisdiction policy files). 1313 * @exception InvalidAlgorithmParameterException if the given algorithm 1314 * parameters are inappropriate for this cipher, 1315 * or this cipher requires 1316 * algorithm parameters and {@code params} is null, or the given 1317 * algorithm parameters imply a cryptographic strength that would exceed 1318 * the legal limits (as determined from the configured jurisdiction 1319 * policy files). 1320 * @throws UnsupportedOperationException if (@code opmode} is 1321 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1322 * by the underlying {@code CipherSpi}. 1323 */ 1324 public final void init(int opmode, Key key, AlgorithmParameterSpec params) 1325 throws InvalidKeyException, InvalidAlgorithmParameterException 1326 { 1327 init(opmode, key, params, JceSecurity.RANDOM); 1328 } 1329 1330 /** 1331 * Initializes this cipher with a key, a set of algorithm 1332 * parameters, and a source of randomness. 1333 * 1334 * <p>The cipher is initialized for one of the following four operations: 1335 * encryption, decryption, key wrapping or key unwrapping, depending 1336 * on the value of {@code opmode}. 1337 * 1338 * <p>If this cipher requires any algorithm parameters and 1339 * {@code params} is null, the underlying cipher implementation is 1340 * supposed to generate the required parameters itself (using 1341 * provider-specific default or random values) if it is being 1342 * initialized for encryption or key wrapping, and raise an 1343 * {@code InvalidAlgorithmParameterException} if it is being 1344 * initialized for decryption or key unwrapping. 1345 * The generated parameters can be retrieved using 1346 * {@link #getParameters() getParameters} or 1347 * {@link #getIV() getIV} (if the parameter is an IV). 1348 * 1349 * <p>If this cipher requires algorithm parameters that cannot be 1350 * derived from the input parameters, and there are no reasonable 1351 * provider-specific default values, initialization will 1352 * necessarily fail. 1353 * 1354 * <p>If this cipher (including its underlying feedback or padding scheme) 1355 * requires any random bytes (e.g., for parameter generation), it will get 1356 * them from {@code random}. 1357 * 1358 * <p>Note that when a Cipher object is initialized, it loses all 1359 * previously-acquired state. In other words, initializing a Cipher is 1360 * equivalent to creating a new instance of that Cipher and initializing 1361 * it. 1362 * 1363 * @param opmode the operation mode of this cipher (this is one of the 1364 * following: 1365 * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, 1366 * {@code WRAP_MODE} or {@code UNWRAP_MODE}) 1367 * @param key the encryption key 1368 * @param params the algorithm parameters 1369 * @param random the source of randomness 1370 * 1371 * @exception InvalidKeyException if the given key is inappropriate for 1372 * initializing this cipher, or its keysize exceeds the maximum allowable 1373 * keysize (as determined from the configured jurisdiction policy files). 1374 * @exception InvalidAlgorithmParameterException if the given algorithm 1375 * parameters are inappropriate for this cipher, 1376 * or this cipher requires 1377 * algorithm parameters and {@code params} is null, or the given 1378 * algorithm parameters imply a cryptographic strength that would exceed 1379 * the legal limits (as determined from the configured jurisdiction 1380 * policy files). 1381 * @throws UnsupportedOperationException if (@code opmode} is 1382 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1383 * by the underlying {@code CipherSpi}. 1384 */ 1385 public final void init(int opmode, Key key, AlgorithmParameterSpec params, 1386 SecureRandom random) 1387 throws InvalidKeyException, InvalidAlgorithmParameterException 1388 { 1389 initialized = false; 1390 checkOpmode(opmode); 1391 1392 if (spi != null) { 1393 checkCryptoPerm(spi, key, params); 1394 spi.engineInit(opmode, key, params, random); 1395 } else { 1396 chooseProvider(I_PARAMSPEC, opmode, key, params, null, random); 1397 } 1398 1399 initialized = true; 1400 this.opmode = opmode; 1401 1402 if (!skipDebug && pdebug != null) { 1403 pdebug.println("Cipher." + transformation + " " + 1404 getOpmodeString(opmode) + " algorithm from: " + 1405 this.provider.getName()); 1406 } 1407 } 1408 1409 /** 1410 * Initializes this cipher with a key and a set of algorithm 1411 * parameters. 1412 * 1413 * <p>The cipher is initialized for one of the following four operations: 1414 * encryption, decryption, key wrapping or key unwrapping, depending 1415 * on the value of {@code opmode}. 1416 * 1417 * <p>If this cipher requires any algorithm parameters and 1418 * {@code params} is null, the underlying cipher implementation is 1419 * supposed to generate the required parameters itself (using 1420 * provider-specific default or random values) if it is being 1421 * initialized for encryption or key wrapping, and raise an 1422 * {@code InvalidAlgorithmParameterException} if it is being 1423 * initialized for decryption or key unwrapping. 1424 * The generated parameters can be retrieved using 1425 * {@link #getParameters() getParameters} or 1426 * {@link #getIV() getIV} (if the parameter is an IV). 1427 * 1428 * <p>If this cipher requires algorithm parameters that cannot be 1429 * derived from the input parameters, and there are no reasonable 1430 * provider-specific default values, initialization will 1431 * necessarily fail. 1432 * 1433 * <p>If this cipher (including its underlying feedback or padding scheme) 1434 * requires any random bytes (e.g., for parameter generation), it will get 1435 * them using the {@link java.security.SecureRandom} 1436 * implementation of the highest-priority 1437 * installed provider as the source of randomness. 1438 * (If none of the installed providers supply an implementation of 1439 * SecureRandom, a system-provided source of randomness will be used.) 1440 * 1441 * <p>Note that when a Cipher object is initialized, it loses all 1442 * previously-acquired state. In other words, initializing a Cipher is 1443 * equivalent to creating a new instance of that Cipher and initializing 1444 * it. 1445 * 1446 * @param opmode the operation mode of this cipher (this is one of the 1447 * following: {@code ENCRYPT_MODE}, 1448 * {@code DECRYPT_MODE}, {@code WRAP_MODE} 1449 * or {@code UNWRAP_MODE}) 1450 * @param key the encryption key 1451 * @param params the algorithm parameters 1452 * 1453 * @exception InvalidKeyException if the given key is inappropriate for 1454 * initializing this cipher, or its keysize exceeds the maximum allowable 1455 * keysize (as determined from the configured jurisdiction policy files). 1456 * @exception InvalidAlgorithmParameterException if the given algorithm 1457 * parameters are inappropriate for this cipher, 1458 * or this cipher requires 1459 * algorithm parameters and {@code params} is null, or the given 1460 * algorithm parameters imply a cryptographic strength that would exceed 1461 * the legal limits (as determined from the configured jurisdiction 1462 * policy files). 1463 * @throws UnsupportedOperationException if (@code opmode} is 1464 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1465 * by the underlying {@code CipherSpi}. 1466 */ 1467 public final void init(int opmode, Key key, AlgorithmParameters params) 1468 throws InvalidKeyException, InvalidAlgorithmParameterException 1469 { 1470 init(opmode, key, params, JceSecurity.RANDOM); 1471 } 1472 1473 /** 1474 * Initializes this cipher with a key, a set of algorithm 1475 * parameters, and a source of randomness. 1476 * 1477 * <p>The cipher is initialized for one of the following four operations: 1478 * encryption, decryption, key wrapping or key unwrapping, depending 1479 * on the value of {@code opmode}. 1480 * 1481 * <p>If this cipher requires any algorithm parameters and 1482 * {@code params} is null, the underlying cipher implementation is 1483 * supposed to generate the required parameters itself (using 1484 * provider-specific default or random values) if it is being 1485 * initialized for encryption or key wrapping, and raise an 1486 * {@code InvalidAlgorithmParameterException} if it is being 1487 * initialized for decryption or key unwrapping. 1488 * The generated parameters can be retrieved using 1489 * {@link #getParameters() getParameters} or 1490 * {@link #getIV() getIV} (if the parameter is an IV). 1491 * 1492 * <p>If this cipher requires algorithm parameters that cannot be 1493 * derived from the input parameters, and there are no reasonable 1494 * provider-specific default values, initialization will 1495 * necessarily fail. 1496 * 1497 * <p>If this cipher (including its underlying feedback or padding scheme) 1498 * requires any random bytes (e.g., for parameter generation), it will get 1499 * them from {@code random}. 1500 * 1501 * <p>Note that when a Cipher object is initialized, it loses all 1502 * previously-acquired state. In other words, initializing a Cipher is 1503 * equivalent to creating a new instance of that Cipher and initializing 1504 * it. 1505 * 1506 * @param opmode the operation mode of this cipher (this is one of the 1507 * following: {@code ENCRYPT_MODE}, 1508 * {@code DECRYPT_MODE}, {@code WRAP_MODE} 1509 * or {@code UNWRAP_MODE}) 1510 * @param key the encryption key 1511 * @param params the algorithm parameters 1512 * @param random the source of randomness 1513 * 1514 * @exception InvalidKeyException if the given key is inappropriate for 1515 * initializing this cipher, or its keysize exceeds the maximum allowable 1516 * keysize (as determined from the configured jurisdiction policy files). 1517 * @exception InvalidAlgorithmParameterException if the given algorithm 1518 * parameters are inappropriate for this cipher, 1519 * or this cipher requires 1520 * algorithm parameters and {@code params} is null, or the given 1521 * algorithm parameters imply a cryptographic strength that would exceed 1522 * the legal limits (as determined from the configured jurisdiction 1523 * policy files). 1524 * @throws UnsupportedOperationException if (@code opmode} is 1525 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1526 * by the underlying {@code CipherSpi}. 1527 */ 1528 public final void init(int opmode, Key key, AlgorithmParameters params, 1529 SecureRandom random) 1530 throws InvalidKeyException, InvalidAlgorithmParameterException 1531 { 1532 initialized = false; 1533 checkOpmode(opmode); 1534 1535 if (spi != null) { 1536 checkCryptoPerm(spi, key, params); 1537 spi.engineInit(opmode, key, params, random); 1538 } else { 1539 chooseProvider(I_PARAMS, opmode, key, null, params, random); 1540 } 1541 1542 initialized = true; 1543 this.opmode = opmode; 1544 1545 if (!skipDebug && pdebug != null) { 1546 pdebug.println("Cipher." + transformation + " " + 1547 getOpmodeString(opmode) + " algorithm from: " + 1548 this.provider.getName()); 1549 } 1550 } 1551 1552 /** 1553 * Initializes this cipher with the public key from the given certificate. 1554 * <p> The cipher is initialized for one of the following four operations: 1555 * encryption, decryption, key wrapping or key unwrapping, depending 1556 * on the value of {@code opmode}. 1557 * 1558 * <p>If the certificate is of type X.509 and has a <i>key usage</i> 1559 * extension field marked as critical, and the value of the <i>key usage</i> 1560 * extension field implies that the public key in 1561 * the certificate and its corresponding private key are not 1562 * supposed to be used for the operation represented by the value 1563 * of {@code opmode}, 1564 * an {@code InvalidKeyException} 1565 * is thrown. 1566 * 1567 * <p> If this cipher requires any algorithm parameters that cannot be 1568 * derived from the public key in the given certificate, the underlying 1569 * cipher 1570 * implementation is supposed to generate the required parameters itself 1571 * (using provider-specific default or random values) if it is being 1572 * initialized for encryption or key wrapping, and raise an 1573 * {@code InvalidKeyException} if it is being initialized for decryption or 1574 * key unwrapping. 1575 * The generated parameters can be retrieved using 1576 * {@link #getParameters() getParameters} or 1577 * {@link #getIV() getIV} (if the parameter is an IV). 1578 * 1579 * <p>If this cipher requires algorithm parameters that cannot be 1580 * derived from the input parameters, and there are no reasonable 1581 * provider-specific default values, initialization will 1582 * necessarily fail. 1583 * 1584 * <p>If this cipher (including its underlying feedback or padding scheme) 1585 * requires any random bytes (e.g., for parameter generation), it will get 1586 * them using the 1587 * {@code SecureRandom} 1588 * implementation of the highest-priority 1589 * installed provider as the source of randomness. 1590 * (If none of the installed providers supply an implementation of 1591 * SecureRandom, a system-provided source of randomness will be used.) 1592 * 1593 * <p>Note that when a Cipher object is initialized, it loses all 1594 * previously-acquired state. In other words, initializing a Cipher is 1595 * equivalent to creating a new instance of that Cipher and initializing 1596 * it. 1597 * 1598 * @param opmode the operation mode of this cipher (this is one of the 1599 * following: 1600 * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, 1601 * {@code WRAP_MODE} or {@code UNWRAP_MODE}) 1602 * @param certificate the certificate 1603 * 1604 * @exception InvalidKeyException if the public key in the given 1605 * certificate is inappropriate for initializing this cipher, or this 1606 * cipher requires algorithm parameters that cannot be determined from the 1607 * public key in the given certificate, or the keysize of the public key 1608 * in the given certificate has a keysize that exceeds the maximum 1609 * allowable keysize (as determined by the configured jurisdiction policy 1610 * files). 1611 * @throws UnsupportedOperationException if (@code opmode} is 1612 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1613 * by the underlying {@code CipherSpi}. 1614 */ 1615 public final void init(int opmode, Certificate certificate) 1616 throws InvalidKeyException 1617 { 1618 init(opmode, certificate, JceSecurity.RANDOM); 1619 } 1620 1621 /** 1622 * Initializes this cipher with the public key from the given certificate 1623 * and 1624 * a source of randomness. 1625 * 1626 * <p>The cipher is initialized for one of the following four operations: 1627 * encryption, decryption, key wrapping 1628 * or key unwrapping, depending on 1629 * the value of {@code opmode}. 1630 * 1631 * <p>If the certificate is of type X.509 and has a <i>key usage</i> 1632 * extension field marked as critical, and the value of the <i>key usage</i> 1633 * extension field implies that the public key in 1634 * the certificate and its corresponding private key are not 1635 * supposed to be used for the operation represented by the value of 1636 * {@code opmode}, 1637 * an {@code InvalidKeyException} 1638 * is thrown. 1639 * 1640 * <p>If this cipher requires any algorithm parameters that cannot be 1641 * derived from the public key in the given {@code certificate}, 1642 * the underlying cipher 1643 * implementation is supposed to generate the required parameters itself 1644 * (using provider-specific default or random values) if it is being 1645 * initialized for encryption or key wrapping, and raise an 1646 * {@code InvalidKeyException} if it is being 1647 * initialized for decryption or key unwrapping. 1648 * The generated parameters can be retrieved using 1649 * {@link #getParameters() getParameters} or 1650 * {@link #getIV() getIV} (if the parameter is an IV). 1651 * 1652 * <p>If this cipher requires algorithm parameters that cannot be 1653 * derived from the input parameters, and there are no reasonable 1654 * provider-specific default values, initialization will 1655 * necessarily fail. 1656 * 1657 * <p>If this cipher (including its underlying feedback or padding scheme) 1658 * requires any random bytes (e.g., for parameter generation), it will get 1659 * them from {@code random}. 1660 * 1661 * <p>Note that when a Cipher object is initialized, it loses all 1662 * previously-acquired state. In other words, initializing a Cipher is 1663 * equivalent to creating a new instance of that Cipher and initializing 1664 * it. 1665 * 1666 * @param opmode the operation mode of this cipher (this is one of the 1667 * following: 1668 * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, 1669 * {@code WRAP_MODE} or {@code UNWRAP_MODE}) 1670 * @param certificate the certificate 1671 * @param random the source of randomness 1672 * 1673 * @exception InvalidKeyException if the public key in the given 1674 * certificate is inappropriate for initializing this cipher, or this 1675 * cipher 1676 * requires algorithm parameters that cannot be determined from the 1677 * public key in the given certificate, or the keysize of the public key 1678 * in the given certificate has a keysize that exceeds the maximum 1679 * allowable keysize (as determined by the configured jurisdiction policy 1680 * files). 1681 * @throws UnsupportedOperationException if (@code opmode} is 1682 * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented 1683 * by the underlying {@code CipherSpi}. 1684 */ 1685 public final void init(int opmode, Certificate certificate, 1686 SecureRandom random) 1687 throws InvalidKeyException 1688 { 1689 initialized = false; 1745 * @throws IllegalStateException if Cipher object is not in valid state. 1746 */ 1747 private void checkCipherState() { 1748 if (!(this instanceof NullCipher)) { 1749 if (!initialized) { 1750 throw new IllegalStateException("Cipher not initialized"); 1751 } 1752 if ((opmode != Cipher.ENCRYPT_MODE) && 1753 (opmode != Cipher.DECRYPT_MODE)) { 1754 throw new IllegalStateException("Cipher not initialized " + 1755 "for encryption/decryption"); 1756 } 1757 } 1758 } 1759 1760 /** 1761 * Continues a multiple-part encryption or decryption operation 1762 * (depending on how this cipher was initialized), processing another data 1763 * part. 1764 * 1765 * <p>The bytes in the {@code input} buffer are processed, and the 1766 * result is stored in a new buffer. 1767 * 1768 * <p>If {@code input} has a length of zero, this method returns 1769 * {@code null}. 1770 * 1771 * @param input the input buffer 1772 * 1773 * @return the new buffer with the result, or null if the underlying 1774 * cipher is a block cipher and the input data is too short to result in a 1775 * new block. 1776 * 1777 * @exception IllegalStateException if this cipher is in a wrong state 1778 * (e.g., has not been initialized) 1779 */ 1780 public final byte[] update(byte[] input) { 1781 checkCipherState(); 1782 1783 // Input sanity check 1784 if (input == null) { 1785 throw new IllegalArgumentException("Null input buffer"); 1786 } 1787 1788 chooseFirstProvider(); 1789 if (input.length == 0) { 1790 return null; 1791 } 1792 return spi.engineUpdate(input, 0, input.length); 1793 } 1794 1795 /** 1796 * Continues a multiple-part encryption or decryption operation 1797 * (depending on how this cipher was initialized), processing another data 1798 * part. 1799 * 1800 * <p>The first {@code inputLen} bytes in the {@code input} 1801 * buffer, starting at {@code inputOffset} inclusive, are processed, 1802 * and the result is stored in a new buffer. 1803 * 1804 * <p>If {@code inputLen} is zero, this method returns 1805 * {@code null}. 1806 * 1807 * @param input the input buffer 1808 * @param inputOffset the offset in {@code input} where the input 1809 * starts 1810 * @param inputLen the input length 1811 * 1812 * @return the new buffer with the result, or null if the underlying 1813 * cipher is a block cipher and the input data is too short to result in a 1814 * new block. 1815 * 1816 * @exception IllegalStateException if this cipher is in a wrong state 1817 * (e.g., has not been initialized) 1818 */ 1819 public final byte[] update(byte[] input, int inputOffset, int inputLen) { 1820 checkCipherState(); 1821 1822 // Input sanity check 1823 if (input == null || inputOffset < 0 1824 || inputLen > (input.length - inputOffset) || inputLen < 0) { 1825 throw new IllegalArgumentException("Bad arguments"); 1826 } 1827 1828 chooseFirstProvider(); 1829 if (inputLen == 0) { 1830 return null; 1831 } 1832 return spi.engineUpdate(input, inputOffset, inputLen); 1833 } 1834 1835 /** 1836 * Continues a multiple-part encryption or decryption operation 1837 * (depending on how this cipher was initialized), processing another data 1838 * part. 1839 * 1840 * <p>The first {@code inputLen} bytes in the {@code input} 1841 * buffer, starting at {@code inputOffset} inclusive, are processed, 1842 * and the result is stored in the {@code output} buffer. 1843 * 1844 * <p>If the {@code output} buffer is too small to hold the result, 1845 * a {@code ShortBufferException} is thrown. In this case, repeat this 1846 * call with a larger output buffer. Use 1847 * {@link #getOutputSize(int) getOutputSize} to determine how big 1848 * the output buffer should be. 1849 * 1850 * <p>If {@code inputLen} is zero, this method returns 1851 * a length of zero. 1852 * 1853 * <p>Note: this method should be copy-safe, which means the 1854 * {@code input} and {@code output} buffers can reference 1855 * the same byte array and no unprocessed input data is overwritten 1856 * when the result is copied into the output buffer. 1857 * 1858 * @param input the input buffer 1859 * @param inputOffset the offset in {@code input} where the input 1860 * starts 1861 * @param inputLen the input length 1862 * @param output the buffer for the result 1863 * 1864 * @return the number of bytes stored in {@code output} 1865 * 1866 * @exception IllegalStateException if this cipher is in a wrong state 1867 * (e.g., has not been initialized) 1868 * @exception ShortBufferException if the given output buffer is too small 1869 * to hold the result 1870 */ 1871 public final int update(byte[] input, int inputOffset, int inputLen, 1872 byte[] output) 1873 throws ShortBufferException { 1874 checkCipherState(); 1875 1876 // Input sanity check 1877 if (input == null || inputOffset < 0 1878 || inputLen > (input.length - inputOffset) || inputLen < 0) { 1879 throw new IllegalArgumentException("Bad arguments"); 1880 } 1881 1882 chooseFirstProvider(); 1883 if (inputLen == 0) { 1884 return 0; 1885 } 1886 return spi.engineUpdate(input, inputOffset, inputLen, 1887 output, 0); 1888 } 1889 1890 /** 1891 * Continues a multiple-part encryption or decryption operation 1892 * (depending on how this cipher was initialized), processing another data 1893 * part. 1894 * 1895 * <p>The first {@code inputLen} bytes in the {@code input} 1896 * buffer, starting at {@code inputOffset} inclusive, are processed, 1897 * and the result is stored in the {@code output} buffer, starting at 1898 * {@code outputOffset} inclusive. 1899 * 1900 * <p>If the {@code output} buffer is too small to hold the result, 1901 * a {@code ShortBufferException} is thrown. In this case, repeat this 1902 * call with a larger output buffer. Use 1903 * {@link #getOutputSize(int) getOutputSize} to determine how big 1904 * the output buffer should be. 1905 * 1906 * <p>If {@code inputLen} is zero, this method returns 1907 * a length of zero. 1908 * 1909 * <p>Note: this method should be copy-safe, which means the 1910 * {@code input} and {@code output} buffers can reference 1911 * the same byte array and no unprocessed input data is overwritten 1912 * when the result is copied into the output buffer. 1913 * 1914 * @param input the input buffer 1915 * @param inputOffset the offset in {@code input} where the input 1916 * starts 1917 * @param inputLen the input length 1918 * @param output the buffer for the result 1919 * @param outputOffset the offset in {@code output} where the result 1920 * is stored 1921 * 1922 * @return the number of bytes stored in {@code output} 1923 * 1924 * @exception IllegalStateException if this cipher is in a wrong state 1925 * (e.g., has not been initialized) 1926 * @exception ShortBufferException if the given output buffer is too small 1927 * to hold the result 1928 */ 1929 public final int update(byte[] input, int inputOffset, int inputLen, 1930 byte[] output, int outputOffset) 1931 throws ShortBufferException { 1932 checkCipherState(); 1933 1934 // Input sanity check 1935 if (input == null || inputOffset < 0 1936 || inputLen > (input.length - inputOffset) || inputLen < 0 1937 || outputOffset < 0) { 1938 throw new IllegalArgumentException("Bad arguments"); 1939 } 1940 1941 chooseFirstProvider(); 1942 if (inputLen == 0) { 1943 return 0; 1944 } 1945 return spi.engineUpdate(input, inputOffset, inputLen, 1946 output, outputOffset); 1947 } 1948 1949 /** 1950 * Continues a multiple-part encryption or decryption operation 1951 * (depending on how this cipher was initialized), processing another data 1952 * part. 1953 * 1954 * <p>All {@code input.remaining()} bytes starting at 1955 * {@code input.position()} are processed. The result is stored 1956 * in the output buffer. 1957 * Upon return, the input buffer's position will be equal 1958 * to its limit; its limit will not have changed. The output buffer's 1959 * position will have advanced by n, where n is the value returned 1960 * by this method; the output buffer's limit will not have changed. 1961 * 1962 * <p>If {@code output.remaining()} bytes are insufficient to 1963 * hold the result, a {@code ShortBufferException} is thrown. 1964 * In this case, repeat this call with a larger output buffer. Use 1965 * {@link #getOutputSize(int) getOutputSize} to determine how big 1966 * the output buffer should be. 1967 * 1968 * <p>Note: this method should be copy-safe, which means the 1969 * {@code input} and {@code output} buffers can reference 1970 * the same block of memory and no unprocessed input data is overwritten 1971 * when the result is copied into the output buffer. 1972 * 1973 * @param input the input ByteBuffer 1974 * @param output the output ByteByffer 1975 * 1976 * @return the number of bytes stored in {@code output} 1977 * 1978 * @exception IllegalStateException if this cipher is in a wrong state 1979 * (e.g., has not been initialized) 1980 * @exception IllegalArgumentException if input and output are the 1981 * same object 1982 * @exception ReadOnlyBufferException if the output buffer is read-only 1983 * @exception ShortBufferException if there is insufficient space in the 1984 * output buffer 1985 * @since 1.5 1986 */ 1987 public final int update(ByteBuffer input, ByteBuffer output) 1988 throws ShortBufferException { 1989 checkCipherState(); 1990 1991 if ((input == null) || (output == null)) { 1992 throw new IllegalArgumentException("Buffers must not be null"); 1993 } 1994 if (input == output) { 1995 throw new IllegalArgumentException("Input and output buffers must " 1996 + "not be the same object, consider using buffer.duplicate()"); 1997 } 1998 if (output.isReadOnly()) { 1999 throw new ReadOnlyBufferException(); 2000 } 2001 2002 chooseFirstProvider(); 2003 return spi.engineUpdate(input, output); 2004 } 2005 2006 /** 2007 * Finishes a multiple-part encryption or decryption operation, depending 2008 * on how this cipher was initialized. 2009 * 2010 * <p>Input data that may have been buffered during a previous 2011 * {@code update} operation is processed, with padding (if requested) 2012 * being applied. 2013 * If an AEAD mode such as GCM/CCM is being used, the authentication 2014 * tag is appended in the case of encryption, or verified in the 2015 * case of decryption. 2016 * The result is stored in a new buffer. 2017 * 2018 * <p>Upon finishing, this method resets this cipher object to the state 2019 * it was in when previously initialized via a call to {@code init}. 2020 * That is, the object is reset and available to encrypt or decrypt 2021 * (depending on the operation mode that was specified in the call to 2022 * {@code init}) more data. 2023 * 2024 * <p>Note: if any exception is thrown, this cipher object may need to 2025 * be reset before it can be used again. 2026 * 2027 * @return the new buffer with the result 2028 * 2029 * @exception IllegalStateException if this cipher is in a wrong state 2030 * (e.g., has not been initialized) 2031 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2032 * no padding has been requested (only in encryption mode), and the total 2033 * input length of the data processed by this cipher is not a multiple of 2034 * block size; or if this encryption algorithm is unable to 2035 * process the input data provided. 2036 * @exception BadPaddingException if this cipher is in decryption mode, 2037 * and (un)padding has been requested, but the decrypted data is not 2038 * bounded by the appropriate padding bytes 2039 * @exception AEADBadTagException if this cipher is decrypting in an 2040 * AEAD mode (such as GCM/CCM), and the received authentication tag 2041 * does not match the calculated value 2042 */ 2043 public final byte[] doFinal() 2044 throws IllegalBlockSizeException, BadPaddingException { 2045 checkCipherState(); 2046 2047 chooseFirstProvider(); 2048 return spi.engineDoFinal(null, 0, 0); 2049 } 2050 2051 /** 2052 * Finishes a multiple-part encryption or decryption operation, depending 2053 * on how this cipher was initialized. 2054 * 2055 * <p>Input data that may have been buffered during a previous 2056 * {@code update} operation is processed, with padding (if requested) 2057 * being applied. 2058 * If an AEAD mode such as GCM/CCM is being used, the authentication 2059 * tag is appended in the case of encryption, or verified in the 2060 * case of decryption. 2061 * The result is stored in the {@code output} buffer, starting at 2062 * {@code outputOffset} inclusive. 2063 * 2064 * <p>If the {@code output} buffer is too small to hold the result, 2065 * a {@code ShortBufferException} is thrown. In this case, repeat this 2066 * call with a larger output buffer. Use 2067 * {@link #getOutputSize(int) getOutputSize} to determine how big 2068 * the output buffer should be. 2069 * 2070 * <p>Upon finishing, this method resets this cipher object to the state 2071 * it was in when previously initialized via a call to {@code init}. 2072 * That is, the object is reset and available to encrypt or decrypt 2073 * (depending on the operation mode that was specified in the call to 2074 * {@code init}) more data. 2075 * 2076 * <p>Note: if any exception is thrown, this cipher object may need to 2077 * be reset before it can be used again. 2078 * 2079 * @param output the buffer for the result 2080 * @param outputOffset the offset in {@code output} where the result 2081 * is stored 2082 * 2083 * @return the number of bytes stored in {@code output} 2084 * 2085 * @exception IllegalStateException if this cipher is in a wrong state 2086 * (e.g., has not been initialized) 2087 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2088 * no padding has been requested (only in encryption mode), and the total 2089 * input length of the data processed by this cipher is not a multiple of 2090 * block size; or if this encryption algorithm is unable to 2091 * process the input data provided. 2092 * @exception ShortBufferException if the given output buffer is too small 2093 * to hold the result 2094 * @exception BadPaddingException if this cipher is in decryption mode, 2095 * and (un)padding has been requested, but the decrypted data is not 2096 * bounded by the appropriate padding bytes 2097 * @exception AEADBadTagException if this cipher is decrypting in an 2098 * AEAD mode (such as GCM/CCM), and the received authentication tag 2099 * does not match the calculated value 2100 */ 2101 public final int doFinal(byte[] output, int outputOffset) 2102 throws IllegalBlockSizeException, ShortBufferException, 2103 BadPaddingException { 2104 checkCipherState(); 2105 2106 // Input sanity check 2107 if ((output == null) || (outputOffset < 0)) { 2108 throw new IllegalArgumentException("Bad arguments"); 2109 } 2110 2111 chooseFirstProvider(); 2112 return spi.engineDoFinal(null, 0, 0, output, outputOffset); 2113 } 2114 2115 /** 2116 * Encrypts or decrypts data in a single-part operation, or finishes a 2117 * multiple-part operation. The data is encrypted or decrypted, 2118 * depending on how this cipher was initialized. 2119 * 2120 * <p>The bytes in the {@code input} buffer, and any input bytes that 2121 * may have been buffered during a previous {@code update} operation, 2122 * are processed, with padding (if requested) being applied. 2123 * If an AEAD mode such as GCM/CCM is being used, the authentication 2124 * tag is appended in the case of encryption, or verified in the 2125 * case of decryption. 2126 * The result is stored in a new buffer. 2127 * 2128 * <p>Upon finishing, this method resets this cipher object to the state 2129 * it was in when previously initialized via a call to {@code init}. 2130 * That is, the object is reset and available to encrypt or decrypt 2131 * (depending on the operation mode that was specified in the call to 2132 * {@code init}) more data. 2133 * 2134 * <p>Note: if any exception is thrown, this cipher object may need to 2135 * be reset before it can be used again. 2136 * 2137 * @param input the input buffer 2138 * 2139 * @return the new buffer with the result 2140 * 2141 * @exception IllegalStateException if this cipher is in a wrong state 2142 * (e.g., has not been initialized) 2143 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2144 * no padding has been requested (only in encryption mode), and the total 2145 * input length of the data processed by this cipher is not a multiple of 2146 * block size; or if this encryption algorithm is unable to 2147 * process the input data provided. 2148 * @exception BadPaddingException if this cipher is in decryption mode, 2149 * and (un)padding has been requested, but the decrypted data is not 2150 * bounded by the appropriate padding bytes 2151 * @exception AEADBadTagException if this cipher is decrypting in an 2152 * AEAD mode (such as GCM/CCM), and the received authentication tag 2153 * does not match the calculated value 2154 */ 2155 public final byte[] doFinal(byte[] input) 2156 throws IllegalBlockSizeException, BadPaddingException { 2157 checkCipherState(); 2158 2159 // Input sanity check 2160 if (input == null) { 2161 throw new IllegalArgumentException("Null input buffer"); 2162 } 2163 2164 chooseFirstProvider(); 2165 return spi.engineDoFinal(input, 0, input.length); 2166 } 2167 2168 /** 2169 * Encrypts or decrypts data in a single-part operation, or finishes a 2170 * multiple-part operation. The data is encrypted or decrypted, 2171 * depending on how this cipher was initialized. 2172 * 2173 * <p>The first {@code inputLen} bytes in the {@code input} 2174 * buffer, starting at {@code inputOffset} inclusive, and any input 2175 * bytes that may have been buffered during a previous {@code update} 2176 * operation, are processed, with padding (if requested) being applied. 2177 * If an AEAD mode such as GCM/CCM is being used, the authentication 2178 * tag is appended in the case of encryption, or verified in the 2179 * case of decryption. 2180 * The result is stored in a new buffer. 2181 * 2182 * <p>Upon finishing, this method resets this cipher object to the state 2183 * it was in when previously initialized via a call to {@code init}. 2184 * That is, the object is reset and available to encrypt or decrypt 2185 * (depending on the operation mode that was specified in the call to 2186 * {@code init}) more data. 2187 * 2188 * <p>Note: if any exception is thrown, this cipher object may need to 2189 * be reset before it can be used again. 2190 * 2191 * @param input the input buffer 2192 * @param inputOffset the offset in {@code input} where the input 2193 * starts 2194 * @param inputLen the input length 2195 * 2196 * @return the new buffer with the result 2197 * 2198 * @exception IllegalStateException if this cipher is in a wrong state 2199 * (e.g., has not been initialized) 2200 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2201 * no padding has been requested (only in encryption mode), and the total 2202 * input length of the data processed by this cipher is not a multiple of 2203 * block size; or if this encryption algorithm is unable to 2204 * process the input data provided. 2205 * @exception BadPaddingException if this cipher is in decryption mode, 2206 * and (un)padding has been requested, but the decrypted data is not 2207 * bounded by the appropriate padding bytes 2208 * @exception AEADBadTagException if this cipher is decrypting in an 2209 * AEAD mode (such as GCM/CCM), and the received authentication tag 2210 * does not match the calculated value 2211 */ 2212 public final byte[] doFinal(byte[] input, int inputOffset, int inputLen) 2213 throws IllegalBlockSizeException, BadPaddingException { 2214 checkCipherState(); 2215 2216 // Input sanity check 2217 if (input == null || inputOffset < 0 2218 || inputLen > (input.length - inputOffset) || inputLen < 0) { 2219 throw new IllegalArgumentException("Bad arguments"); 2220 } 2221 2222 chooseFirstProvider(); 2223 return spi.engineDoFinal(input, inputOffset, inputLen); 2224 } 2225 2226 /** 2227 * Encrypts or decrypts data in a single-part operation, or finishes a 2228 * multiple-part operation. The data is encrypted or decrypted, 2229 * depending on how this cipher was initialized. 2230 * 2231 * <p>The first {@code inputLen} bytes in the {@code input} 2232 * buffer, starting at {@code inputOffset} inclusive, and any input 2233 * bytes that may have been buffered during a previous {@code update} 2234 * operation, are processed, with padding (if requested) being applied. 2235 * If an AEAD mode such as GCM/CCM is being used, the authentication 2236 * tag is appended in the case of encryption, or verified in the 2237 * case of decryption. 2238 * The result is stored in the {@code output} buffer. 2239 * 2240 * <p>If the {@code output} buffer is too small to hold the result, 2241 * a {@code ShortBufferException} is thrown. In this case, repeat this 2242 * call with a larger output buffer. Use 2243 * {@link #getOutputSize(int) getOutputSize} to determine how big 2244 * the output buffer should be. 2245 * 2246 * <p>Upon finishing, this method resets this cipher object to the state 2247 * it was in when previously initialized via a call to {@code init}. 2248 * That is, the object is reset and available to encrypt or decrypt 2249 * (depending on the operation mode that was specified in the call to 2250 * {@code init}) more data. 2251 * 2252 * <p>Note: if any exception is thrown, this cipher object may need to 2253 * be reset before it can be used again. 2254 * 2255 * <p>Note: this method should be copy-safe, which means the 2256 * {@code input} and {@code output} buffers can reference 2257 * the same byte array and no unprocessed input data is overwritten 2258 * when the result is copied into the output buffer. 2259 * 2260 * @param input the input buffer 2261 * @param inputOffset the offset in {@code input} where the input 2262 * starts 2263 * @param inputLen the input length 2264 * @param output the buffer for the result 2265 * 2266 * @return the number of bytes stored in {@code output} 2267 * 2268 * @exception IllegalStateException if this cipher is in a wrong state 2269 * (e.g., has not been initialized) 2270 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2271 * no padding has been requested (only in encryption mode), and the total 2272 * input length of the data processed by this cipher is not a multiple of 2273 * block size; or if this encryption algorithm is unable to 2274 * process the input data provided. 2275 * @exception ShortBufferException if the given output buffer is too small 2276 * to hold the result 2277 * @exception BadPaddingException if this cipher is in decryption mode, 2278 * and (un)padding has been requested, but the decrypted data is not 2279 * bounded by the appropriate padding bytes 2280 * @exception AEADBadTagException if this cipher is decrypting in an 2281 * AEAD mode (such as GCM/CCM), and the received authentication tag 2282 * does not match the calculated value 2283 */ 2284 public final int doFinal(byte[] input, int inputOffset, int inputLen, 2285 byte[] output) 2286 throws ShortBufferException, IllegalBlockSizeException, 2287 BadPaddingException { 2288 checkCipherState(); 2289 2290 // Input sanity check 2291 if (input == null || inputOffset < 0 2292 || inputLen > (input.length - inputOffset) || inputLen < 0) { 2293 throw new IllegalArgumentException("Bad arguments"); 2294 } 2295 2296 chooseFirstProvider(); 2297 return spi.engineDoFinal(input, inputOffset, inputLen, 2298 output, 0); 2299 } 2300 2301 /** 2302 * Encrypts or decrypts data in a single-part operation, or finishes a 2303 * multiple-part operation. The data is encrypted or decrypted, 2304 * depending on how this cipher was initialized. 2305 * 2306 * <p>The first {@code inputLen} bytes in the {@code input} 2307 * buffer, starting at {@code inputOffset} inclusive, and any input 2308 * bytes that may have been buffered during a previous 2309 * {@code update} operation, are processed, with padding 2310 * (if requested) being applied. 2311 * If an AEAD mode such as GCM/CCM is being used, the authentication 2312 * tag is appended in the case of encryption, or verified in the 2313 * case of decryption. 2314 * The result is stored in the {@code output} buffer, starting at 2315 * {@code outputOffset} inclusive. 2316 * 2317 * <p>If the {@code output} buffer is too small to hold the result, 2318 * a {@code ShortBufferException} is thrown. In this case, repeat this 2319 * call with a larger output buffer. Use 2320 * {@link #getOutputSize(int) getOutputSize} to determine how big 2321 * the output buffer should be. 2322 * 2323 * <p>Upon finishing, this method resets this cipher object to the state 2324 * it was in when previously initialized via a call to {@code init}. 2325 * That is, the object is reset and available to encrypt or decrypt 2326 * (depending on the operation mode that was specified in the call to 2327 * {@code init}) more data. 2328 * 2329 * <p>Note: if any exception is thrown, this cipher object may need to 2330 * be reset before it can be used again. 2331 * 2332 * <p>Note: this method should be copy-safe, which means the 2333 * {@code input} and {@code output} buffers can reference 2334 * the same byte array and no unprocessed input data is overwritten 2335 * when the result is copied into the output buffer. 2336 * 2337 * @param input the input buffer 2338 * @param inputOffset the offset in {@code input} where the input 2339 * starts 2340 * @param inputLen the input length 2341 * @param output the buffer for the result 2342 * @param outputOffset the offset in {@code output} where the result 2343 * is stored 2344 * 2345 * @return the number of bytes stored in {@code output} 2346 * 2347 * @exception IllegalStateException if this cipher is in a wrong state 2348 * (e.g., has not been initialized) 2349 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2350 * no padding has been requested (only in encryption mode), and the total 2351 * input length of the data processed by this cipher is not a multiple of 2352 * block size; or if this encryption algorithm is unable to 2353 * process the input data provided. 2354 * @exception ShortBufferException if the given output buffer is too small 2355 * to hold the result 2356 * @exception BadPaddingException if this cipher is in decryption mode, 2357 * and (un)padding has been requested, but the decrypted data is not 2358 * bounded by the appropriate padding bytes 2359 * @exception AEADBadTagException if this cipher is decrypting in an 2360 * AEAD mode (such as GCM/CCM), and the received authentication tag 2361 * does not match the calculated value 2362 */ 2363 public final int doFinal(byte[] input, int inputOffset, int inputLen, 2364 byte[] output, int outputOffset) 2365 throws ShortBufferException, IllegalBlockSizeException, 2366 BadPaddingException { 2367 checkCipherState(); 2368 2369 // Input sanity check 2370 if (input == null || inputOffset < 0 2371 || inputLen > (input.length - inputOffset) || inputLen < 0 2372 || outputOffset < 0) { 2373 throw new IllegalArgumentException("Bad arguments"); 2374 } 2375 2376 chooseFirstProvider(); 2377 return spi.engineDoFinal(input, inputOffset, inputLen, 2378 output, outputOffset); 2379 } 2380 2381 /** 2382 * Encrypts or decrypts data in a single-part operation, or finishes a 2383 * multiple-part operation. The data is encrypted or decrypted, 2384 * depending on how this cipher was initialized. 2385 * 2386 * <p>All {@code input.remaining()} bytes starting at 2387 * {@code input.position()} are processed. 2388 * If an AEAD mode such as GCM/CCM is being used, the authentication 2389 * tag is appended in the case of encryption, or verified in the 2390 * case of decryption. 2391 * The result is stored in the output buffer. 2392 * Upon return, the input buffer's position will be equal 2393 * to its limit; its limit will not have changed. The output buffer's 2394 * position will have advanced by n, where n is the value returned 2395 * by this method; the output buffer's limit will not have changed. 2396 * 2397 * <p>If {@code output.remaining()} bytes are insufficient to 2398 * hold the result, a {@code ShortBufferException} is thrown. 2399 * In this case, repeat this call with a larger output buffer. Use 2400 * {@link #getOutputSize(int) getOutputSize} to determine how big 2401 * the output buffer should be. 2402 * 2403 * <p>Upon finishing, this method resets this cipher object to the state 2404 * it was in when previously initialized via a call to {@code init}. 2405 * That is, the object is reset and available to encrypt or decrypt 2406 * (depending on the operation mode that was specified in the call to 2407 * {@code init}) more data. 2408 * 2409 * <p>Note: if any exception is thrown, this cipher object may need to 2410 * be reset before it can be used again. 2411 * 2412 * <p>Note: this method should be copy-safe, which means the 2413 * {@code input} and {@code output} buffers can reference 2414 * the same byte array and no unprocessed input data is overwritten 2415 * when the result is copied into the output buffer. 2416 * 2417 * @param input the input ByteBuffer 2418 * @param output the output ByteBuffer 2419 * 2420 * @return the number of bytes stored in {@code output} 2421 * 2422 * @exception IllegalStateException if this cipher is in a wrong state 2423 * (e.g., has not been initialized) 2424 * @exception IllegalArgumentException if input and output are the 2425 * same object 2426 * @exception ReadOnlyBufferException if the output buffer is read-only 2427 * @exception IllegalBlockSizeException if this cipher is a block cipher, 2428 * no padding has been requested (only in encryption mode), and the total 2429 * input length of the data processed by this cipher is not a multiple of 2430 * block size; or if this encryption algorithm is unable to 2431 * process the input data provided. 2432 * @exception ShortBufferException if there is insufficient space in the 2433 * output buffer 2434 * @exception BadPaddingException if this cipher is in decryption mode, 2435 * and (un)padding has been requested, but the decrypted data is not 2436 * bounded by the appropriate padding bytes 2437 * @exception AEADBadTagException if this cipher is decrypting in an 2438 * AEAD mode (such as GCM/CCM), and the received authentication tag 2439 * does not match the calculated value 2440 * 2490 } 2491 if (opmode != Cipher.WRAP_MODE) { 2492 throw new IllegalStateException("Cipher not initialized " + 2493 "for wrapping keys"); 2494 } 2495 } 2496 2497 chooseFirstProvider(); 2498 return spi.engineWrap(key); 2499 } 2500 2501 /** 2502 * Unwrap a previously wrapped key. 2503 * 2504 * @param wrappedKey the key to be unwrapped. 2505 * 2506 * @param wrappedKeyAlgorithm the algorithm associated with the wrapped 2507 * key. 2508 * 2509 * @param wrappedKeyType the type of the wrapped key. This must be one of 2510 * {@code SECRET_KEY}, {@code PRIVATE_KEY}, or 2511 * {@code PUBLIC_KEY}. 2512 * 2513 * @return the unwrapped key. 2514 * 2515 * @exception IllegalStateException if this cipher is in a wrong state 2516 * (e.g., has not been initialized). 2517 * 2518 * @exception NoSuchAlgorithmException if no installed providers 2519 * can create keys of type {@code wrappedKeyType} for the 2520 * {@code wrappedKeyAlgorithm}. 2521 * 2522 * @exception InvalidKeyException if {@code wrappedKey} does not 2523 * represent a wrapped key of type {@code wrappedKeyType} for 2524 * the {@code wrappedKeyAlgorithm}. 2525 * 2526 * @throws UnsupportedOperationException if the corresponding method in the 2527 * {@code CipherSpi} is not supported. 2528 */ 2529 public final Key unwrap(byte[] wrappedKey, 2530 String wrappedKeyAlgorithm, 2531 int wrappedKeyType) 2532 throws InvalidKeyException, NoSuchAlgorithmException { 2533 2534 if (!(this instanceof NullCipher)) { 2535 if (!initialized) { 2536 throw new IllegalStateException("Cipher not initialized"); 2537 } 2538 if (opmode != Cipher.UNWRAP_MODE) { 2539 throw new IllegalStateException("Cipher not initialized " + 2540 "for unwrapping keys"); 2541 } 2542 } 2543 if ((wrappedKeyType != SECRET_KEY) && 2544 (wrappedKeyType != PRIVATE_KEY) && 2583 String transformation) throws NullPointerException, 2584 NoSuchAlgorithmException { 2585 if (transformation == null) throw new NullPointerException(); 2586 String[] parts = tokenizeTransformation(transformation); 2587 return JceSecurityManager.INSTANCE.getCryptoPermission(parts[0]); 2588 } 2589 2590 /** 2591 * Returns the maximum key length for the specified transformation 2592 * according to the installed JCE jurisdiction policy files. If 2593 * JCE unlimited strength jurisdiction policy files are installed, 2594 * Integer.MAX_VALUE will be returned. 2595 * For more information on default key size in JCE jurisdiction 2596 * policy files, please see Appendix E in the 2597 * <a href= 2598 * "{@docRoot}/../technotes/guides/security/crypto/CryptoSpec.html#AppC"> 2599 * Java Cryptography Architecture Reference Guide</a>. 2600 * 2601 * @param transformation the cipher transformation. 2602 * @return the maximum key length in bits or Integer.MAX_VALUE. 2603 * @exception NullPointerException if {@code transformation} is null. 2604 * @exception NoSuchAlgorithmException if {@code transformation} 2605 * is not a valid transformation, i.e. in the form of "algorithm" or 2606 * "algorithm/mode/padding". 2607 * @since 1.5 2608 */ 2609 public static final int getMaxAllowedKeyLength(String transformation) 2610 throws NoSuchAlgorithmException { 2611 CryptoPermission cp = getConfiguredPermission(transformation); 2612 return cp.getMaxKeySize(); 2613 } 2614 2615 /** 2616 * Returns an AlgorithmParameterSpec object which contains 2617 * the maximum cipher parameter value according to the 2618 * jurisdiction policy file. If JCE unlimited strength jurisdiction 2619 * policy files are installed or there is no maximum limit on the 2620 * parameters for the specified transformation in the policy file, 2621 * null will be returned. 2622 * 2623 * @param transformation the cipher transformation. 2624 * @return an AlgorithmParameterSpec which holds the maximum 2625 * value or null. 2626 * @exception NullPointerException if {@code transformation} 2627 * is null. 2628 * @exception NoSuchAlgorithmException if {@code transformation} 2629 * is not a valid transformation, i.e. in the form of "algorithm" or 2630 * "algorithm/mode/padding". 2631 * @since 1.5 2632 */ 2633 public static final AlgorithmParameterSpec getMaxAllowedParameterSpec( 2634 String transformation) throws NoSuchAlgorithmException { 2635 CryptoPermission cp = getConfiguredPermission(transformation); 2636 return cp.getAlgorithmParameterSpec(); 2637 } 2638 2639 /** 2640 * Continues a multi-part update of the Additional Authentication 2641 * Data (AAD). 2642 * <p> 2643 * Calls to this method provide AAD to the cipher when operating in 2644 * modes such as AEAD (GCM/CCM). If this cipher is operating in 2645 * either GCM or CCM mode, all AAD must be supplied before beginning 2646 * operations on the ciphertext (via the {@code update} and 2647 * {@code doFinal} methods). 2648 * 2649 * @param src the buffer containing the Additional Authentication Data 2650 * 2651 * @throws IllegalArgumentException if the {@code src} 2652 * byte array is null 2653 * @throws IllegalStateException if this cipher is in a wrong state 2654 * (e.g., has not been initialized), does not accept AAD, or if 2655 * operating in either GCM or CCM mode and one of the {@code update} 2656 * methods has already been called for the active 2657 * encryption/decryption operation 2658 * @throws UnsupportedOperationException if the corresponding method 2659 * in the {@code CipherSpi} has not been overridden by an 2660 * implementation 2661 * 2662 * @since 1.7 2663 */ 2664 public final void updateAAD(byte[] src) { 2665 if (src == null) { 2666 throw new IllegalArgumentException("src buffer is null"); 2667 } 2668 2669 updateAAD(src, 0, src.length); 2670 } 2671 2672 /** 2673 * Continues a multi-part update of the Additional Authentication 2674 * Data (AAD), using a subset of the provided buffer. 2675 * <p> 2676 * Calls to this method provide AAD to the cipher when operating in 2677 * modes such as AEAD (GCM/CCM). If this cipher is operating in 2678 * either GCM or CCM mode, all AAD must be supplied before beginning 2679 * operations on the ciphertext (via the {@code update} 2680 * and {@code doFinal} methods). 2681 * 2682 * @param src the buffer containing the AAD 2683 * @param offset the offset in {@code src} where the AAD input starts 2684 * @param len the number of AAD bytes 2685 * 2686 * @throws IllegalArgumentException if the {@code src} 2687 * byte array is null, or the {@code offset} or {@code length} 2688 * is less than 0, or the sum of the {@code offset} and 2689 * {@code len} is greater than the length of the 2690 * {@code src} byte array 2691 * @throws IllegalStateException if this cipher is in a wrong state 2692 * (e.g., has not been initialized), does not accept AAD, or if 2693 * operating in either GCM or CCM mode and one of the {@code update} 2694 * methods has already been called for the active 2695 * encryption/decryption operation 2696 * @throws UnsupportedOperationException if the corresponding method 2697 * in the {@code CipherSpi} has not been overridden by an 2698 * implementation 2699 * 2700 * @since 1.7 2705 // Input sanity check 2706 if ((src == null) || (offset < 0) || (len < 0) 2707 || ((len + offset) > src.length)) { 2708 throw new IllegalArgumentException("Bad arguments"); 2709 } 2710 2711 chooseFirstProvider(); 2712 if (len == 0) { 2713 return; 2714 } 2715 spi.engineUpdateAAD(src, offset, len); 2716 } 2717 2718 /** 2719 * Continues a multi-part update of the Additional Authentication 2720 * Data (AAD). 2721 * <p> 2722 * Calls to this method provide AAD to the cipher when operating in 2723 * modes such as AEAD (GCM/CCM). If this cipher is operating in 2724 * either GCM or CCM mode, all AAD must be supplied before beginning 2725 * operations on the ciphertext (via the {@code update} 2726 * and {@code doFinal} methods). 2727 * <p> 2728 * All {@code src.remaining()} bytes starting at 2729 * {@code src.position()} are processed. 2730 * Upon return, the input buffer's position will be equal 2731 * to its limit; its limit will not have changed. 2732 * 2733 * @param src the buffer containing the AAD 2734 * 2735 * @throws IllegalArgumentException if the {@code src ByteBuffer} 2736 * is null 2737 * @throws IllegalStateException if this cipher is in a wrong state 2738 * (e.g., has not been initialized), does not accept AAD, or if 2739 * operating in either GCM or CCM mode and one of the {@code update} 2740 * methods has already been called for the active 2741 * encryption/decryption operation 2742 * @throws UnsupportedOperationException if the corresponding method 2743 * in the {@code CipherSpi} has not been overridden by an 2744 * implementation 2745 * 2746 * @since 1.7 |