mirror of
https://github.com/openjdk/jdk.git
synced 2025-08-27 14:54:52 +02:00
8284851: Update javax.crypto files to use proper javadoc for mentioned classes
Reviewed-by: weijun, valeriep
This commit is contained in:
Mark Powers
Valerie Peng
parent
8cdead0c94
commit
f804f2ce8e
92 changed files with 2142 additions and 2010 deletions
|
|
@ -49,7 +49,7 @@ import sun.security.jca.GetInstance.Instance;
|
|||
import sun.security.util.KnownOIDs;
|
||||
|
||||
/**
|
||||
* The Signature class is used to provide applications the functionality
|
||||
* The {@code Signature} class is used to provide applications the functionality
|
||||
* of a digital signature algorithm. Digital signatures are used for
|
||||
* authentication and integrity assurance of digital data.
|
||||
*
|
||||
|
|
@ -60,10 +60,10 @@ import sun.security.util.KnownOIDs;
|
|||
* {@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
|
||||
* <p> A {@code Signature} object can be used to generate and verify digital
|
||||
* signatures.
|
||||
*
|
||||
* <p> There are three phases to the use of a Signature object for
|
||||
* <p> There are three phases to the use of a {@code Signature} object for
|
||||
* either signing data or verifying a signature:<ol>
|
||||
*
|
||||
* <li>Initialization, with either
|
||||
|
|
@ -169,29 +169,29 @@ public abstract class Signature extends SignatureSpi {
|
|||
|
||||
/**
|
||||
* Possible {@link #state} value, signifying that
|
||||
* this signature object has not yet been initialized.
|
||||
* this {@code Signature} object has not yet been initialized.
|
||||
*/
|
||||
protected static final int UNINITIALIZED = 0;
|
||||
|
||||
/**
|
||||
* Possible {@link #state} value, signifying that
|
||||
* this signature object has been initialized for signing.
|
||||
* this {@code Signature} object has been initialized for signing.
|
||||
*/
|
||||
protected static final int SIGN = 2;
|
||||
|
||||
/**
|
||||
* Possible {@link #state} value, signifying that
|
||||
* this signature object has been initialized for verification.
|
||||
* this {@code Signature} object has been initialized for verification.
|
||||
*/
|
||||
protected static final int VERIFY = 3;
|
||||
|
||||
/**
|
||||
* Current state of this signature object.
|
||||
* Current state of this {@code Signature} object.
|
||||
*/
|
||||
protected int state = UNINITIALIZED;
|
||||
|
||||
/**
|
||||
* Creates a Signature object for the specified algorithm.
|
||||
* Creates a {@code Signature} object for the specified algorithm.
|
||||
*
|
||||
* @param algorithm the standard string name of the algorithm.
|
||||
* See the Signature section in the <a href=
|
||||
|
|
@ -218,14 +218,14 @@ public abstract class Signature extends SignatureSpi {
|
|||
new ServiceId("Cipher", "RSA"));
|
||||
|
||||
/**
|
||||
* Returns a Signature object that implements the specified signature
|
||||
* algorithm.
|
||||
* Returns a {@code Signature} object that implements the specified
|
||||
* signature algorithm.
|
||||
*
|
||||
* <p> This method traverses the list of registered security Providers,
|
||||
* starting with the most preferred Provider.
|
||||
* A new Signature object encapsulating the
|
||||
* SignatureSpi implementation from the first
|
||||
* Provider that supports the specified algorithm is returned.
|
||||
* A new {@code Signature} object encapsulating the
|
||||
* {@code SignatureSpi} implementation from the first
|
||||
* provider that supports the specified algorithm is returned.
|
||||
*
|
||||
* <p> Note that the list of registered providers may be retrieved via
|
||||
* the {@link Security#getProviders() Security.getProviders()} method.
|
||||
|
|
@ -349,11 +349,11 @@ public abstract class Signature extends SignatureSpi {
|
|||
}
|
||||
|
||||
/**
|
||||
* Returns a Signature object that implements the specified signature
|
||||
* algorithm.
|
||||
* Returns a {@code Signature} object that implements the specified
|
||||
* signature algorithm.
|
||||
*
|
||||
* <p> A new Signature object encapsulating the
|
||||
* SignatureSpi implementation from the specified provider
|
||||
* <p> A new {@code Signature} object encapsulating the
|
||||
* {@code SignatureSpi} implementation from the specified provider
|
||||
* is returned. The specified provider must be registered
|
||||
* in the security provider list.
|
||||
*
|
||||
|
|
@ -405,13 +405,13 @@ public abstract class Signature extends SignatureSpi {
|
|||
}
|
||||
|
||||
/**
|
||||
* Returns a Signature object that implements the specified
|
||||
* Returns a {@code Signature} object that implements the specified
|
||||
* signature algorithm.
|
||||
*
|
||||
* <p> A new Signature object encapsulating the
|
||||
* SignatureSpi implementation from the specified Provider
|
||||
* object is returned. Note that the specified Provider object
|
||||
* does not have to be registered in the provider list.
|
||||
* <p> A new {@code Signature} object encapsulating the
|
||||
* {@code SignatureSpi} implementation from the specified provider
|
||||
* is returned. Note that the specified provider does not
|
||||
* have to be registered in the provider list.
|
||||
*
|
||||
* @param algorithm the name of the algorithm requested.
|
||||
* See the Signature section in the <a href=
|
||||
|
|
@ -473,9 +473,9 @@ public abstract class Signature extends SignatureSpi {
|
|||
}
|
||||
|
||||
/**
|
||||
* Returns the provider of this signature object.
|
||||
* Returns the provider of this {@code Signature} object.
|
||||
*
|
||||
* @return the provider of this signature object
|
||||
* @return the provider of this {@code Signature} object
|
||||
*/
|
||||
public final Provider getProvider() {
|
||||
chooseFirstProvider();
|
||||
|
|
@ -518,7 +518,8 @@ public abstract class Signature extends SignatureSpi {
|
|||
*
|
||||
* @param publicKey the public key of the identity whose signature is
|
||||
* going to be verified
|
||||
* @param params the parameters used for verifying this signature object
|
||||
* @param params the parameters used for verifying this {@code Signature}
|
||||
* object
|
||||
*
|
||||
* @throws InvalidKeyException if the key is invalid
|
||||
* @throws InvalidAlgorithmParameterException if the params is invalid
|
||||
|
|
@ -598,7 +599,8 @@ public abstract class Signature extends SignatureSpi {
|
|||
*
|
||||
* @param certificate the certificate of the identity whose signature is
|
||||
* going to be verified
|
||||
* @param params the parameters used for verifying this signature object
|
||||
* @param params the parameters used for verifying this {@code Signature}
|
||||
* object
|
||||
*
|
||||
* @throws InvalidKeyException if the public key in the certificate
|
||||
* is not encoded properly or does not include required parameter
|
||||
|
|
@ -648,7 +650,7 @@ public abstract class Signature extends SignatureSpi {
|
|||
* @param privateKey the private key of the identity whose signature
|
||||
* is going to be generated
|
||||
*
|
||||
* @param random the source of randomness for this signature object
|
||||
* @param random the source of randomness for this {@code Signature} object
|
||||
*
|
||||
* @throws InvalidKeyException if the key is invalid.
|
||||
*/
|
||||
|
|
@ -671,7 +673,7 @@ public abstract class Signature extends SignatureSpi {
|
|||
* @param privateKey the private key of the identity whose signature
|
||||
* is going to be generated
|
||||
* @param params the parameters used for generating signature
|
||||
* @param random the source of randomness for this signature object
|
||||
* @param random the source of randomness for this {@code Signature} object
|
||||
*
|
||||
* @throws InvalidKeyException if the key is invalid
|
||||
* @throws InvalidAlgorithmParameterException if the params is invalid
|
||||
|
|
@ -693,8 +695,8 @@ public abstract class Signature extends SignatureSpi {
|
|||
* The format of the signature depends on the underlying
|
||||
* signature scheme.
|
||||
*
|
||||
* <p>A call to this method resets this signature object to the state
|
||||
* it was in when previously initialized for signing via a
|
||||
* <p>A call to this method resets this {@code Signature} object to the
|
||||
* state it was in when previously initialized for signing via a
|
||||
* call to {@code initSign(PrivateKey)}. That is, the object is
|
||||
* reset and available to generate another signature from the same
|
||||
* signer, if desired, via new calls to {@code update} and
|
||||
|
|
@ -702,7 +704,7 @@ public abstract class Signature extends SignatureSpi {
|
|||
*
|
||||
* @return the signature bytes of the signing operation's result.
|
||||
*
|
||||
* @throws SignatureException if this signature object is not
|
||||
* @throws SignatureException if this {@code Signature} object is not
|
||||
* initialized properly or if this signature algorithm is unable to
|
||||
* process the input data provided.
|
||||
*/
|
||||
|
|
@ -721,8 +723,8 @@ public abstract class Signature extends SignatureSpi {
|
|||
* The format of the signature depends on the underlying
|
||||
* signature scheme.
|
||||
*
|
||||
* <p>This signature object is reset to its initial state (the state it
|
||||
* was in after a call to one of the {@code initSign} methods) and
|
||||
* <p>This {@code Signature} object is reset to its initial state (the
|
||||
* state it was in after a call to one of the {@code initSign} methods) and
|
||||
* can be reused to generate further signatures with the same private key.
|
||||
*
|
||||
* @param outbuf buffer for the signature result.
|
||||
|
|
@ -735,7 +737,7 @@ public abstract class Signature extends SignatureSpi {
|
|||
*
|
||||
* @return the number of bytes placed into {@code outbuf}.
|
||||
*
|
||||
* @throws SignatureException if this signature object is not
|
||||
* @throws SignatureException if this {@code Signature} object is not
|
||||
* initialized properly, if this signature algorithm is unable to
|
||||
* process the input data provided, or if {@code len} is less
|
||||
* than the actual signature length.
|
||||
|
|
@ -768,17 +770,17 @@ public abstract class Signature extends SignatureSpi {
|
|||
/**
|
||||
* Verifies the passed-in signature.
|
||||
*
|
||||
* <p>A call to this method resets this signature object to the state
|
||||
* it was in when previously initialized for verification via a
|
||||
* <p>A call to this method resets this {@code Signature} object to the
|
||||
* state it was in when previously initialized for verification via a
|
||||
* call to {@code initVerify(PublicKey)}. That is, the object is
|
||||
* reset and available to verify another signature from the identity
|
||||
* whose public key was specified in the call to {@code initVerify}.
|
||||
*
|
||||
* @param signature the signature bytes to be verified.
|
||||
*
|
||||
* @return true if the signature was verified, false if not.
|
||||
* @return {@code true} if the signature was verified, {@code false} if not.
|
||||
*
|
||||
* @throws SignatureException if this signature object is not
|
||||
* @throws SignatureException if this {@code Signature} object is not
|
||||
* initialized properly, the passed-in signature is improperly
|
||||
* encoded or of the wrong type, if this signature algorithm is unable to
|
||||
* process the input data provided, etc.
|
||||
|
|
@ -795,8 +797,8 @@ public abstract class Signature extends SignatureSpi {
|
|||
* Verifies the passed-in signature in the specified array
|
||||
* of bytes, starting at the specified offset.
|
||||
*
|
||||
* <p>A call to this method resets this signature object to the state
|
||||
* it was in when previously initialized for verification via a
|
||||
* <p>A call to this method resets this {@code Signature} object to the
|
||||
* state it was in when previously initialized for verification via a
|
||||
* call to {@code initVerify(PublicKey)}. That is, the object is
|
||||
* reset and available to verify another signature from the identity
|
||||
* whose public key was specified in the call to {@code initVerify}.
|
||||
|
|
@ -806,9 +808,9 @@ public abstract class Signature extends SignatureSpi {
|
|||
* @param offset the offset to start from in the array of bytes.
|
||||
* @param length the number of bytes to use, starting at offset.
|
||||
*
|
||||
* @return true if the signature was verified, false if not.
|
||||
* @return {@code true} if the signature was verified, {@code false} if not.
|
||||
*
|
||||
* @throws SignatureException if this signature object is not
|
||||
* @throws SignatureException if this {@code Signature} object is not
|
||||
* initialized properly, the passed-in signature is improperly
|
||||
* encoded or of the wrong type, if this signature algorithm is unable to
|
||||
* process the input data provided, etc.
|
||||
|
|
@ -845,7 +847,7 @@ public abstract class Signature extends SignatureSpi {
|
|||
*
|
||||
* @param b the byte to use for the update.
|
||||
*
|
||||
* @throws SignatureException if this signature object is not
|
||||
* @throws SignatureException if this {@code Signature} object is not
|
||||
* initialized properly.
|
||||
*/
|
||||
public final void update(byte b) throws SignatureException {
|
||||
|
|
@ -863,7 +865,7 @@ public abstract class Signature extends SignatureSpi {
|
|||
*
|
||||
* @param data the byte array to use for the update.
|
||||
*
|
||||
* @throws SignatureException if this signature object is not
|
||||
* @throws SignatureException if this {@code Signature} object is not
|
||||
* initialized properly.
|
||||
*/
|
||||
public final void update(byte[] data) throws SignatureException {
|
||||
|
|
@ -878,7 +880,7 @@ public abstract class Signature extends SignatureSpi {
|
|||
* @param off the offset to start from in the array of bytes.
|
||||
* @param len the number of bytes to use, starting at offset.
|
||||
*
|
||||
* @throws SignatureException if this signature object is not
|
||||
* @throws SignatureException if this {@code Signature} object is not
|
||||
* initialized properly.
|
||||
* @throws IllegalArgumentException if {@code data} is {@code null},
|
||||
* or {@code off} or {@code len} is less than 0, or the sum of
|
||||
|
|
@ -914,7 +916,7 @@ public abstract class Signature extends SignatureSpi {
|
|||
*
|
||||
* @param data the ByteBuffer
|
||||
*
|
||||
* @throws SignatureException if this signature object is not
|
||||
* @throws SignatureException if this {@code Signature} object is not
|
||||
* initialized properly.
|
||||
* @since 1.5
|
||||
*/
|
||||
|
|
@ -930,20 +932,20 @@ public abstract class Signature extends SignatureSpi {
|
|||
}
|
||||
|
||||
/**
|
||||
* Returns the name of the algorithm for this signature object.
|
||||
* Returns the name of the algorithm for this {@code Signature} object.
|
||||
*
|
||||
* @return the name of the algorithm for this signature object.
|
||||
* @return the name of the algorithm for this {@code Signature} object.
|
||||
*/
|
||||
public final String getAlgorithm() {
|
||||
return this.algorithm;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a string representation of this signature object,
|
||||
* Returns a string representation of this {@code Signature} object,
|
||||
* providing information that includes the state of the object
|
||||
* and the name of the algorithm used.
|
||||
*
|
||||
* @return a string representation of this signature object.
|
||||
* @return a string representation of this {@code Signature} object.
|
||||
*/
|
||||
public String toString() {
|
||||
String initState = switch (state) {
|
||||
|
|
@ -970,7 +972,7 @@ public abstract class Signature extends SignatureSpi {
|
|||
* @param value the parameter value
|
||||
*
|
||||
* @throws InvalidParameterException if {@code param} is an
|
||||
* invalid parameter for this signature object,
|
||||
* invalid parameter for this {@code Signature} object,
|
||||
* the parameter is already set
|
||||
* and cannot be set again, a security exception occurs, and so on.
|
||||
*
|
||||
|
|
@ -987,12 +989,13 @@ public abstract class Signature extends SignatureSpi {
|
|||
}
|
||||
|
||||
/**
|
||||
* Initializes this signature object with the specified parameter values.
|
||||
* Initializes this {@code Signature} object with the specified parameter
|
||||
* values.
|
||||
*
|
||||
* @param params the parameter values
|
||||
*
|
||||
* @throws InvalidAlgorithmParameterException if the given parameter values
|
||||
* are inappropriate for this signature object
|
||||
* are inappropriate for this {@code Signature} object
|
||||
*
|
||||
* @see #getParameters
|
||||
*/
|
||||
|
|
@ -1002,20 +1005,21 @@ public abstract class Signature extends SignatureSpi {
|
|||
}
|
||||
|
||||
/**
|
||||
* Returns the parameters used with this signature object.
|
||||
* Returns the parameters used with this {@code Signature} object.
|
||||
*
|
||||
* <p>The returned parameters may be the same that were used to initialize
|
||||
* this signature object, or may contain additional default or random
|
||||
* parameter values used by the underlying signature scheme. If the required
|
||||
* parameters were not supplied and can be generated by the signature
|
||||
* object, the generated parameters are returned; otherwise {@code null} is
|
||||
* returned.
|
||||
* this {@code Signature} object, or may contain additional default or
|
||||
* random parameter values used by the underlying signature scheme.
|
||||
* If the required parameters were not supplied and can be generated by
|
||||
* the {@code Signature} object, the generated parameters are returned;
|
||||
* otherwise {@code null} is returned.
|
||||
*
|
||||
* <p>However, if the signature scheme does not support returning
|
||||
* the parameters as {@code AlgorithmParameters}, {@code null} is always
|
||||
* returned.
|
||||
*
|
||||
* @return the parameters used with this signature object, or {@code null}
|
||||
* @return the parameters used with this {@code Signature} object,
|
||||
* or {@code null}
|
||||
* @throws UnsupportedOperationException if the provider does not support
|
||||
* this method
|
||||
*
|
||||
|
|
@ -1072,15 +1076,16 @@ public abstract class Signature extends SignatureSpi {
|
|||
}
|
||||
|
||||
/*
|
||||
* The following class allows providers to extend from SignatureSpi
|
||||
* rather than from Signature. It represents a Signature with an
|
||||
* encapsulated, provider-supplied SPI object (of type SignatureSpi).
|
||||
* If the provider implementation is an instance of SignatureSpi, the
|
||||
* getInstance() methods above return an instance of this class, with
|
||||
* The following class allows providers to extend from {@code SignatureSpi}
|
||||
* rather than from {@code Signature}. It represents a {@code Signature}
|
||||
* with an encapsulated, provider-supplied SPI object
|
||||
* (of type {@code SignatureSpi}).
|
||||
* If the provider implementation is an instance of {@code SignatureSpi},
|
||||
* the getInstance() methods above return an instance of this class, with
|
||||
* the SPI object encapsulated.
|
||||
*
|
||||
* Note: All SPI methods from the original Signature class have been
|
||||
* moved up the hierarchy into a new class (SignatureSpi), which has
|
||||
* Note: All SPI methods from the original {@code Signature} class have been
|
||||
* moved up the hierarchy into a new class (SignatureSpi}, which has
|
||||
* been interposed in the hierarchy between the API (Signature)
|
||||
* and its original parent (Object).
|
||||
*/
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue