stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8169080: Improve documentation examples for crypto applications

Browse Source 
Reviewed-by: mullan
This commit is contained in:
Bradford Wetmore 2017-08-01 15:30:13 -07:00
parent 276506ab24
commit 570bbe25a2
7 changed files with 44 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
jdk/src/java.base/share/classes/java/security/MessageDigest.java
View File

@ -57,7 +57,7 @@ import javax.crypto.SecretKey;
* and catching the CloneNotSupportedException:
*
* <pre>{@code
* MessageDigest md = MessageDigest.getInstance("SHA");
* MessageDigest md = MessageDigest.getInstance("SHA-256");
*
* try {
* md.update(toChapter1);
@ -496,7 +496,7 @@ public abstract class MessageDigest extends MessageDigestSpi {
/**
* 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 <a href=
* "{@docRoot}/../specs/security/standard-names.html#messagedigest-algorithms">
* Java Security Standard Algorithm Names Specification</a>

9
jdk/src/java.base/share/classes/java/security/Signature.java
View File

@ -51,11 +51,10 @@ import sun.security.jca.GetInstance.Instance;
* authentication and integrity assurance of digital data.
*
* <p> 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.
*
* <p> A Signature object can be used to generate and verify digital

13
jdk/src/java.base/share/classes/java/security/SignedObject.java
View File

@ -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 @@ import java.io.*;
* verification in an attempt to bypass a security check.
*
* <p> 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.
*
* <p> The name of the Cryptography Package Provider is designated

30
jdk/src/java.base/share/classes/javax/crypto/Cipher.java
View File

@ -59,7 +59,7 @@ import sun.security.jca.*;
* <p>A <i>transformation</i> 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., <i>DES</i>), and may be followed by a feedback mode and
* algorithm (e.g., <i>AES</i>), and may be followed by a feedback mode and
* padding scheme.
*
* <p> A transformation is of the form:
@ -75,17 +75,19 @@ import sun.security.jca.*;
* For example, the following is a valid transformation:
*
* <pre>
* Cipher c = Cipher.getInstance("<i>DES/CBC/PKCS5Padding</i>");
* Cipher c = Cipher.getInstance("<i>AES/CBC/PKCS5Padding</i>");
* </pre>
*
* 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.
* <p>
@ -308,7 +310,7 @@ public class Cipher {
/*
* 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 @@ public class Cipher {
// 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 @@ public class Cipher {
}
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<Transform> 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 @@ public class Cipher {
* {@link Security#getProviders() Security.getProviders()}.
*
* @param transformation the name of the transformation, e.g.,
* <i>DES/CBC/PKCS5Padding</i>.
* <i>AES/CBC/PKCS5Padding</i>.
* See the Cipher section in the <a href=
* "{@docRoot}/../specs/security/standard-names.html#cipher-algorithm-names">
* Java Security Standard Algorithm Names Specification</a>
@ -566,7 +568,7 @@ public class Cipher {
* the {@link Security#getProviders() Security.getProviders()} method.
*
* @param transformation the name of the transformation,
* e.g., <i>DES/CBC/PKCS5Padding</i>.
* e.g., <i>AES/CBC/PKCS5Padding</i>.
* See the Cipher section in the <a href=
* "{@docRoot}/../specs/security/standard-names.html#cipher-algorithm-names">
* Java Security Standard Algorithm Names Specification</a>
@ -626,7 +628,7 @@ public class Cipher {
* does not have to be registered in the provider list.
*
* @param transformation the name of the transformation,
* e.g., <i>DES/CBC/PKCS5Padding</i>.
* e.g., <i>AES/CBC/PKCS5Padding</i>.
* See the Cipher section in the <a href=
* "{@docRoot}/../specs/security/standard-names.html#cipher-algorithm-names">
* Java Security Standard Algorithm Names Specification</a>

26
jdk/src/java.base/share/classes/javax/crypto/CipherSpi.java
View File

@ -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 @@ import java.nio.ByteBuffer;
* <p>A <i>transformation</i> 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., <i>DES</i>), and may be followed by a feedback mode and
* algorithm (e.g., <i>AES</i>), and may be followed by a feedback mode and
* padding scheme.
*
* <p> A transformation is of the form:
@ -75,7 +75,7 @@ import java.nio.ByteBuffer;
* For example, the following is a valid transformation:
*
* <pre>
* Cipher c = Cipher.getInstance("<i>DES/CBC/PKCS5Padding</i>");
* Cipher c = Cipher.getInstance("<i>AES/CBC/PKCS5Padding</i>");
* </pre>
*
* <p>A provider may supply a separate class for each combination
@ -125,32 +125,32 @@ import java.nio.ByteBuffer;
* </ul>
*
* <p>For example, a provider may supply a subclass of <code>CipherSpi</code>
* that implements <i>DES/ECB/PKCS5Padding</i>, one that implements
* <i>DES/CBC/PKCS5Padding</i>, one that implements
* <i>DES/CFB/PKCS5Padding</i>, and yet another one that implements
* <i>DES/OFB/PKCS5Padding</i>. That provider would have the following
* that implements <i>AES/ECB/PKCS5Padding</i>, one that implements
* <i>AES/CBC/PKCS5Padding</i>, one that implements
* <i>AES/CFB/PKCS5Padding</i>, and yet another one that implements
* <i>AES/OFB/PKCS5Padding</i>. That provider would have the following
* <code>Cipher</code> properties in its master class:
*
* <ul>
*
* <li>
* <pre>
* <code>Cipher.</code><i>DES/ECB/PKCS5Padding</i>
* <code>Cipher.</code><i>AES/ECB/PKCS5Padding</i>
* </pre>
*
* <li>
* <pre>
* <code>Cipher.</code><i>DES/CBC/PKCS5Padding</i>
* <code>Cipher.</code><i>AES/CBC/PKCS5Padding</i>
* </pre>
*
* <li>
* <pre>
* <code>Cipher.</code><i>DES/CFB/PKCS5Padding</i>
* <code>Cipher.</code><i>AES/CFB/PKCS5Padding</i>
* </pre>
*
* <li>
* <pre>
* <code>Cipher.</code><i>DES/OFB/PKCS5Padding</i>
* <code>Cipher.</code><i>AES/OFB/PKCS5Padding</i>
* </pre>
*
* </ul>
@ -158,7 +158,7 @@ import java.nio.ByteBuffer;
* <p>Another provider may implement a class for each of the above modes
* (i.e., one class for <i>ECB</i>, one for <i>CBC</i>, one for <i>CFB</i>,
* and one for <i>OFB</i>), one class for <i>PKCS5Padding</i>,
* and a generic <i>DES</i> class that subclasses from <code>CipherSpi</code>.
* and a generic <i>AES</i> class that subclasses from <code>CipherSpi</code>.
* That provider would have the following
* <code>Cipher</code> properties in its master class:
*
@ -166,7 +166,7 @@ import java.nio.ByteBuffer;
*
* <li>
* <pre>
* <code>Cipher.</code><i>DES</i>
* <code>Cipher.</code><i>AES</i>
* </pre>
*
* </ul>

2
jdk/src/java.base/share/classes/javax/crypto/Mac.java
View File

@ -50,7 +50,7 @@ import sun.security.jca.GetInstance.Instance;
*
* <p> 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.
*
* <p> Every implementation of the Java platform is required to support

4
jdk/src/java.base/share/classes/javax/crypto/SealedObject.java
View File

@ -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 @@ import java.security.NoSuchProviderException;
* <p> 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.