FileDocCategorySizeDatePackage
Signature.javaAPI DocAndroid 1.5 API25644Wed May 06 22:41:06 BST 2009java.security

Signature

public abstract class Signature extends SignatureSpi
{@code Signature} is an engine class which is capable of creating and verifying digital signatures, using different algorithms that have been registered with the {@link Security} class.
see
SignatureSpi
since
Android 1.0

Fields Summary
private static final String
SERVICE
private static org.apache.harmony.security.fortress.Engine
engine
private Provider
provider
private String
algorithm
protected static final int
UNINITIALIZED
Constant that indicates that this {@code Signature} instance has not yet been initialized.
protected static final int
SIGN
Constant that indicates that this {@code Signature} instance has been initialized for signing.
protected static final int
VERIFY
Constant that indicates that this {@code Signature} instance has been initialized for verification.
protected int
state
Represents the current state of this {@code Signature}. The three possible states are {@link #UNINITIALIZED}, {@link #SIGN} or {@link #VERIFY}.
Constructors Summary
protected Signature(String algorithm)
Constructs a new instance of {@code Signature} with the name of the algorithm to use.

param
algorithm the name of algorithm to use.
since
Android 1.0


                                               
       
        this.algorithm = algorithm;
    
Methods Summary
public java.lang.Objectclone()

        if (this instanceof Cloneable) {
            return super.clone();
        } else {
            throw new CloneNotSupportedException();
        }
    
public final java.lang.StringgetAlgorithm()
Returns the name of the algorithm of this {@code Signature}.

return
the name of the algorithm of this {@code Signature}.
since
Android 1.0

        return algorithm;
    
public static java.security.SignaturegetInstance(java.lang.String algorithm)
Returns a new instance of {@code Signature} that utilizes the specified algorithm.

param
algorithm the name of the algorithm to use.
return
a new instance of {@code Signature} that utilizes the specified algorithm.
throws
NoSuchAlgorithmException if the specified algorithm is not available.
throws
NullPointerException if {@code algorithm} is {@code null}.
since
Android 1.0

        if (algorithm == null) {
            throw new NullPointerException(Messages.getString("security.01")); //$NON-NLS-1$
        }
        Signature result;
        synchronized (engine) {
            engine.getInstance(algorithm, null);
            if (engine.spi instanceof Signature) {
                result = (Signature) engine.spi;
                result.algorithm = algorithm;
                result.provider = engine.provider;
            } else {
                result = new SignatureImpl((SignatureSpi) engine.spi,
                        engine.provider, algorithm);
            }
        }
        return result;
    
public static java.security.SignaturegetInstance(java.lang.String algorithm, java.lang.String provider)
Returns a new instance of {@code Signature} that utilizes the specified algorithm from the specified provider.

param
algorithm the name of the algorithm to use.
param
provider the name of the provider.
return
a new instance of {@code Signature} that utilizes the specified algorithm from the specified provider.
throws
NoSuchAlgorithmException if the specified algorithm is not available.
throws
NoSuchProviderException if the specified provider is not available.
throws
NullPointerException if {@code algorithm} is {@code null}.
since
Android 1.0

        if (algorithm == null) {
            throw new NullPointerException(Messages.getString("security.01")); //$NON-NLS-1$
        }
        if ((provider == null) || (provider.length() == 0)) {
            throw new IllegalArgumentException(
                    Messages.getString("security.02")); //$NON-NLS-1$
        }
        Provider p = Security.getProvider(provider);
        if (p == null) {
            throw new NoSuchProviderException(Messages.getString("security.03", provider)); //$NON-NLS-1$
        }
        return getSignatureInstance(algorithm, p);
    
public static java.security.SignaturegetInstance(java.lang.String algorithm, java.security.Provider provider)
Returns a new instance of {@code Signature} that utilizes the specified algorithm from the specified provider.

param
algorithm the name of the algorithm to use.
param
provider the security provider.
return
a new instance of {@code Signature} that utilizes the specified algorithm from the specified provider.
throws
NoSuchAlgorithmException if the specified algorithm is not available.
throws
NullPointerException if {@code algorithm} is {@code null}.
since
Android 1.0

        if (algorithm == null) {
            throw new NullPointerException(Messages.getString("security.01")); //$NON-NLS-1$
        }
        if (provider == null) {
            throw new IllegalArgumentException(Messages.getString("security.04")); //$NON-NLS-1$
        }
        return getSignatureInstance(algorithm, provider);
    
public final java.lang.ObjectgetParameter(java.lang.String param)
Returns the value of the parameter with the specified name.

param
param the name of the requested parameter value
return
the value of the parameter with the specified name, maybe {@code null}.
throws
InvalidParameterException if {@code param} is not a valid parameter for this {@code Signature} or an other error occures.
deprecated
There is no generally accepted parameter naming convention.
since
Android 1.0

        return engineGetParameter(param);
    
public final java.security.AlgorithmParametersgetParameters()
Returns the {@code AlgorithmParameters} of this {@link Signature} instance.

return
the {@code AlgorithmParameters} of this {@link Signature} instance, maybe {@code null}.
since
Android 1.0

        return engineGetParameters();
    
public final java.security.ProvidergetProvider()
Returns the provider associated with this {@code Signature}.

return
the provider associated with this {@code Signature}.
since
Android 1.0

        return provider;
    
private static java.security.SignaturegetSignatureInstance(java.lang.String algorithm, java.security.Provider provider)

        Signature result;
        synchronized (engine) {
            engine.getInstance(algorithm, provider, null);
            if (engine.spi instanceof Signature) {
                result = (Signature) engine.spi;
                result.algorithm = algorithm;
                result.provider = provider;
            } else {
                result = new SignatureImpl((SignatureSpi) engine.spi, provider,
                        algorithm);
            }
        }
        return result;
    
public final voidinitSign(java.security.PrivateKey privateKey)
Initializes this {@code Signature} instance for signing, using the private key of the identity whose signature is going to be generated.

param
privateKey the private key.
throws
InvalidKeyException if {@code privateKey} is not valid.
since
Android 1.0

        engineInitSign(privateKey);
        state = SIGN;
    
public final voidinitSign(java.security.PrivateKey privateKey, java.security.SecureRandom random)
Initializes this {@code Signature} instance for signing, using the private key of the identity whose signature is going to be generated and the specified source of randomness.

param
privateKey the private key.
param
random the {@code SecureRandom} to use.
throws
InvalidKeyException if {@code privateKey} is not valid.
since
Android 1.0

        engineInitSign(privateKey, random);
        state = SIGN;
    
public final voidinitVerify(java.security.PublicKey publicKey)
Initializes this {@code Signature} instance for signature verification, using the public key of the identity whose signature is going to be verified.

param
publicKey the public key.
throws
InvalidKeyException if {@code publicKey} is not valid.
since
Android 1.0

        engineInitVerify(publicKey);
        state = VERIFY;
    
public final voidinitVerify(java.security.cert.Certificate certificate)
Initializes this {@code Signature} instance for signature verification, using the certificate of the identity whose signature is going to be verified.

If the given certificate is an instance of {@link X509Certificate} and has a key usage parameter that indicates, that this certificate is not to be used for signing, an {@code InvalidKeyException} is thrown.

param
certificate the certificate used to verify a signature.
throws
InvalidKeyException if the publicKey in the certificate is not valid or not to be used for signing.
since
Android 1.0

        if (certificate instanceof X509Certificate) {
            Set ce = ((X509Certificate) certificate).getCriticalExtensionOIDs();
            boolean critical = false;
            if (ce != null && !ce.isEmpty()) {
                for (Iterator i = ce.iterator(); i.hasNext();) {
                    if ("2.5.29.15".equals(i.next())) {  //$NON-NLS-1$
                        //KeyUsage OID = 2.5.29.15
                        critical = true;
                        break;
                    }
                }
                if (critical) {
                    boolean[] keyUsage = ((X509Certificate) certificate)
                            .getKeyUsage();
                    // As specified in RFC 3280 -
                    // Internet X.509 Public Key Infrastructure
                    // Certificate and Certificate Revocation List (CRL) Profile.
                    // (http://www.ietf.org/rfc/rfc3280.txt)
                    //
                    // KeyUsage ::= BIT STRING { digitalSignature (0), <skipped> }
                    if ((keyUsage != null) && (!keyUsage[0])) { // digitalSignature
                        throw new InvalidKeyException(
                                Messages.getString("security.26")); //$NON-NLS-1$
                    }
                }
            }
        }
        engineInitVerify(certificate.getPublicKey());
        state = VERIFY;
    
public final voidsetParameter(java.lang.String param, java.lang.Object value)
Sets the specified parameter to the given value.

param
param the name of the parameter.
param
value the parameter value.
throws
InvalidParameterException if the parameter is invalid, already set or is not allowed to be changed.
deprecated
Use {@link #setParameter(AlgorithmParameterSpec)}
since
Android 1.0

        engineSetParameter(param, value);
    
public final voidsetParameter(java.security.spec.AlgorithmParameterSpec params)
Sets the specified {@code AlgorithmParameterSpec}.

param
params the parameter to set.
throws
InvalidAlgorithmParameterException if the parameter is invalid, already set or is not allowed to be changed.
since
Android 1.0

        engineSetParameter(params);
    
public final byte[]sign()
Generates and returns the signature of all updated data.

This {@code Signature} instance is reset to the state of its last initialization for signing and thus can be used for another signature from the same identity.

return
the signature of all updated data.
throws
SignatureException if this {@code Signature} instance is not initialized properly.
since
Android 1.0

        if (state != SIGN) {
            throw new SignatureException(
                    Messages.getString("security.27")); //$NON-NLS-1$
        }
        return engineSign();
    
public final intsign(byte[] outbuf, int offset, int len)
Generates and stores the signature of all updated data in the provided {@code byte[]} at the specified position with the specified length.

This {@code Signature} instance is reset to the state of its last initialization for signing and thus can be used for another signature from the same identity.

param
outbuf the buffer to store the signature.
param
offset the index of the first byte in {@code outbuf} to store.
param
len the number of bytes allocated for the signature.
return
the number of bytes stored in {@code outbuf}.
throws
SignatureException if this {@code Signature} instance is not initialized properly.
throws
IllegalArgumentException if {@code offset} or {@code len} are not valid in respect to {@code outbuf}.
since
Android 1.0

       
        if (outbuf == null || offset < 0 || len < 0 ||
                offset + len > outbuf.length) {
            throw new IllegalArgumentException(
                    Messages.getString("security.05")); //$NON-NLS-1$
        }
        if (state != SIGN) {
            throw new SignatureException(
                    Messages.getString("security.27")); //$NON-NLS-1$
        }
        return engineSign(outbuf, offset, len);
    
private java.lang.StringstateToString(int state)

        switch (state) {
        case UNINITIALIZED:
            return "UNINITIALIZED"; //$NON-NLS-1$
        case SIGN:
            return "SIGN"; //$NON-NLS-1$
        case VERIFY:
            return "VERIFY"; //$NON-NLS-1$
        default:
            return ""; //$NON-NLS-1$
        }
    
public java.lang.StringtoString()
Returns a string containing a concise, human-readable description of this {@code Signature} including its algorithm and its state.

return
a printable representation for this {@code Signature}.
since
Android 1.0

        return "SIGNATURE " + algorithm + " state: " + stateToString(state); //$NON-NLS-1$ //$NON-NLS-2$
    
public final voidupdate(byte b)
Updates the data to be verified or to be signed, using the specified {@code byte}.

param
b the byte to update with.
throws
SignatureException if this {@code Signature} instance is not initialized properly.
since
Android 1.0

        if (state == UNINITIALIZED) {
            throw new SignatureException(
                    Messages.getString("security.27")); //$NON-NLS-1$
        }
        engineUpdate(b);
    
public final voidupdate(byte[] data)
Updates the data to be verified or to be signed, using the specified {@code byte[]}.

param
data the byte array to update with.
throws
SignatureException if this {@code Signature} instance is not initialized properly.
since
Android 1.0

        if (state == UNINITIALIZED) {
            throw new SignatureException(
                    Messages.getString("security.27")); //$NON-NLS-1$
        }
        engineUpdate(data, 0, data.length);
    
public final voidupdate(byte[] data, int off, int len)
Updates the data to be verified or to be signed, using the given {@code byte[]}, starting form the specified index for the specified length.

param
data the byte array to update with.
param
off the start index in {@code data} of the data.
param
len the number of bytes to use.
throws
SignatureException if this {@code Signature} instance is not initialized properly.
since
Android 1.0

        if (state == UNINITIALIZED) {
            throw new SignatureException(
                    Messages.getString("security.27")); //$NON-NLS-1$
        }
        if (data == null || off < 0 || len < 0 ||
                off + len > data.length) {
            throw new IllegalArgumentException(
                    Messages.getString("security.05")); //$NON-NLS-1$
        }
        engineUpdate(data, off, len);
    
public final voidupdate(java.nio.ByteBuffer data)
Updates the data to be verified or to be signed, using the specified {@code ByteBuffer}.

param
data the {@code ByteBuffer} to update with.
throws
SignatureException if this {@code Signature} instance is not initialized properly.
since
Android 1.0

        if (state == UNINITIALIZED) {
            throw new SignatureException(
                    Messages.getString("security.27")); //$NON-NLS-1$
        }
        engineUpdate(data);
    
public final booleanverify(byte[] signature)
Indicates whether the given {@code signature} can be verified using the public key or a certificate of the signer.

This {@code Signature} instance is reset to the state of its last initialization for verifying and thus can be used to verify another signature of the same signer.

param
signature the signature to verify.
return
{@code true} if the signature was verified, {@code false} otherwise.
throws
SignatureException if this {@code Signature} instance is not initialized properly.
since
Android 1.0

        if (state != VERIFY) {
            throw new SignatureException(
                    Messages.getString("security.27")); //$NON-NLS-1$
        }
        return engineVerify(signature);
    
public final booleanverify(byte[] signature, int offset, int length)
Indicates whether the given {@code signature} starting at index {@code offset} with {@code length} bytes can be verified using the public key or a certificate of the signer.

This {@code Signature} instance is reset to the state of its last initialization for verifying and thus can be used to verify another signature of the same signer.

param
signature the {@code byte[]} containing the signature to verify.
param
offset the start index in {@code signature} of the signature.
param
length the number of bytes allocated for the signature.
return
{@code true} if the signature was verified, {@code false} otherwise.
throws
SignatureException if this {@code Signature} instance is not initialized properly.
throws
IllegalArgumentException if {@code offset} or {@code length} are not valid in respect to {@code signature}.
since
Android 1.0

        if (state != VERIFY) {
            throw new SignatureException(
                    Messages.getString("security.27")); //$NON-NLS-1$
        }
        if (signature == null || offset < 0 || length < 0 ||
                offset + length > signature.length) {
            throw new IllegalArgumentException(
                    Messages.getString("security.05")); //$NON-NLS-1$
        }
        return engineVerify(signature, offset, length);