Java > Open Source Codes > java > security > Signature


1 /*
2  * @(#)Signature.java 1.99 04/05/18
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7   
8 package java.security;
9
10 import java.security.spec.AlgorithmParameterSpec ;
11 import java.util.*;
12 import java.util.concurrent.ConcurrentHashMap ;
13 import java.io.*;
14 import java.security.cert.Certificate ;
15 import java.security.cert.X509Certificate ;
16
17 import java.nio.ByteBuffer ;
18
19 import java.security.Provider.Service;
20
21 import javax.crypto.Cipher;
22 import javax.crypto.CipherSpi;
23 import javax.crypto.IllegalBlockSizeException;
24 import javax.crypto.BadPaddingException;
25 import javax.crypto.NoSuchPaddingException;
26
27 import sun.security.util.Debug;
28 import sun.security.jca.*;
29 import sun.security.jca.GetInstance.Instance;
30
31 /**
32  * This Signature class is used to provide applications the functionality
33  * of a digital signature algorithm. Digital signatures are used for
34  * authentication and integrity assurance of digital data.
35  *
36  * <p> The signature algorithm can be, among others, the NIST standard
37  * DSA, using DSA and SHA-1. The DSA algorithm using the
38  * SHA-1 message digest algorithm can be specified as <tt>SHA1withDSA</tt>.
39  * In the case of RSA, there are multiple choices for the message digest
40  * algorithm, so the signing algorithm could be specified as, for example,
41  * <tt>MD2withRSA</tt>, <tt>MD5withRSA</tt>, or <tt>SHA1withRSA</tt>.
42  * The algorithm name must be specified, as there is no default.
43  *
44  * <p>Like other algorithm-based classes in Java Security, Signature
45  * provides implementation-independent algorithms, whereby a caller
46  * (application code) requests a particular signature algorithm
47  * and is handed back a properly initialized Signature object. It is
48  * also possible, if desired, to request a particular algorithm from a
49  * particular provider. See the <code>getInstance </code> methods.
50  *
51  * <p>Thus, there are two ways to request a Signature algorithm object: by
52  * specifying either just an algorithm name, or both an algorithm name
53  * and a package provider. <ul>
54  *
55  * <li>If just an algorithm name is specified, the system will
56  * determine if there is an implementation of the algorithm requested
57  * available in the environment, and if there is more than one, if
58  * there is a preferred one.<p>
59  *
60  * <li>If both an algorithm name and a package provider are specified,
61  * the system will determine if there is an implementation of the
62  * algorithm in the package requested, and throw an exception if there
63  * is not.
64  *
65  * </ul>
66  *
67  * <p>A Signature object can be used to generate and verify digital
68  * signatures.
69  *
70  * <p>There are three phases to the use of a Signature object for
71  * either signing data or verifying a signature:<ol>
72  *
73  * <li>Initialization, with either
74  *
75  * <ul>
76  *
77  * <li>a public key, which initializes the signature for
78  * verification (see {@link #initVerify(PublicKey) initVerify}), or
79  *
80  * <li>a private key (and optionally a Secure Random Number Generator),
81  * which initializes the signature for signing
82  * (see {@link #initSign(PrivateKey)}
83  * and {@link #initSign(PrivateKey, SecureRandom)}).
84  *
85  * </ul><p>
86  *
87  * <li>Updating<p>
88  *
89  * <p>Depending on the type of initialization, this will update the
90  * bytes to be signed or verified. See the
91  * {@link #update(byte) update} methods.<p>
92  *
93  * <li>Signing or Verifying a signature on all updated bytes. See the
94  * {@link #sign() sign} methods and the {@link #verify(byte[]) verify}
95  * method.
96  *
97  * </ol>
98  *
99  * <p>Note that this class is abstract and extends from
100  * <code>SignatureSpi</code> for historical reasons.
101  * Application developers should only take notice of the methods defined in
102  * this <code>Signature</code> class; all the methods in
103  * the superclass are intended for cryptographic service providers who wish to
104  * supply their own implementations of digital signature algorithms.
105  *
106  * @author Benjamin Renaud
107  *
108  * @version 1.99, 05/18/04
109  */
110
111 public abstract class Signature extends SignatureSpi {
112
113     private static final Debug debug =
114             Debug.getInstance("jca", "Signature");
115     
116     /*
117      * The algorithm for this signature object.
118      * This value is used to map an OID to the particular algorithm.
119      * The mapping is done in AlgorithmObject.algOID(String algorithm)
120      */
121     private String algorithm;
122
123     // The provider
124 Provider provider;
125
126     /**
127      * Possible {@link #state} value, signifying that
128      * this signature object has not yet been initialized.
129      */
130     protected final static int UNINITIALIZED = 0;
131        
132     /**
133      * Possible {@link #state} value, signifying that
134      * this signature object has been initialized for signing.
135      */
136     protected final static int SIGN = 2;
137        
138     /**
139      * Possible {@link #state} value, signifying that
140      * this signature object has been initialized for verification.
141      */
142     protected final static int VERIFY = 3;
143
144     /**
145      * Current state of this signature object.
146      */
147     protected int state = UNINITIALIZED;
148
149     /**
150      * Creates a Signature object for the specified algorithm.
151      *
152      * @param algorithm the standard string name of the algorithm.
153      * See Appendix A in the <a HREF=
154      * "../../../guide/security/CryptoSpec.html#AppA">
155      * Java Cryptography Architecture API Specification &amp; Reference </a>
156      * for information about standard algorithm names.
157      */
158     protected Signature(String algorithm) {
159     this.algorithm = algorithm;
160     }
161     
162     // name of the special signature alg
163 private final static String RSA_SIGNATURE = "NONEwithRSA";
164
165     // name of the equivalent cipher alg
166 private final static String RSA_CIPHER = "RSA/ECB/PKCS1Padding";
167     
168     // all the services we need to lookup for compatibility with Cipher
169 private final static List<ServiceId> rsaIds = Arrays.asList(
170     new ServiceId[] {
171         new ServiceId("Signature", "NONEwithRSA"),
172         new ServiceId("Cipher", "RSA/ECB/PKCS1Padding"),
173         new ServiceId("Cipher", "RSA/ECB"),
174         new ServiceId("Cipher", "RSA//PKCS1Padding"),
175         new ServiceId("Cipher", "RSA"),
176     }
177     );
178
179     /**
180      * Generates a Signature object that implements the specified digest
181      * algorithm. If the default provider package
182      * provides an implementation of the requested digest algorithm,
183      * an instance of Signature containing that implementation is returned.
184      * If the algorithm is not available in the default
185      * package, other packages are searched.
186      *
187      * @param algorithm the standard name of the algorithm requested.
188      * See Appendix A in the <a HREF=
189      * "../../../guide/security/CryptoSpec.html#AppA">
190      * Java Cryptography Architecture API Specification &amp; Reference </a>
191      * for information about standard algorithm names.
192      *
193      * @return the new Signature object.
194      *
195      * @exception NoSuchAlgorithmException if the algorithm is
196      * not available in the environment.
197      */
198     public static Signature getInstance(String algorithm)
199         throws NoSuchAlgorithmException {
200     List list;
201     if (algorithm.equalsIgnoreCase(RSA_SIGNATURE)) {
202         list = GetInstance.getServices(rsaIds);
203     } else {
204         list = GetInstance.getServices("Signature", algorithm);
205     }
206     Iterator t = list.iterator();
207     if (t.hasNext() == false) {
208         throw new NoSuchAlgorithmException
209             (algorithm + " Signature not available");
210     }
211     // try services until we find an Spi or a working Signature subclass
212 NoSuchAlgorithmException failure;
213     do {
214         Service s = (Service)t.next();
215         if (isSpi(s)) {
216         return new Delegate(s, t, algorithm);
217         } else {
218         // must be a subclass of Signature, disable dynamic selection
219 try {
220             Instance instance =
221                 GetInstance.getInstance(s, SignatureSpi .class);
222             return getInstance(instance, algorithm);
223         } catch (NoSuchAlgorithmException e) {
224             failure = e;
225         }
226         }
227     } while (t.hasNext());
228     throw failure;
229     }
230     
231     private static Signature getInstance(Instance instance, String algorithm) {
232     Signature sig;
233     if (instance.impl instanceof Signature ) {
234         sig = (Signature )instance.impl;
235     } else {
236         SignatureSpi spi = (SignatureSpi )instance.impl;
237         sig = new Delegate(spi, algorithm);
238     }
239     sig.provider = instance.provider;
240     return sig;
241     }
242     
243     private final static Map <String ,Boolean > signatureInfo;
244     
245     static {
246         signatureInfo = new ConcurrentHashMap <String ,Boolean >();
247     Boolean TRUE = Boolean.TRUE;
248     // pre-initialize with values for our SignatureSpi implementations
249 signatureInfo.put("sun.security.provider.DSA$RawDSA", TRUE);
250     signatureInfo.put("sun.security.provider.DSA$SHA1withDSA", TRUE);
251     signatureInfo.put("sun.security.rsa.RSASignature$MD2withRSA", TRUE);
252     signatureInfo.put("sun.security.rsa.RSASignature$MD5withRSA", TRUE);
253     signatureInfo.put("sun.security.rsa.RSASignature$SHA1withRSA", TRUE);
254     signatureInfo.put("sun.security.rsa.RSASignature$SHA256withRSA", TRUE);
255     signatureInfo.put("sun.security.rsa.RSASignature$SHA384withRSA", TRUE);
256     signatureInfo.put("sun.security.rsa.RSASignature$SHA512withRSA", TRUE);
257     signatureInfo.put("com.sun.net.ssl.internal.ssl.RSASignature", TRUE);
258     signatureInfo.put("sun.security.pkcs11.P11Signature", TRUE);
259     }
260     
261     private static boolean isSpi(Service s) {
262     if (s.getType().equals("Cipher")) {
263         // must be a CipherSpi, which we can wrap with the CipherAdapter
264 return true;
265     }
266     String className = s.getClassName();
267     Boolean result = signatureInfo.get(className);
268     if (result == null) {
269         try {
270         Object instance = s.newInstance(null);
271         // Signature extends SignatureSpi
272 // so it is a "real" Spi if it is an
273 // instance of SignatureSpi but not Signature
274 boolean r = (instance instanceof SignatureSpi )
275                 && (instance instanceof Signature == false);
276         if ((debug != null) && (r == false)) {
277             debug.println("Not a SignatureSpi " + className);
278             debug.println("Delayed provider selection may not be "
279                 + "available for algorithm " + s.getAlgorithm());
280         }
281         result = Boolean.valueOf(r);
282         signatureInfo.put(className, result);
283         } catch (Exception e) {
284         // something is wrong, assume not an SPI
285 return false;
286         }
287     }
288     return result.booleanValue();
289     }
290
291     /**
292      * Generates a Signature object implementing the specified
293      * algorithm, as supplied from the specified provider, if such an
294      * algorithm is available from the provider.
295      *
296      * @param algorithm the name of the algorithm requested.
297      * See Appendix A in the <a HREF=
298      * "../../../guide/security/CryptoSpec.html#AppA">
299      * Java Cryptography Architecture API Specification &amp; Reference </a>
300      * for information about standard algorithm names.
301      *
302      * @param provider the name of the provider.
303      *
304      * @return the new Signature object.
305      *
306      * @exception NoSuchAlgorithmException if the algorithm is
307      * not available in the package supplied by the requested
308      * provider.
309      *
310      * @exception NoSuchProviderException if the provider is not
311      * available in the environment.
312      *
313      * @exception IllegalArgumentException if the provider name is null
314      * or empty.
315      *
316      * @see Provider
317      */
318     public static Signature getInstance(String algorithm, String provider)
319         throws NoSuchAlgorithmException , NoSuchProviderException {
320     if (algorithm.equalsIgnoreCase(RSA_SIGNATURE)) {
321         // exception compatibility with existing code
322 if ((provider == null) || (provider.length() == 0)) {
323         throw new IllegalArgumentException ("missing provider");
324         }
325         Provider p = Security.getProvider(provider);
326         if (p == null) {
327         throw new NoSuchProviderException
328             ("no such provider: " + provider);
329         }
330         return getInstanceRSA(p);
331     }
332     Instance instance = GetInstance.getInstance
333         ("Signature", SignatureSpi .class, algorithm, provider);
334     return getInstance(instance, algorithm);
335     }
336     
337     /**
338      * Generates a Signature object implementing the specified
339      * algorithm, as supplied from the specified provider, if such an
340      * algorithm is available from the provider. Note: the
341      * <code>provider</code> doesn't have to be registered.
342      *
343      * @param algorithm the name of the algorithm requested.
344      * See Appendix A in the <a HREF=
345      * "../../../guide/security/CryptoSpec.html#AppA">
346      * Java Cryptography Architecture API Specification &amp; Reference </a>
347      * for information about standard algorithm names.
348      *
349      * @param provider the provider.
350      *
351      * @return the new Signature object.
352      *
353      * @exception NoSuchAlgorithmException if the algorithm is
354      * not available in the package supplied by the requested
355      * provider.
356      *
357      * @exception IllegalArgumentException if the <code>provider</code> is
358      * null.
359      *
360      * @see Provider
361      *
362      * @since 1.4
363      */
364     public static Signature getInstance(String algorithm, Provider provider)
365         throws NoSuchAlgorithmException {
366     if (algorithm.equalsIgnoreCase(RSA_SIGNATURE)) {
367         // exception compatibility with existing code
368 if (provider == null) {
369         throw new IllegalArgumentException ("missing provider");
370         }
371         return getInstanceRSA(provider);
372     }
373     Instance instance = GetInstance.getInstance
374         ("Signature", SignatureSpi .class, algorithm, provider);
375     return getInstance(instance, algorithm);
376     }
377
378     // return an implementation for NONEwithRSA, which is a special case
379 // because of the Cipher.RSA/ECB/PKCS1Padding compatibility wrapper
380 private static Signature getInstanceRSA(Provider p)
381         throws NoSuchAlgorithmException {
382     // try Signature first
383 Service s = p.getService("Signature", RSA_SIGNATURE);
384     if (s != null) {
385         Instance instance = GetInstance.getInstance(s, SignatureSpi .class);
386         return getInstance(instance, RSA_SIGNATURE);
387     }
388     // check Cipher
389 try {
390         Cipher c = Cipher.getInstance(RSA_CIPHER, p);
391         return new Delegate(new CipherAdapter(c), RSA_SIGNATURE);
392     } catch (GeneralSecurityException e) {
393         // throw Signature style exception message to avoid confusion,
394 // but append Cipher exception as cause
395 throw new NoSuchAlgorithmException ("no such algorithm: "
396         + RSA_SIGNATURE + " for provider " + p.getName(), e);
397     }
398     }
399
400     /**
401      * Returns the provider of this signature object.
402      *
403      * @return the provider of this signature object
404      */
405     public final Provider getProvider() {
406     chooseFirstProvider();
407     return this.provider;
408     }
409     
410     void chooseFirstProvider() {
411     // empty, overridden in Delegate
412 }
413
414     /**
415      * Initializes this object for verification. If this method is called
416      * again with a different argument, it negates the effect
417      * of this call.
418      *
419      * @param publicKey the public key of the identity whose signature is
420      * going to be verified.
421      *
422      * @exception InvalidKeyException if the key is invalid.
423      */
424     public final void initVerify(PublicKey publicKey)
425         throws InvalidKeyException {
426     engineInitVerify(publicKey);
427     state = VERIFY;
428     }
429
430     /**
431      * Initializes this object for verification, using the public key from
432      * the given certificate.
433      * <p>If the certificate is of type X.509 and has a <i>key usage</i>
434      * extension field marked as critical, and the value of the <i>key usage</i>
435      * extension field implies that the public key in
436      * the certificate and its corresponding private key are not
437      * supposed to be used for digital signatures, an
438      * <code>InvalidKeyException</code> is thrown.
439      *
440      * @param certificate the certificate of the identity whose signature is
441      * going to be verified.
442      *
443      * @exception InvalidKeyException if the public key in the certificate
444      * is not encoded properly or does not include required parameter
445      * information or cannot be used for digital signature purposes.
446      */
447     public final void initVerify(Certificate certificate)
448         throws InvalidKeyException {
449     // If the certificate is of type X509Certificate,
450 // we should check whether it has a Key Usage
451 // extension marked as critical.
452 if (certificate instanceof java.security.cert.X509Certificate ) {
453         // Check whether the cert has a key usage extension
454 // marked as a critical extension.
455 // The OID for KeyUsage extension is 2.5.29.15.
456 X509Certificate cert = (X509Certificate )certificate;
457         Set critSet = cert.getCriticalExtensionOIDs();
458
459         if (critSet != null && !critSet.isEmpty()
460         && critSet.contains("2.5.29.15")) {
461         boolean[] keyUsageInfo = cert.getKeyUsage();
462         // keyUsageInfo[0] is for digitalSignature.
463 if ((keyUsageInfo != null) && (keyUsageInfo[0] == false))
464             throw new InvalidKeyException ("Wrong key usage");
465         }
466     }
467         
468     PublicKey publicKey = certificate.getPublicKey();
469     engineInitVerify(publicKey);
470     state = VERIFY;
471     }
472
473     /**
474      * Initialize this object for signing. If this method is called
475      * again with a different argument, it negates the effect
476      * of this call.
477      *
478      * @param privateKey the private key of the identity whose signature
479      * is going to be generated.
480      *
481      * @exception InvalidKeyException if the key is invalid.
482      */
483     public final void initSign(PrivateKey privateKey)
484         throws InvalidKeyException {
485     engineInitSign(privateKey);
486     state = SIGN;
487     }
488
489     /**
490      * Initialize this object for signing. If this method is called
491      * again with a different argument, it negates the effect
492      * of this call.
493      *
494      * @param privateKey the private key of the identity whose signature
495      * is going to be generated.
496      *
497      * @param random the source of randomness for this signature.
498      *
499      * @exception InvalidKeyException if the key is invalid.
500      */
501     public final void initSign(PrivateKey privateKey, SecureRandom random)
502         throws InvalidKeyException {
503     engineInitSign(privateKey, random);
504     state = SIGN;
505     }
506
507     /**
508      * Returns the signature bytes of all the data updated.
509      * The format of the signature depends on the underlying
510      * signature scheme.
511      *
512      * <p>A call to this method resets this signature object to the state
513      * it was in when previously initialized for signing via a
514      * call to <code>initSign(PrivateKey)</code>. That is, the object is
515      * reset and available to generate another signature from the same
516      * signer, if desired, via new calls to <code>update</code> and
517      * <code>sign</code>.
518      *
519      * @return the signature bytes of the signing operation's result.
520      *
521      * @exception SignatureException if this signature object is not
522      * initialized properly or if this signature algorithm is unable to
523      * process the input data provided.
524      */
525     public final byte[] sign() throws SignatureException {
526     if (state == SIGN) {
527         return engineSign();
528     }
529     throw new SignatureException ("object not initialized for " +
530                      "signing");
531     }
532
533     /**
534      * Finishes the signature operation and stores the resulting signature
535      * bytes in the provided buffer <code>outbuf</code>, starting at
536      * <code>offset</code>.
537      * The format of the signature depends on the underlying
538      * signature scheme.
539      *
540      * <p>This signature object is reset to its initial state (the state it
541      * was in after a call to one of the <code>initSign</code> methods) and
542      * can be reused to generate further signatures with the same private key.
543      *
544      * @param outbuf buffer for the signature result.
545      *
546      * @param offset offset into <code>outbuf</code> where the signature is
547      * stored.
548      *
549      * @param len number of bytes within <code>outbuf</code> allotted for the
550      * signature.
551      *
552      * @return the number of bytes placed into <code>outbuf</code>.
553      *
554      * @exception SignatureException if this signature object is not
555      * initialized properly, if this signature algorithm is unable to
556      * process the input data provided, or if <code>len</code> is less
557      * than the actual signature length.
558      *
559      * @since 1.2
560      */
561     public final int sign(byte[] outbuf, int offset, int len)
562     throws SignatureException {
563     if (outbuf == null) {
564         throw new IllegalArgumentException ("No output buffer given");
565     }
566     if (outbuf.length - offset < len) {
567         throw new IllegalArgumentException
568         ("Output buffer too small for specified offset and length");
569     }
570     if (state != SIGN) {
571         throw new SignatureException ("object not initialized for " +
572                      "signing");
573     }
574     return engineSign(outbuf, offset, len);
575     }
576
577     /**
578      * Verifies the passed-in signature.
579      *
580      * <p>A call to this method resets this signature object to the state
581      * it was in when previously initialized for verification via a
582      * call to <code>initVerify(PublicKey)</code>. That is, the object is
583      * reset and available to verify another signature from the identity
584      * whose public key was specified in the call to <code>initVerify</code>.
585      *
586      * @param signature the signature bytes to be verified.
587      *
588      * @return true if the signature was verified, false if not.
589      *
590      * @exception SignatureException if this signature object is not
591      * initialized properly, the passed-in signature is improperly
592      * encoded or of the wrong type, if this signature algorithm is unable to
593      * process the input data provided, etc.
594      */
595     public final boolean verify(byte[] signature) throws SignatureException {
596     if (state == VERIFY) {
597         return engineVerify(signature);
598     }
599     throw new SignatureException ("object not initialized for " +
600                      "verification");
601     }
602
603     /**
604      * Verifies the passed-in signature in the specified array
605      * of bytes, starting at the specified offset.
606      *
607      * <p>A call to this method resets this signature object to the state
608      * it was in when previously initialized for verification via a
609      * call to <code>initVerify(PublicKey)</code>. That is, the object is
610      * reset and available to verify another signature from the identity
611      * whose public key was specified in the call to <code>initVerify</code>.
612      *
613      *
614      * @param signature the signature bytes to be verified.
615      * @param offset the offset to start from in the array of bytes.
616      * @param length the number of bytes to use, starting at offset.
617      *
618      * @return true if the signature was verified, false if not.
619      *
620      * @exception SignatureException if this signature object is not
621      * initialized properly, the passed-in signature is improperly
622      * encoded or of the wrong type, if this signature algorithm is unable to
623      * process the input data provided, etc.
624      * @exception IllegalArgumentException if the <code>signature</code>
625      * byte array is null, or the <code>offset</code> or <code>length</code>
626      * is less than 0, or the sum of the <code>offset</code> and
627      * <code>length</code> is greater than the length of the
628      * <code>signature</code> byte array.
629      */
630     public final boolean verify(byte[] signature, int offset, int length)
631     throws SignatureException {
632     if (state == VERIFY) {
633         if ((signature == null) || (offset < 0) || (length < 0) ||
634         (offset + length > signature.length)) {
635         throw new IllegalArgumentException ("Bad arguments");
636         }
637
638         return engineVerify(signature, offset, length);
639     }
640     throw new SignatureException ("object not initialized for " +
641                      "verification");
642     }
643
644     /**
645      * Updates the data to be signed or verified by a byte.
646      *
647      * @param b the byte to use for the update.
648      *
649      * @exception SignatureException if this signature object is not
650      * initialized properly.
651      */
652     public final void update(byte b) throws SignatureException {
653     if (state == VERIFY || state == SIGN) {
654         engineUpdate(b);
655     } else {
656         throw new SignatureException ("object not initialized for "
657                      + "signature or verification");
658     }
659     }
660
661     /**
662      * Updates the data to be signed or verified, using the specified
663      * array of bytes.
664      *
665      * @param data the byte array to use for the update.
666      *
667      * @exception SignatureException if this signature object is not
668      * initialized properly.
669      */
670     public final void update(byte[] data) throws SignatureException {
671     update(data, 0, data.length);
672     }
673
674     /**
675      * Updates the data to be signed or verified, using the specified
676      * array of bytes, starting at the specified offset.
677      *
678      * @param data the array of bytes.
679      * @param off the offset to start from in the array of bytes.
680      * @param len the number of bytes to use, starting at offset.
681      *
682      * @exception SignatureException if this signature object is not
683      * initialized properly.
684      */
685     public final void update(byte[] data, int off, int len)
686         throws SignatureException {
687     if (state == SIGN || state == VERIFY) {
688         engineUpdate(data, off, len);
689     } else {
690         throw new SignatureException ("object not initialized for "
691                      + "signature or verification");
692     }
693     }
694
695     /**
696      * Updates the data to be signed or verified using the specified
697      * ByteBuffer. Processes the <code>data.remaining()</code> bytes
698      * starting at at <code>data.position()</code>.
699      * Upon return, the buffer's position will be equal to its limit;
700      * its limit will not have changed.
701      *
702      * @param data the ByteBuffer
703      *
704      * @exception SignatureException if this signature object is not
705      * initialized properly.
706      * @since 1.5
707      */
708     public final void update(ByteBuffer data) throws SignatureException {
709     if ((state != SIGN) && (state != VERIFY)) {
710         throw new SignatureException ("object not initialized for "
711                      + "signature or verification");
712     }
713     if (data == null) {
714         throw new NullPointerException ();
715     }
716     engineUpdate(data);
717     }
718
719     /**
720      * Returns the name of the algorithm for this signature object.
721      *
722      * @return the name of the algorithm for this signature object.
723      */
724     public final String getAlgorithm() {
725     return this.algorithm;
726     }
727
728     /**
729      * Returns a string representation of this signature object,
730      * providing information that includes the state of the object
731      * and the name of the algorithm used.
732      *
733      * @return a string representation of this signature object.
734      */
735     public String toString() {
736     String initState = "";
737     switch (state) {
738     case UNINITIALIZED:
739         initState = "<not initialized>";
740         break;
741     case VERIFY:
742         initState = "<initialized for verifying>";
743         break;
744     case SIGN:
745         initState = "<initialized for signing>";
746         break;
747     }
748     return "Signature object: " + getAlgorithm() + initState;
749     }
750
751     /**
752      * Sets the specified algorithm parameter to the specified value.
753      * This method supplies a general-purpose mechanism through
754      * which it is possible to set the various parameters of this object.
755      * A parameter may be any settable parameter for the algorithm, such as
756      * a parameter size, or a source of random bits for signature generation
757      * (if appropriate), or an indication of whether or not to perform
758      * a specific but optional computation. A uniform algorithm-specific
759      * naming scheme for each parameter is desirable but left unspecified
760      * at this time.
761      *
762      * @param param the string identifier of the parameter.
763      * @param value the parameter value.
764      *
765      * @exception InvalidParameterException if <code>param</code> is an
766      * invalid parameter for this signature algorithm engine,
767      * the parameter is already set
768      * and cannot be set again, a security exception occurs, and so on.
769      *
770      * @see #getParameter
771      *
772      * @deprecated Use
773      * {@link #setParameter(java.security.spec.AlgorithmParameterSpec)
774      * setParameter}.
775      */
776     @Deprecated
777     public final void setParameter(String param, Object value)
778         throws InvalidParameterException {
779     engineSetParameter(param, value);
780     }
781
782     /**
783      * Initializes this signature engine with the specified parameter set.
784      *
785      * @param params the parameters
786      *
787      * @exception InvalidAlgorithmParameterException if the given parameters
788      * are inappropriate for this signature engine
789      *
790      * @see #getParameters
791      */
792     public final void setParameter(AlgorithmParameterSpec params)
793         throws InvalidAlgorithmParameterException {
794     engineSetParameter(params);
795     }
796
797     /**
798      * Returns the parameters used with this signature object.
799      *
800      * <p>The returned parameters may be the same that were used to initialize
801      * this signature, or may contain a combination of default and randomly
802      * generated parameter values used by the underlying signature
803      * implementation if this signature requires algorithm parameters but
804      * was not initialized with any.
805      *
806      * @return the parameters used with this signature, or null if this
807      * signature does not use any parameters.
808      *
809      * @see #setParameter(AlgorithmParameterSpec)
810      */
811     public final AlgorithmParameters getParameters() {
812     return engineGetParameters();
813     }
814
815     /**
816      * Gets the value of the specified algorithm parameter. This method
817      * supplies a general-purpose mechanism through which it is possible to
818      * get the various parameters of this object. A parameter may be any
819      * settable parameter for the algorithm, such as a parameter size, or
820      * a source of random bits for signature generation (if appropriate),
821      * or an indication of whether or not to perform a specific but optional
822      * computation. A uniform algorithm-specific naming scheme for each
823      * parameter is desirable but left unspecified at this time.
824      *
825      * @param param the string name of the parameter.
826      *
827      * @return the object that represents the parameter value, or null if
828      * there is none.
829      *
830      * @exception InvalidParameterException if <code>param</code> is an invalid
831      * parameter for this engine, or another exception occurs while
832      * trying to get this parameter.
833      *
834      * @see #setParameter(String, Object)
835      *
836      * @deprecated
837      */
838     @Deprecated
839     public final Object getParameter(String param)
840         throws InvalidParameterException {
841     return engineGetParameter(param);
842     }
843
844     /**
845      * Returns a clone if the implementation is cloneable.
846      *
847      * @return a clone if the implementation is cloneable.
848      *
849      * @exception CloneNotSupportedException if this is called
850      * on an implementation that does not support <code>Cloneable</code>.
851      */
852     public Object clone() throws CloneNotSupportedException {
853     if (this instanceof Cloneable ) {
854         return super.clone();
855     } else {
856         throw new CloneNotSupportedException ();
857     }
858     }
859     
860     /*
861      * The following class allows providers to extend from SignatureSpi
862      * rather than from Signature. It represents a Signature with an
863      * encapsulated, provider-supplied SPI object (of type SignatureSpi).
864      * If the provider implementation is an instance of SignatureSpi, the
865      * getInstance() methods above return an instance of this class, with
866      * the SPI object encapsulated.
867      *
868      * Note: All SPI methods from the original Signature class have been
869      * moved up the hierarchy into a new class (SignatureSpi), which has
870      * been interposed in the hierarchy between the API (Signature)
871      * and its original parent (Object).
872      */
873
874     private static class Delegate extends Signature {
875
876     // The provider implementation (delegate)
877 // filled in once the provider is selected
878 private SignatureSpi sigSpi;
879     
880     // lock for mutex during provider selection
881 private final Object lock;
882
883     // next service to try in provider selection
884 // null once provider is selected
885 private Service firstService;
886     
887     // remaining services to try in provider selection
888 // null once provider is selected
889 private Iterator serviceIterator;
890     
891     // constructor
892 Delegate(SignatureSpi sigSpi, String algorithm) {
893         super(algorithm);
894         this.sigSpi = sigSpi;
895         this.lock = null; // no lock needed
896 }
897     
898     // used with delayed provider selection
899 Delegate(Service service, Iterator iterator, String algorithm) {
900         super(algorithm);
901         this.firstService = service;
902         this.serviceIterator = iterator;
903         this.lock = new Object ();
904     }
905     
906     /*
907      * Returns a clone if the delegate is cloneable.
908      *
909      * @return a clone if the delegate is cloneable.
910      *
911      * @exception CloneNotSupportedException if this is called on a
912      * delegate that does not support <code>