Overview Package Class Use Source Tree Index Deprecated About
Prev Class | Next ClassFrames | No Frames
Summary: Nested | Field | Method | ConstrDetail: Nested | Field | Method | Constr

java.security

Class Signature

public abstract class Signature
extends SignatureSpi
Signature is used to provide an interface to digital signature algorithms. Digital signatures provide authentication and data integrity of digital data.

The GNU provider provides the NIST standard DSA which uses DSA and SHA-1. It can be specified by SHA/DSA, SHA-1/DSA or its OID. If the RSA signature algorithm is provided then it could be MD2/RSA. MD5/RSA, or SHA-1/RSA. The algorithm must be specified because there is no default.

Signature provides implementation-independent algorithms which are requested by the user through the getInstance()<?code> methods. It can be requested by specifying just the algorithm name or by specifying both the algorithm name and provider name.

The three phases of using Signature are:

  1. Initializing:
    • It must be initialized with a private key for signing.
    • It must be initialized with a public key for verifying.
    • Updating:

      Update the bytes for signing or verifying with calls to update.

    • Signing or Verify the signature on the currently stored bytes by calling sign or verify.

    Field Summary

    protected static int
    SIGN
    Possible state value which signifies that this instance has been initialized for signing purposes.
    protected static int
    UNINITIALIZED
    Possible state value which signifies that this instance has not yet been initialized.
    protected static int
    VERIFY
    Possible state value which signifies that this instance has been initialized for verification purposes.
    protected int
    state
    Current sate of this instance.

    Fields inherited from class java.security.SignatureSpi

    appRandom

    Constructor Summary

    Signature(String algorithm)
    Constructs a new Signature instance for a designated digital signature algorithm.

    Method Summary

    Object
    clone()
    Returns a clone of this instance.
    String
    getAlgorithm()
    Returns the name of the algorithm currently used.
    static Signature
    getInstance(String algorithm)
    Returns an instance of Signature representing the specified signature.
    static Signature
    getInstance(String algorithm, String provider)
    Returns an instance of Signature representing the specified signature from the named provider.
    static Signature
    getInstance(String algorithm, Provider provider)
    Returns an instance of Signature representing the specified signature from the specified Provider.
    Object
    getParameter(String param)
    Deprecated. use the other getParameter
    AlgorithmParameters
    getParameters()
    Return the parameters of the algorithm used in this instance as an AlgorithmParameters.
    Provider
    getProvider()
    Returns the Provider of this instance.
    void
    initSign(PrivateKey privateKey)
    Initializes this class with the private key for signing purposes.
    void
    initSign(PrivateKey privateKey, SecureRandom random)
    Initializes this class with the private key and source of randomness for signing purposes.
    void
    initVerify(PublicKey publicKey)
    Initializes this instance with the public key for verification purposes.
    void
    initVerify(Certificate certificate)
    Verify a signature with a designated Certificate.
    void
    setParameter(String param, Object value)
    Deprecated. use the other setParameter
    void
    setParameter(AlgorithmParameterSpec params)
    Sets the signature engine with the specified AlgorithmParameterSpec.
    byte[]
    sign()
    Returns the signature bytes of all the data fed to this instance.
    int
    sign(byte[] outbuf, int offset, int len)
    Generates signature bytes of all the data fed to this instance and stores it in the designated array.
    String
    toString()
    Returns a rstring representation of this instance.
    void
    update(byte b)
    Updates the data to be signed or verified with the specified byte.
    void
    update(byte[] data)
    Updates the data to be signed or verified with the specified bytes.
    void
    update(byte[] data, int off, int len)
    Updates the data to be signed or verified with the specified bytes.
    void
    update(ByteBuffer input)
    Update this signature with the Buffer.remaining() bytes of the input buffer.
    boolean
    verify(byte[] signature)
    Verifies a designated signature.
    boolean
    verify(byte[] signature, int offset, int length)
    Verifies a designated signature.

    Methods inherited from class java.security.SignatureSpi

    clone, engineGetParameter, engineGetParameters, engineInitSign, engineInitSign, engineInitVerify, engineSetParameter, engineSetParameter, engineSign, engineSign, engineUpdate, engineUpdate, engineUpdate, engineVerify, engineVerify

    Methods inherited from class java.lang.Object

    clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

    Field Details

    SIGN

    protected static final int SIGN
    Possible state value which signifies that this instance has been initialized for signing purposes.
    Field Value:
    2

    UNINITIALIZED

    protected static final int UNINITIALIZED
    Possible state value which signifies that this instance has not yet been initialized.
    Field Value:
    0

    VERIFY

    protected static final int VERIFY
    Possible state value which signifies that this instance has been initialized for verification purposes.
    Field Value:
    3

    state

    protected int state
    Current sate of this instance.

    Constructor Details

    Signature

    protected Signature(String algorithm)
    Constructs a new Signature instance for a designated digital signature algorithm.
    Parameters:
    algorithm - the algorithm to use.

    Method Details

    clone

    public Object clone()
            throws CloneNotSupportedException
    Returns a clone of this instance.
    Overrides:
    clone in interface SignatureSpi
    Returns:
    a clone of this instace.
    Throws:
    CloneNotSupportedException - if the implementation does not support cloning.

    getAlgorithm

    public final String getAlgorithm()
    Returns the name of the algorithm currently used. The names of algorithms are usually SHA/DSA or SHA/RSA.
    Returns:
    name of algorithm.

    getInstance

    public static Signature getInstance(String algorithm)
            throws NoSuchAlgorithmException
    Returns an instance of Signature representing the specified signature.
    Parameters:
    algorithm - the algorithm to use.
    Returns:
    a new instance repesenting the desired algorithm.
    Throws:
    NoSuchAlgorithmException - if the algorithm is not implemented by any provider.
    IllegalArgumentException - if algorithm is null or is an empty string.

    getInstance

    public static Signature getInstance(String algorithm,
                                    String provider)
            throws NoSuchAlgorithmException,
                   NoSuchProviderException
    Returns an instance of Signature representing the specified signature from the named provider.
    Parameters:
    algorithm - the algorithm to use.
    provider - the name of the provider to use.
    Returns:
    a new instance repesenting the desired algorithm.
    Throws:
    NoSuchProviderException - if the named provider was not found.
    NoSuchAlgorithmException - if the algorithm is not implemented by the named provider.
    IllegalArgumentException - if either algorithm or provider is null or empty.

    getInstance

    public static Signature getInstance(String algorithm,
                                    Provider provider)
            throws NoSuchAlgorithmException
    Returns an instance of Signature representing the specified signature from the specified Provider.
    Parameters:
    algorithm - the algorithm to use.
    provider - the Provider to use.
    Returns:
    a new instance repesenting the desired algorithm.
    Throws:
    NoSuchAlgorithmException - if the algorithm is not implemented by the Provider.
    IllegalArgumentException - if either algorithm or provider is null, or if algorithm is an empty string.

    getParameter

    public final Object getParameter(String param)
            throws InvalidParameterException

    Deprecated. use the other getParameter

    Returns the value for the specified algorithm parameter.
    Parameters:
    param - the parameter name.
    Returns:
    the parameter value.
    Throws:
    InvalidParameterException - if the parameter is invalid.

    getParameters

    public final AlgorithmParameters getParameters()
    Return the parameters of the algorithm used in this instance as an AlgorithmParameters.
    Returns:
    the parameters used with this instance, or null if this instance does not use any parameters.

    getProvider

    public final Provider getProvider()
    Returns the Provider of this instance.
    Returns:
    the Provider of this instance.

    initSign

    public final void initSign(PrivateKey privateKey)
            throws InvalidKeyException
    Initializes this class with the private key for signing purposes.
    Parameters:
    privateKey - the private key to sign with.
    Throws:
    InvalidKeyException - if the key is invalid.

    initSign

    public final void initSign(PrivateKey privateKey,
                           SecureRandom random)
            throws InvalidKeyException
    Initializes this class with the private key and source of randomness for signing purposes.
    Parameters:
    privateKey - the private key to sign with.
    random - the SecureRandom to use.
    Throws:
    InvalidKeyException - if the key is invalid.

    initVerify

    public final void initVerify(PublicKey publicKey)
            throws InvalidKeyException
    Initializes this instance with the public key for verification purposes.
    Parameters:
    publicKey - the public key to verify with.
    Throws:
    InvalidKeyException - if the key is invalid.

    initVerify

    public final void initVerify(Certificate certificate)
            throws InvalidKeyException
    Verify a signature with a designated Certificate. This is a FIPS 140-1 compatible method since it verifies a signature with a certificate.

    If the Certificate is an X.509 one, has a KeyUsage parameter and that parameter indicates this key is not to be used for signing then an exception is thrown.

    Parameters:
    certificate - a Certificate containing a public key to verify with.
    Throws:
    InvalidKeyException - if the key is invalid.

    setParameter

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

    Deprecated. use the other setParameter

    Sets the specified algorithm parameter to the specified value.
    Parameters:
    param - the parameter name.
    value - the parameter value.
    Throws:
    InvalidParameterException - if the parameter is invalid, the parameter is already set and can not be changed, a security exception occured, etc.

    setParameter

    public final void setParameter(AlgorithmParameterSpec params)
            throws InvalidAlgorithmParameterException
    Sets the signature engine with the specified AlgorithmParameterSpec.

    By default, and unless overriden by the concrete SPI, this method always throws an UnsupportedOperationException.

    Parameters:
    params - the parameters to use for intializing this instance.
    Throws:
    InvalidParameterException - if the parameter is invalid, the parameter is already set and cannot be changed, a security exception occured, etc.

    sign

    public final byte[] sign()
            throws SignatureException
    Returns the signature bytes of all the data fed to this instance. The format of the output depends on the underlying signature algorithm.
    Returns:
    the signature bytes.
    Throws:
    SignatureException - if the engine is not properly initialized.

    sign

    public final int sign(byte[] outbuf,
                      int offset,
                      int len)
            throws SignatureException
    Generates signature bytes of all the data fed to this instance and stores it in the designated array. The format of the result depends on the underlying signature algorithm.

    After calling this method, the instance is reset to its initial state and can then be used to generate additional signatures.

    IMPLEMENTATION NOTE: Neither this method nor the GNU provider will return partial digests. If len is less than the signature length, this method will throw a SignatureException. If it is greater than or equal then it is ignored.

    Parameters:
    outbuf - array of bytes of where to store the resulting signature bytes.
    offset - the offset to start at in the array.
    len - the number of the bytes to use in the array.
    Returns:
    the real number of bytes used.
    Throws:
    SignatureException - if the engine is not properly initialized.
    Since:
    1.2

    toString

    public String toString()
    Returns a rstring representation of this instance.
    Overrides:
    toString in interface Object
    Returns:
    a rstring representation of this instance.

    update

    public final void update(byte b)
            throws SignatureException
    Updates the data to be signed or verified with the specified byte.
    Parameters:
    b - the byte to update with.
    Throws:
    SignatureException - if the engine is not properly initialized.

    update

    public final void update(byte[] data)
            throws SignatureException
    Updates the data to be signed or verified with the specified bytes.
    Parameters:
    data - the array of bytes to use.
    Throws:
    SignatureException - if the engine is not properly initialized.

    update

    public final void update(byte[] data,
                         int off,
                         int len)
            throws SignatureException
    Updates the data to be signed or verified with the specified bytes.
    Parameters:
    data - an array of bytes to use.
    off - the offset to start at in the array.
    len - the number of bytes to use from the array.
    Throws:
    SignatureException - if the engine is not properly initialized.

    update

    public final void update(ByteBuffer input)
            throws SignatureException
    Update this signature with the Buffer.remaining() bytes of the input buffer.
    Parameters:
    input - The input buffer.
    Throws:
    SignatureException - If this instance was not properly initialized.

    verify

    public final boolean verify(byte[] signature)
            throws SignatureException
    Verifies a designated signature.
    Parameters:
    signature - the signature bytes to verify.
    Returns:
    true if verified, false otherwise.
    Throws:
    SignatureException - if the engine is not properly initialized or the signature does not check.

    verify

    public final boolean verify(byte[] signature,
                            int offset,
                            int length)
            throws SignatureException
    Verifies a designated signature.
    Parameters:
    signature - the signature bytes to verify.
    offset - the offset to start at in the array.
    length - the number of the bytes to use from the array.
    Returns:
    true if verified, false otherwise.
    Throws:
    IllegalArgumentException - if the signature byte array is null, or the offset or length is less than 0, or the sum of the offset and length is greater than the length of the signature byte array.
    SignatureException - if the engine is not properly initialized or the signature does not check.
    Signature.java --- Signature Class Copyright (C) 1999, 2002, 2003, 2004 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

    Overview Package Class Use Source Tree Index Deprecated About