All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class java.security.Signature

java.lang.Object
   |
   +----java.security.Signature

public class Signature

extends Object

Like other algorithm-based classes in JavaSecurity, the Signature class has two major components:

Digital Signature API (Application Program Interface)

This is the interface of methods called by applications needing digital signature services. The API consists of all public methods.

Digital Signature SPI (Service Provider Interface)

This is the interface implemented by providers that supply specific algorithms. It consists of all methods whose names are prefixed by engine. Each such method is called by a correspondingly-named public API method. For example, the engineGetAlgorithm method is called by the getAlgorithm method. The SPI methods are abstract; providers must supply a concrete implementation.

Like other algorithm classes in JavaSecurity, Signature provides implementation-independent algorithms, whereby a caller (an application developer) requests a particular signature algorithm and is handed back a properly initialized Signature object. It is also possible, if desired, to request a particular algorithm from a particular provider. See the getSignature methods.

Thus, there are two ways to request a Signature algorithm object: by specifying either just an algorithm name, or both an algorithm name and a package provider.

• If just an algorithm name is specified, the system will determine if there is an implementation of the algorithm requested available in the environment, and if there is more than one, if there is a preferred one.
• If both an algorithm name and a package provider are specified, the system will determine if there is an implementation of the algorithm in the package requested, and throw an exception if there is not.

A Signature object can be used for three major purposes:

• Generating key pairs appropriate for the algorithm. A key pair is a public key and an associated private key.
• Signing bytes.
• Verifying signatures.

There are two phases to the use of a Signature object to generate a key pair:

1. Initialization, by calling one of the initGenerateKeyPair methods.

2. Generation of the key pair, by calling the generateKeyPair method.

There are three phases to the use of a Signature object for either signing bytes or verifying a signature:

1. Initialization
   • with a public key, which initializes the signature for verification. See initVerify.
   • with a private key, which initializes the signature for signing. See initSign.

2. Updating

   Depending on the type of initialization, this will update the bytes to be signed or verified. See update.

3. Signing or Verifying

   a signature on all updated bytes. See sign and verify.

KEYGEN

Possible state value, signifying that this signature object has been initialized for key generation.

SIGN

Possible state value, signifying that this signature object has been initialized for signing.

state

Current state of this signature object.

UNINITIALIZED

Possible state value, signifying that this signature object has not yet been initialized.

VERIFY

Possible state value, signifying that this signature object has been initialized for verification.

Signature(String)

Creates a Signature object for the specified algorithm.

clone()

Returns a clone if the implementation is cloneable.

engineGenerateKeyPair(byte[])

SPI: Generates a pair of keys suitable for this algorithm.

engineGetParameter(String)

Gets the value of the specified algorithm parameter.

engineInitGenerateKeyPair(int)

SPI: Initializes this signature object for key generation for keys of a given size.

engineInitGenerateKeyPair(int, byte[])

SPI: Initializes this signature object for key generation for keys of a given size generated using the specified random seed.

engineInitGenerateKeyPair(KeyParams)

SPI: Initializes this signature object for key generation.

engineInitSign(byte[], String)

SPI:Initializes this signature object with the specified private key for signing operations.

engineInitVerify(byte[], String)

SPI: Initializes this signature object with the specified public key for verification operations.

engineSetParameter(String, Object)

Sets the specified algorithm parameter to the specified value.

engineSign()

SPI: Returns the signature bytes of all the data updated so far.

engineToString()

SPI: Returns an informative human-readable string which succintly describes this object, its implementation details and the implementation-specific bits of information about the object or its state.

engineUpdate(byte)

SPI: Updates the data to be signed or verified using the specified byte.

engineUpdate(byte[], int, int)

SPI: Updates the data to be signed or verified, using the specified array of bytes, starting at the specified offset.

engineVerify(byte[])

SPI: Verifies the passed-in signature.

generateKeyPair(byte[])

Generates pair of keys suitable for this algorithm.

getAlgorithm()

Returns the name of the algorithm for this signature object.

getParameter(String)

Gets the value of the specified algorithm parameter.

getSignature(String)

Generates a Signature object that implements the algorithm requested, as available in the environment.

getSignature(String, String)

Generates a Signature object implementing the specified algorithm, as supplied from the specified Security Package Provider, if such an algorithm is available from the provider.

initGenerateKeyPair(int)

Initializes this object for key generation for keys of a given size.

initGenerateKeyPair(int, byte[])

Initializes this object for key generation for keys of a given size generated using the specified random seed.

initGenerateKeyPair(KeyParams)

Initializes this object for key generation.

initSign(PrivateKey)

Initialize this object for signing.

initVerify(PublicKey)

Initializes this object for verification.

setParameter(String, Object)

Sets the specified algorithm parameter to the specified value.

sign()

Returns the signature bytes of all the data updated.

toString()

Returns a string representation of this signature object, providing information that includes the state of the object and the name of the algorithm used.

update(byte)

Updates the data to be signed or verified by a byte.

update(byte[])

Updates the data to be signed or verified, using the specified array of bytes.

update(byte[], int, int)

Updates the data to be signed or verified, using the specified array of bytes, starting at the specified offset.

verify(byte[])

Verifies the passed-in signature.

  protected final static int UNINITIALIZED

Possible state value, signifying that this signature object has not yet been initialized.

  protected final static int KEYGEN

Possible state value, signifying that this signature object has been initialized for key generation.

  protected final static int SIGN

Possible state value, signifying that this signature object has been initialized for signing.

  protected final static int VERIFY

Possible state value, signifying that this signature object has been initialized for verification.

  protected int state

Current state of this signature object.

  protected Signature(String algorithm)

Creates a Signature object for the specified algorithm.

Parameters:

algorithm - the string name of the algorithm. See Algorithm Names in JavaSecurity.

  public static Signature getSignature(String algorithm) throws NoSuchAlgorithmException

Generates a Signature object that implements the algorithm requested, as available in the environment.

Parameters:

algorithm - the string name of the algorithm. See Algorithm Names in JavaSecurity.

Returns:

the new Signature object.

Throws: NoSuchAlgorithmException

if the algorithm is not available in the environment.

  public static Signature getSignature(String algorithm,
                                       String provider) throws NoSuchAlgorithmException, NoSuchProviderException

Generates a Signature object implementing the specified algorithm, as supplied from the specified Security Package Provider, if such an algorithm is available from the provider.

Parameters:

algorithm - the string name of the algorithm. See Algorithm Names in JavaSecurity for more information.

provider - the string name of the provider. See the "Security Package Providers" section in the JavaSecurity Overview for more information about providers.

Returns:

the new Signature object.

Throws: NoSuchAlgorithmException

if the algorithm is not available from the provider.

Throws: NoSuchProviderException

if the provider is not available in the environment.

  public final KeyPair generateKeyPair(byte seed[]) throws KeyException

Generates pair of keys suitable for this algorithm. This object must have been previously initialized for key generation using an initGenerateKeyPair call.

Parameters:

seed - some random bits. The randomness of the bits provided is critical to the security of the keys generated.

Returns:

a key pair object containing a public key and an associated private key.

Throws: KeyException

if the object is not properly initialized.

See Also:

initGenerateKeyPair, setParameter, getParameter, SecureRandom

  public final void initGenerateKeyPair(int strength) throws InvalidParameterException

Initializes this object for key generation for keys of a given size. Some algorithms require algorithm parameters which are expensive to generate (e.g. p, q and g for DSA), thus implementations routinely default these parameters for you. If you want to generate a new set of parameters for this class of algorithms, please consult the JavaSecurity reference for the parameters pertaining to the algorithm in question.

Parameters:

strength - an algorithm-specific measure of key strength. For example, a DSA signature can have a key size of 512 to 1024 bits. Other parameters that are algorithm-specific but not key specific are set using the setParameter method.

Throws: InvalidParameterException

if the strength parameter is out of range.

  public final void initGenerateKeyPair(int strength,
                                        byte seed[]) throws InvalidParameterException

Initializes this object for key generation for keys of a given size generated using the specified random seed. Some algorithms require algorithm parameters which are expensive to generate (e.g. p, q and g for DSA), thus implementations routinely default these parameters for you.

Parameters:

strength - an algorithm-specific measure of key strength. For example, a DSA signature can have a key size of 512 to 1024 bits. Other parameters that are algorithm-specific but not key specific are set using the setParameter method.

seed - the random bytes to be utilized by the key generation algorithm to generate the keys.

Throws: InvalidParameterException

if the strength parameter is out of range.

  public final void initGenerateKeyPair(KeyParams params) throws InvalidParameterException

Initializes this object for key generation. For algorithms that have algorithm families, this call will initialize the object for a family of parameters using the key's algorithm. Note that not all Signature algorithms have algorithm parameters.

Parameters:

params - the KeyParams object which holds parameters used for key generation.

Throws: InvalidParameterException

if a parameter is invalid.

  public final void initVerify(PublicKey publicKey) throws InvalidKeyException

Initializes this object for verification. If this method is called again with a different argument, it negates the effect of this call.

Parameters:

publicKey - the public key.

Throws: InvalidKeyException

if the key is invalid.

  public final void initSign(PrivateKey privateKey) throws InvalidKeyException

Initialize this object for signing. If this method is called again with a different argument, it negates the effect of this call.

Parameters:

privateKey - the private key.

Throws: InvalidKeyException

if the key is invalid.

  public final byte[] sign() throws SignatureException

Returns the signature bytes of all the data updated. This call resets the object to the state it was in right after the call to initSign(PrivateKey). The signature returned is X.509-encoded.

Returns:

the signature bytes of the signing operation's result.

Throws: SignatureException

if the signature is not initialized properly.

  public final boolean verify(byte signature[]) throws SignatureException

Verifies the passed-in signature. The signature bytes are expected to be X.509-encoded. This call resets the object to the state it was in right after the call to initVerify(PublicKey).

Parameters:

signature - the signature bytes to be verified.

Returns:

true if the signature was verified, false if not.

Throws: SignatureException

if the signature is not initialized properly, or it is improperly encoded or of the wrong type, etc.

  public final void update(byte b) throws SignatureException

Updates the data to be signed or verified by a byte.

Parameters:

b - the byte to update.

Throws: SignatureException

if the signature is not initialized properly.

  public final void update(byte data[]) throws SignatureException

Updates the data to be signed or verified, using the specified array of bytes.

Parameters:

data - the byte array to be updated.

Throws: SignatureException

if the signature is not initialized properly.

  public final void update(byte data[],
                           int off,
                           int len) throws SignatureException

Updates the data to be signed or verified, using the specified array of bytes, starting at the specified offset.

Parameters:

data - the array of bytes.

off - the offset to start from in the array of bytes.

len - the number of bytes to use, starting at offset.

Throws: SignatureException

if the signature is not initialized properly.

  public final String getAlgorithm()

Returns the name of the algorithm for this signature object.

Returns:

the name of the algorithm for this signature object.

  public final String toString()

Returns a string representation of this signature object, providing information that includes the state of the object and the name of the algorithm used.

Returns:

a string representation of this signature object.

Overrides:

toString in class Object

  public final void setParameter(String param,
                                 Object value) throws InvalidParameterException

Sets the specified algorithm parameter to the specified value. This method supplies a general-purpose mechanism through which it is possible to set the various parameters of this object. A parameter may be any settable parameter for the algorithm, such as parameter sizes, or a source of random bits for signature generation (if appropriate), or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.

Parameters:

param - the string identifier of the parameter.

value - the parameter value.

Throws: InvalidParameterException

if param is an invalid parameter for this signature algorithm engine, the parameter is already set and cannot be set again, a security exception occurs, and so on.

  public final Object getParameter(String param) throws InvalidParameterException

Gets the value of the specified algorithm parameter. This method supplies a general-purpose mechanism through which it is possible to get the various parameters of this object. A parameter may be any settable parameter for the algorithm, such as parameter sizes, or a source of random bits for signature generation (if appropriate), or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.

Parameters:

param - the string name of the parameter.

Returns:

the object that represents the parameter value, or null if there is none.

Throws: InvalidParameterException

if param is an invalid parameter for this engine, or another exception occurs while trying to get this parameter.

  protected abstract void engineInitVerify(byte publicKey[],
                                           String format) throws InvalidKeyException

SPI: Initializes this signature object with the specified public key for verification operations.

Parameters:

publicKey - a public key, encoded using format.

format - the format in which the key is encoded. It is recommended that all JavaSecurity implementations be able to decode X.509-encoded keys.

Throws: InvalidKeyException

if the key is improperly encoded, parameters are missing, and so on.

  protected abstract void engineInitSign(byte privateKey[],
                                         String format) throws InvalidKeyException

SPI:Initializes this signature object with the specified private key for signing operations.

Parameters:

privateKey - a private key, encoded using format.

format - the format in which the key is encoded. It is recommended that all JavaSecurity implementation be able to decode DER encoded keys.

Throws: InvalidKeyException

if the key is improperly encoded, parameters are missing, and so on.

  protected abstract void engineInitGenerateKeyPair(int strength) throws InvalidParameterException

SPI: Initializes this signature object for key generation for keys of a given size. Note that implementations are free to default non-security sensitive algorithm values, unless overriden by the KEY_ALGORITHM parameter.

Parameters:

strength - an algorithm-specific measure of key strength. For example, a DSA signature can have a key size of 512 to 1024 bits. Other parameters that are algorithm-specific but not key-specific are set using the setParameter method.

Throws: InvalidParameterException

if the strength passed is invalid for this algorithm or this implementation.

  protected abstract void engineInitGenerateKeyPair(int strength,
                                                    byte seed[]) throws InvalidParameterException

SPI: Initializes this signature object for key generation for keys of a given size generated using the specified random seed. Note that implementations are free to default non-security sensitive algorithm values, unless overriden by the KEY_ALGORITHM parameter.

Parameters:

strength - an algorithm-specific measure of key strength. For example, a DSA signature can have a key size of 512 to 1024 bits. Other parameters that are algorithm-specific but not key-specific are set using the setParameter method.

seed - the random bytes to be utilized by the key generation algorithm to generate the keys.

Throws: InvalidParameterException

if the strength passed is invalid for this algorithm or this implementation.

  protected void engineInitGenerateKeyPair(KeyParams params) throws InvalidParameterException

SPI: Initializes this signature object for key generation. This will typically involve key or algorithm parameters. By default this will throw an exception.

Parameters:

params - the key parameters to be used for key generation, if any.

Throws: InvalidParameterException

if a parameter is invalid.

Throws: ProviderException

by default, stating that this operation is not implemented.

  protected abstract KeyPair engineGenerateKeyPair(byte seed[]) throws KeyException

SPI: Generates a pair of keys suitable for this algorithm.

Parameters:

seed - some random bits. The randomness of the bits provided is critical to the security of the keys generated.

Returns:

a key pair object containing a public key and an associated private key.

Throws: KeyException

if an exception occurs during key generation.

  protected abstract void engineUpdate(byte b) throws SignatureException

SPI: Updates the data to be signed or verified using the specified byte.

Parameters:

b - the byte to update.

Throws: SignatureException

if the engine is not initialized properly.

  protected abstract void engineUpdate(byte b[],
                                       int off,
                                       int len) throws SignatureException

SPI: Updates the data to be signed or verified, using the specified array of bytes, starting at the specified offset.

Parameters:

data - the array of bytes.

off - the offset to start from in the array of bytes.

len - the number of bytes to use, starting at offset.

Throws: SignatureException

if the engine is not initialized properly.

  protected abstract byte[] engineSign() throws SignatureException

SPI: Returns the signature bytes of all the data updated so far. The signature returned is X.509-encoded. For more information about the X.509 encoding, see X.509 certificates.

Returns:

the signature bytes of the signing operation's result.

Throws: SignatureException

if the signature is not initialized properly.

  protected abstract boolean engineVerify(byte sigBytes[]) throws SignatureException

SPI: Verifies the passed-in signature. The signature bytes are expected to be X.509-encoded. For more information about the X.509 encoding, see X.509 certificates.

Parameters:

sigBytes - the signature bytes to be verified.

Returns:

true if the signature was verified, false if not.

Throws: SignatureException

if the signature is not initialized properly, or it is improperly encoded or of the wrong type, etc.

  protected abstract String engineToString()

SPI: Returns an informative human-readable string which succintly describes this object, its implementation details and the implementation-specific bits of information about the object or its state.

Returns:

a string representation of this signature object.

  protected abstract void engineSetParameter(String param,
                                             Object value) throws InvalidParameterException

Sets the specified algorithm parameter to the specified value. This method supplies a general-purpose mechanism through which it is possible to set the various parameters of this object. A parameter may be any settable parameter for the algorithm, such as parameter sizes, or a source of random bits for signature generation (if appropriate), or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.

Parameters:

param - the string identifier of the parameter.

value - the parameter value.

Throws: InvalidParameterException

if param is an invalid parameter for this signature algorithm engine, the parameter is already set and cannot be set again, a security exception occurs, and so on.

  protected abstract Object engineGetParameter(String param) throws InvalidParameterException

Gets the value of the specified algorithm parameter. This method supplies a general-purpose mechanism through which it is possible to get the various parameters of this object. A parameter may be any settable parameter for the algorithm, such as parameter sizes, or a source of random bits for signature generation (if appropriate), or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.

Parameters:

param - the string name of the parameter.

Returns:

the object that represents the parameter value, or null if there is none.

Throws: InvalidParameterException

if param is an invalid parameter for this engine, or another exception occurs while trying to get this parameter.

  public Object clone() throws CloneNotSupportedException

Returns a clone if the implementation is cloneable.

Returns:

a clone if the implementation is cloneable.

Throws: CloneNotSupportedException

if this is called on an implementation that does not support Cloneable.

Overrides:

clone in class Object

All Packages  Class Hierarchy  This Package  Previous  Next  Index