# HG changeset patch # User wetmore # Date 1501626613 25200 # Node ID 6f7e93cb432a03605a5c98f772d378bdc771ae9c # Parent 30afc40a7f6a5be3cabb85a4313a665a51f4916e 8169080: Improve documentation examples for crypto applications Reviewed-by: mullan diff -r 30afc40a7f6a -r 6f7e93cb432a jdk/src/java.base/share/classes/java/security/MessageDigest.java --- a/jdk/src/java.base/share/classes/java/security/MessageDigest.java Tue Aug 01 15:23:13 2017 -0700 +++ b/jdk/src/java.base/share/classes/java/security/MessageDigest.java Tue Aug 01 15:30:13 2017 -0700 @@ -57,7 +57,7 @@ * and catching the CloneNotSupportedException: * * 
{@code
- * MessageDigest md = MessageDigest.getInstance("SHA");
+ * MessageDigest md = MessageDigest.getInstance("SHA-256");
  *
  * try {
  *     md.update(toChapter1);
@@ -496,7 +496,7 @@
     /**
      * Returns a string that identifies the algorithm, independent of
      * implementation details. The name should be a standard
-     * Java Security name (such as "SHA", "MD5", and so on).
+     * Java Security name (such as "SHA-256").
      * See the MessageDigest section in the 
      * Java Security Standard Algorithm Names Specification
diff -r 30afc40a7f6a -r 6f7e93cb432a jdk/src/java.base/share/classes/java/security/Signature.java
--- a/jdk/src/java.base/share/classes/java/security/Signature.java	Tue Aug 01 15:23:13 2017 -0700
+++ b/jdk/src/java.base/share/classes/java/security/Signature.java	Tue Aug 01 15:30:13 2017 -0700
@@ -51,11 +51,10 @@
  * authentication and integrity assurance of digital data.
  *
  * 
 The signature algorithm can be, among others, the NIST standard
- * DSA, using DSA and SHA-1. The DSA algorithm using the
- * SHA-1 message digest algorithm can be specified as {@code SHA1withDSA}.
- * In the case of RSA, there are multiple choices for the message digest
- * algorithm, so the signing algorithm could be specified as, for example,
- * {@code MD2withRSA}, {@code MD5withRSA}, or {@code SHA1withRSA}.
+ * DSA, using DSA and SHA-256. The DSA algorithm using the
+ * SHA-256 message digest algorithm can be specified as {@code SHA256withDSA}.
+ * In the case of RSA the signing algorithm could be specified as, for example,
+ * {@code SHA256withRSA}.
  * The algorithm name must be specified, as there is no default.
  *
  * 
 A Signature object can be used to generate and verify digital
diff -r 30afc40a7f6a -r 6f7e93cb432a jdk/src/java.base/share/classes/java/security/SignedObject.java
--- a/jdk/src/java.base/share/classes/java/security/SignedObject.java	Tue Aug 01 15:23:13 2017 -0700
+++ b/jdk/src/java.base/share/classes/java/security/SignedObject.java	Tue Aug 01 15:30:13 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -81,13 +81,12 @@
  * verification in an attempt to bypass a security check.
  *
  * 
 The signature algorithm can be, among others, the NIST standard
- * DSA, using DSA and SHA-1.  The algorithm is specified using the
+ * DSA, using DSA and SHA-256.  The algorithm is specified using the
  * same convention as that for signatures. The DSA algorithm using the
- * SHA-1 message digest algorithm can be specified, for example, as
- * "SHA/DSA" or "SHA-1/DSA" (they are equivalent).  In the case of
- * RSA, there are multiple choices for the message digest algorithm,
- * so the signing algorithm could be specified as, for example,
- * "MD2/RSA", "MD5/RSA" or "SHA-1/RSA".  The algorithm name must be
+ * SHA-256 message digest algorithm can be specified, for example, as
+ * "SHA256withDSA".  In the case of
+ * RSA the signing algorithm could be specified as, for example,
+ * "SHA256withRSA".  The algorithm name must be
  * specified, as there is no default.
  *
  * 
 The name of the Cryptography Package Provider is designated
diff -r 30afc40a7f6a -r 6f7e93cb432a jdk/src/java.base/share/classes/javax/crypto/Cipher.java
--- a/jdk/src/java.base/share/classes/javax/crypto/Cipher.java	Tue Aug 01 15:23:13 2017 -0700
+++ b/jdk/src/java.base/share/classes/javax/crypto/Cipher.java	Tue Aug 01 15:30:13 2017 -0700
@@ -59,7 +59,7 @@
  * 
A transformation is a string that describes the operation (or
  * set of operations) to be performed on the given input, to produce some
  * output. A transformation always includes the name of a cryptographic
- * algorithm (e.g., DES), and may be followed by a feedback mode and
+ * algorithm (e.g., AES), and may be followed by a feedback mode and
  * padding scheme.
  *
  * 
 A transformation is of the form:
@@ -75,17 +75,19 @@
  * For example, the following is a valid transformation:
  *
  * 
- *     Cipher c = Cipher.getInstance("DES/CBC/PKCS5Padding");
+ *     Cipher c = Cipher.getInstance("AES/CBC/PKCS5Padding");
  * 

  *
  * Using modes such as {@code CFB} and {@code OFB}, block
  * ciphers can encrypt data in units smaller than the cipher's actual
  * block size.  When requesting such a mode, you may optionally specify
  * the number of bits to be processed at a time by appending this number
- * to the mode name as shown in the "{@code DES/CFB8/NoPadding}" and
- * "{@code DES/OFB32/PKCS5Padding}" transformations. If no such
- * number is specified, a provider-specific default is used. (For
- * example, the SunJCE provider uses a default of 64 bits for DES.)
+ * to the mode name as shown in the "{@code AES/CFB8/NoPadding}" and
+ * "{@code AES/OFB32/PKCS5Padding}" transformations. If no such
+ * number is specified, a provider-specific default is used.
+ * (See the
+ * {@extLink security_guide_jdk_providers JDK Providers Documentation}
+ * for the JDK Providers default values.)
  * Thus, block ciphers can be turned into byte-oriented stream ciphers by
  * using an 8 bit mode such as CFB8 or OFB8.
  * 

@@ -308,7 +310,7 @@
         /*
          * array containing the components of a Cipher transformation:
          *
-         * index 0: algorithm component (e.g., DES)
+         * index 0: algorithm component (e.g., AES)
          * index 1: feedback component (e.g., CFB)
          * index 2: padding component (e.g., PKCS5Padding)
          */
@@ -354,8 +356,8 @@
         // transform string to lookup in the provider
         final String transform;
         // the mode/padding suffix in upper case. for example, if the algorithm
-        // to lookup is "DES/CBC/PKCS5Padding" suffix is "/CBC/PKCS5PADDING"
-        // if loopup is "DES", suffix is the empty string
+        // to lookup is "AES/CBC/PKCS5Padding" suffix is "/CBC/PKCS5PADDING"
+        // if lookup is "AES", suffix is the empty string
         // needed because aliases prevent straight transform.equals()
         final String suffix;
         // value to pass to setMode() or null if no such call required
@@ -440,11 +442,11 @@
         }
 
         if ((mode == null) && (pad == null)) {
-            // DES
+            // AES
             Transform tr = new Transform(alg, "", null, null);
             return Collections.singletonList(tr);
         } else { // if ((mode != null) && (pad != null)) {
-            // DES/CBC/PKCS5Padding
+            // AES/CBC/PKCS5Padding
             List list = new ArrayList<>(4);
             list.add(new Transform(alg, "/" + mode + "/" + pad, null, null));
             list.add(new Transform(alg, "/" + mode, null, pad));
@@ -488,7 +490,7 @@
      * {@link Security#getProviders() Security.getProviders()}.
      *
      * @param transformation the name of the transformation, e.g.,
-     * DES/CBC/PKCS5Padding.
+     * AES/CBC/PKCS5Padding.
      * See the Cipher section in the 
      * Java Security Standard Algorithm Names Specification
@@ -566,7 +568,7 @@
      * the {@link Security#getProviders() Security.getProviders()} method.
      *
      * @param transformation the name of the transformation,
-     * e.g., DES/CBC/PKCS5Padding.
+     * e.g., AES/CBC/PKCS5Padding.
      * See the Cipher section in the 
      * Java Security Standard Algorithm Names Specification
@@ -626,7 +628,7 @@
      * does not have to be registered in the provider list.
      *
      * @param transformation the name of the transformation,
-     * e.g., DES/CBC/PKCS5Padding.
+     * e.g., AES/CBC/PKCS5Padding.
      * See the Cipher section in the 
      * Java Security Standard Algorithm Names Specification
diff -r 30afc40a7f6a -r 6f7e93cb432a jdk/src/java.base/share/classes/javax/crypto/CipherSpi.java
--- a/jdk/src/java.base/share/classes/javax/crypto/CipherSpi.java	Tue Aug 01 15:23:13 2017 -0700
+++ b/jdk/src/java.base/share/classes/javax/crypto/CipherSpi.java	Tue Aug 01 15:30:13 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -59,7 +59,7 @@
  * 
A transformation is a string that describes the operation (or
  * set of operations) to be performed on the given input, to produce some
  * output. A transformation always includes the name of a cryptographic
- * algorithm (e.g., DES), and may be followed by a feedback mode and
+ * algorithm (e.g., AES), and may be followed by a feedback mode and
  * padding scheme.
  *
  * 
 A transformation is of the form:
@@ -75,7 +75,7 @@
  * For example, the following is a valid transformation:
  *
  * 
- *     Cipher c = Cipher.getInstance("DES/CBC/PKCS5Padding");
+ *     Cipher c = Cipher.getInstance("AES/CBC/PKCS5Padding");
  * 

  *
  * 
A provider may supply a separate class for each combination
@@ -125,32 +125,32 @@
  * 
  *
  * 
For example, a provider may supply a subclass of CipherSpi
- * that implements DES/ECB/PKCS5Padding, one that implements
- * DES/CBC/PKCS5Padding, one that implements
- * DES/CFB/PKCS5Padding, and yet another one that implements
- * DES/OFB/PKCS5Padding. That provider would have the following
+ * that implements AES/ECB/PKCS5Padding, one that implements
+ * AES/CBC/PKCS5Padding, one that implements
+ * AES/CFB/PKCS5Padding, and yet another one that implements
+ * AES/OFB/PKCS5Padding. That provider would have the following
  * Cipher properties in its master class:
  *
  * 

@@ -158,7 +158,7 @@
  * 
Another provider may implement a class for each of the above modes
  * (i.e., one class for ECB, one for CBC, one for CFB,
  * and one for OFB), one class for PKCS5Padding,
- * and a generic DES class that subclasses from CipherSpi.
+ * and a generic AES class that subclasses from CipherSpi.
  * That provider would have the following
  * Cipher properties in its master class:
  *
@@ -166,7 +166,7 @@
  *
  * 
  • 
  * 
    - *     Cipher.DES
+ *     Cipher.AES
  * 
    
  *
  * 
diff -r 30afc40a7f6a -r 6f7e93cb432a jdk/src/java.base/share/classes/javax/crypto/Mac.java
--- a/jdk/src/java.base/share/classes/javax/crypto/Mac.java	Tue Aug 01 15:23:13 2017 -0700
+++ b/jdk/src/java.base/share/classes/javax/crypto/Mac.java	Tue Aug 01 15:30:13 2017 -0700
@@ -50,7 +50,7 @@
  *
  * 
     A MAC mechanism that is based on cryptographic hash functions is
  * referred to as HMAC. HMAC can be used with any cryptographic hash function,
- * e.g., MD5 or SHA-1, in combination with a secret shared key. HMAC is
+ * e.g., SHA256 or SHA384, in combination with a secret shared key. HMAC is
  * specified in RFC 2104.
  *
  * 
     Every implementation of the Java platform is required to support
diff -r 30afc40a7f6a -r 6f7e93cb432a jdk/src/java.base/share/classes/javax/crypto/SealedObject.java
--- a/jdk/src/java.base/share/classes/javax/crypto/SealedObject.java	Tue Aug 01 15:23:13 2017 -0700
+++ b/jdk/src/java.base/share/classes/javax/crypto/SealedObject.java	Tue Aug 01 15:30:13 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -40,7 +40,7 @@
  * 
     Given any Serializable object, one can create a SealedObject
  * that encapsulates the original object, in serialized
  * format (i.e., a "deep copy"), and seals (encrypts) its serialized contents,
- * using a cryptographic algorithm such as DES, to protect its
+ * using a cryptographic algorithm such as AES, to protect its
  * confidentiality.  The encrypted content can later be decrypted (with
  * the corresponding algorithm using the correct decryption key) and
  * de-serialized, yielding the original object.