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() 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:
Update the bytes for signing or verifying with calls to update.
*Signature instance for a designated digital
* signature algorithm.
*
* @param algorithm
* the algorithm to use.
*/
protected Signature(String algorithm)
{
this.algorithm = algorithm;
state = UNINITIALIZED;
}
/**
* Returns an instance of Signature representing the specified
* signature.
*
* @param algorithm the algorithm to use.
* @return a new instance repesenting the desired algorithm.
* @throws NoSuchAlgorithmException if the algorithm is not implemented by any
* provider.
* @throws IllegalArgumentException if algorithm is
* null or is an empty string.
*/
public static Signature getInstance(String algorithm)
throws NoSuchAlgorithmException
{
Provider[] p = Security.getProviders();
NoSuchAlgorithmException lastException = null;
for (int i = 0; i < p.length; i++)
try
{
return getInstance(algorithm, p[i]);
}
catch (NoSuchAlgorithmException x)
{
lastException = x;
}
if (lastException != null)
throw lastException;
throw new NoSuchAlgorithmException(algorithm);
}
/**
* Returns an instance of Signature representing the specified
* signature from the named provider.
*
* @param algorithm the algorithm to use.
* @param provider the name of the provider to use.
* @return a new instance repesenting the desired algorithm.
* @throws NoSuchProviderException if the named provider was not found.
* @throws NoSuchAlgorithmException if the algorithm is not implemented by the
* named provider.
* @throws IllegalArgumentException if either algorithm or
* provider is null or empty.
*/
public static Signature getInstance(String algorithm, String provider)
throws NoSuchAlgorithmException, NoSuchProviderException
{
if (provider == null)
throw new IllegalArgumentException("provider MUST NOT be null");
provider = provider.trim();
if (provider.length() == 0)
throw new IllegalArgumentException("provider MUST NOT be empty");
Provider p = Security.getProvider(provider);
if (p == null)
throw new NoSuchProviderException(provider);
return getInstance(algorithm, p);
}
/**
* Returns an instance of Signature representing the specified
* signature from the specified {@link Provider}.
*
* @param algorithm the algorithm to use.
* @param provider the {@link Provider} to use.
* @return a new instance repesenting the desired algorithm.
* @throws NoSuchAlgorithmException if the algorithm is not implemented by the
* {@link Provider}.
* @throws IllegalArgumentException if either algorithm or
* provider is null, or if
* algorithm is an empty string.
*/
public static Signature getInstance(String algorithm, Provider provider)
throws NoSuchAlgorithmException
{
StringBuilder sb = new StringBuilder("Signature algorithm [")
.append(algorithm).append("] from provider[")
.append(provider).append("] ");
Object o;
try
{
o = Engine.getInstance(SIGNATURE, algorithm, provider);
}
catch (InvocationTargetException x)
{
Throwable cause = x.getCause();
if (cause instanceof NoSuchAlgorithmException)
throw (NoSuchAlgorithmException) cause;
if (cause == null)
cause = x;
sb.append("could not be created");
NoSuchAlgorithmException y = new NoSuchAlgorithmException(sb.toString());
y.initCause(cause);
throw y;
}
Signature result;
if (o instanceof SignatureSpi)
result = new DummySignature((SignatureSpi) o, algorithm);
else if (o instanceof Signature)
{
result = (Signature) o;
result.algorithm = algorithm;
}
else
{
sb.append("is of an unexpected Type: ").append(o.getClass().getName());
throw new NoSuchAlgorithmException(sb.toString());
}
result.provider = provider;
return result;
}
/**
* Returns the {@link Provider} of this instance.
*
* @return the {@link Provider} of this instance.
*/
public final Provider getProvider()
{
return provider;
}
/**
* Initializes this instance with the public key for verification purposes.
*
* @param publicKey
* the public key to verify with.
* @throws InvalidKeyException
* if the key is invalid.
*/
public final void initVerify(PublicKey publicKey) throws InvalidKeyException
{
state = VERIFY;
engineInitVerify(publicKey);
}
/**
* Verify a signature with a designated {@link Certificate}. This is a FIPS
* 140-1 compatible method since it verifies a signature with a certificate.
*
* If the {@link 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.
* * @param certificate * a {@link Certificate} containing a public key to verify with. * @throws InvalidKeyException if the key is invalid. */ public final void initVerify(Certificate certificate) throws InvalidKeyException { state = VERIFY; if (certificate.getType().equals("X509")) { X509Certificate cert = (X509Certificate) certificate; boolean[]array = cert.getKeyUsage(); if (array != null && array[0] == false) throw new InvalidKeyException( "KeyUsage of this Certificate indicates it cannot be used for digital signing"); } this.initVerify(certificate.getPublicKey()); } /** * Initializes this class with the private key for signing purposes. * * @param privateKey * the private key to sign with. * @throws InvalidKeyException * if the key is invalid. */ public final void initSign(PrivateKey privateKey) throws InvalidKeyException { state = SIGN; engineInitSign(privateKey); } /** * Initializes this class with the private key and source of randomness for * signing purposes. * * @param privateKey * the private key to sign with. * @param random * the {@link SecureRandom} to use. * @throws InvalidKeyException * if the key is invalid. */ public final void initSign(PrivateKey privateKey, SecureRandom random) throws InvalidKeyException { state = SIGN; engineInitSign(privateKey, random); } /** * Returns the signature bytes of all the data fed to this instance. The * format of the output depends on the underlying signature algorithm. * * @return the signature bytes. * @throws SignatureException * if the engine is not properly initialized. */ public final byte[] sign() throws SignatureException { if (state == SIGN) return engineSign(); else throw new 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 {@link SignatureException}. If
* it is greater than or equal then it is ignored.
true if verified, false otherwise.
* @throws SignatureException
* if the engine is not properly initialized or the signature does
* not check.
*/
public final boolean verify(byte[]signature) throws SignatureException
{
if (state == VERIFY)
return engineVerify(signature);
else
throw new SignatureException();
}
/**
* Verifies a designated signature.
*
* @param signature
* the signature bytes to verify.
* @param offset
* the offset to start at in the array.
* @param length
* the number of the bytes to use from the array.
* @return 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.
* @throws SignatureException
* if the engine is not properly initialized or the signature does
* not check.
*/
public final boolean verify(byte[] signature, int offset, int length)
throws SignatureException
{
if (state != VERIFY)
throw new SignatureException("illegal state");
if (signature == null)
throw new IllegalArgumentException("signature is null");
if (offset < 0)
throw new IllegalArgumentException("offset is less than 0");
if (length < 0)
throw new IllegalArgumentException("length is less than 0");
if (offset + length < signature.length)
throw new IllegalArgumentException("range is out of bounds");
return engineVerify(signature, offset, length);
}
/**
* Updates the data to be signed or verified with the specified byte.
*
* @param b
* the byte to update with.
* @throws SignatureException
* if the engine is not properly initialized.
*/
public final void update(byte b) throws SignatureException
{
if (state != UNINITIALIZED)
engineUpdate(b);
else
throw new SignatureException();
}
/**
* Updates the data to be signed or verified with the specified bytes.
*
* @param data
* the array of bytes to use.
* @throws SignatureException
* if the engine is not properly initialized.
*/
public final void update(byte[]data) throws SignatureException
{
if (state != UNINITIALIZED)
engineUpdate(data, 0, data.length);
else
throw new SignatureException();
}
/**
* Updates the data to be signed or verified with the specified bytes.
*
* @param data
* an array of bytes to use.
* @param off
* the offset to start at in the array.
* @param len
* the number of bytes to use from the array.
* @throws SignatureException
* if the engine is not properly initialized.
*/
public final void update(byte[]data, int off, int len)
throws SignatureException
{
if (state != UNINITIALIZED)
engineUpdate(data, off, len);
else
throw new SignatureException();
}
/**
* Update this signature with the {@link java.nio.Buffer#remaining()}
* bytes of the input buffer.
*
* @param input The input buffer.
* @throws SignatureException If this instance was not properly
* initialized.
*/
public final void update(ByteBuffer input) throws SignatureException
{
if (state != UNINITIALIZED)
engineUpdate(input);
else
throw new SignatureException("not initialized");
}
/**
* Returns the name of the algorithm currently used. The names of algorithms
* are usually SHA/DSA or SHA/RSA.
*
* @return name of algorithm.
*/
public final String getAlgorithm()
{
return algorithm;
}
/**
* Returns a rstring representation of this instance.
*
* @return a rstring representation of this instance.
*/
public String toString()
{
return (algorithm + " Signature");
}
/**
* Sets the specified algorithm parameter to the specified value.
*
* @param param
* the parameter name.
* @param 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.
* @deprecated use the other setParameter
*/
public final void setParameter(String param, Object value)
throws InvalidParameterException
{
engineSetParameter(param, value);
}
/**
* Sets the signature engine with the specified {@link AlgorithmParameterSpec}.
*
* By default, and unless overriden by the concrete SPI, this method always * throws an {@link UnsupportedOperationException}.
* * @param 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. */ public final void setParameter(AlgorithmParameterSpec params) throws InvalidAlgorithmParameterException { engineSetParameter(params); } /** * Return the parameters of the algorithm used in this instance as an * {@link AlgorithmParameters}. * * @return the parameters used with this instance, ornull if
* this instance does not use any parameters.
*/
public final AlgorithmParameters getParameters()
{
return engineGetParameters();
}
/**
* Returns the value for the specified algorithm parameter.
*
* @param param
* the parameter name.
* @return the parameter value.
* @throws InvalidParameterException
* if the parameter is invalid.
* @deprecated use the other getParameter
*/
public final Object getParameter(String param)
throws InvalidParameterException
{
return engineGetParameter(param);
}
/**
* Returns a clone of this instance.
*
* @return a clone of this instace.
* @throws CloneNotSupportedException
* if the implementation does not support cloning.
*/
public Object clone() throws CloneNotSupportedException
{
return super.clone();
}
}