1 /* Signature.java --- Signature Class
2 Copyright (C) 1999, 2002, 2003 Free Software Foundation, Inc.
4 This file is part of GNU Classpath.
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING. If not, write to the
18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library. Thus, the terms and
23 conditions of the GNU General Public License cover the whole
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module. An independent module is a module which is not derived from
33 or based on this library. If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so. If you do not wish to do so, delete this
36 exception statement from your version. */
38 package java
.security
;
40 import java
.security
.cert
.Certificate
;
41 import java
.security
.cert
.X509Certificate
;
42 import java
.security
.spec
.AlgorithmParameterSpec
;
45 * <p>This <code>Signature</code> class is used to provide applications the
46 * functionality of a digital signature algorithm. Digital signatures are used
47 * for authentication and integrity assurance of digital data.</p>
49 * <p>The signature algorithm can be, among others, the NIST standard <i>DSS</i>,
50 * using <i>DSA</i> and <i>SHA-1</i>. The <i>DSA</i> algorithm using the
51 * <i>SHA-1</i> message digest algorithm can be specified as <code>SHA1withDSA
52 * </code>. In the case of <i>RSA</i>, there are multiple choices for the
53 * message digest algorithm, so the signing algorithm could be specified as, for
54 * example, <code>MD2withRSA</code>, <code>MD5withRSA</code>, or
55 * <code>SHA1withRSA</code>. The algorithm name must be specified, as there is
58 * <p>Like other algorithm-based classes in Java Security, <code>Signature</code>
59 * provides implementation-independent algorithms, whereby a caller (application
60 * code) requests a particular signature algorithm and is handed back a properly
61 * initialized <code>Signature</code> object. It is also possible, if desired,
62 * to request a particular algorithm from a particular provider. See the
63 * <code>getInstance()</code> methods.</p>
65 * <p>Thus, there are two ways to request a <code>Signature</code> algorithm
66 * object: by specifying either just an algorithm name, or both an algorithm
67 * name and a package provider.</p>
69 * <p>If just an algorithm name is specified, the system will determine if there
70 * is an implementation of the algorithm requested available in the environment,
71 * and if there is more than one, if there is a preferred one.</p>
73 * <p>If both an algorithm name and a package provider are specified, the system
74 * will determine if there is an implementation of the algorithm in the package
75 * requested, and throw an exception if there is not.</p>
77 * <p>A <code>Signature</code> object can be used to generate and verify digital
80 * <p>There are three phases to the use of a <code>Signature</code> object for
81 * either signing data or verifying a signature:</p>
84 * <li>Initialization, with either
86 * <li>a public key, which initializes the signature for verification
87 * (see <code>initVerify()</code>), or</li>
88 * <li>a private key (and optionally a Secure Random Number Generator),
89 * which initializes the signature for signing (see
90 * {@link #initSign(PrivateKey)} and {@link #initSign(PrivateKey, SecureRandom)}
94 * Depending on the type of initialization, this will update the bytes to
95 * be signed or verified. See the update methods.<br/></li>
96 * <li>Signing or Verifying a signature on all updated bytes. See the
97 * <code>sign()</code> methods and the <code>verify()</code> method.</li>
100 * <p>Note that this class is abstract and extends from {@link SignatureSpi} for
101 * historical reasons. Application developers should only take notice of the
102 * methods defined in this <code>Signature</code> class; all the methods in the
103 * superclass are intended for cryptographic service providers who wish to
104 * supply their own implementations of digital signature algorithms.
106 * @author Mark Benvenuto <ivymccough@worldnet.att.net>
108 public abstract class Signature
extends SignatureSpi
110 /** Service name for signatures. */
111 private static final String SIGNATURE
= "Signature";
114 * Possible <code>state</code> value, signifying that this signature object
115 * has not yet been initialized.
117 protected static final int UNINITIALIZED
= 0;
120 // ------------------------------------------------------------------------
123 * Possible <code>state</code> value, signifying that this signature object
124 * has been initialized for signing.
126 protected static final int SIGN
= 2;
129 * Possible <code>state</code> value, signifying that this signature object
130 * has been initialized for verification.
132 protected static final int VERIFY
= 3;
134 /** Current state of this signature object. */
135 protected int state
= UNINITIALIZED
;
137 private String algorithm
;
141 * Creates a <code>Signature</code> object for the specified algorithm.
143 * @param algorithm the standard string name of the algorithm. See Appendix A
144 * in the Java Cryptography Architecture API Specification & Reference for
145 * information about standard algorithm names.
147 protected Signature(String algorithm
)
149 this.algorithm
= algorithm
;
150 state
= UNINITIALIZED
;
154 * Generates a <code>Signature</code> object that implements the specified
155 * digest algorithm. If the default provider package provides an
156 * implementation of the requested digest algorithm, an instance of
157 * <code>Signature</code> containing that implementation is returned. If the
158 * algorithm is not available in the default package, other packages are
161 * @param algorithm the standard name of the algorithm requested. See Appendix
162 * A in the Java Cryptography Architecture API Specification & Reference
163 * for information about standard algorithm names.
164 * @return the new Signature object.
165 * @throws NoSuchAlgorithmException if the algorithm is not available in the
168 public static Signature
getInstance(String algorithm
)
169 throws NoSuchAlgorithmException
171 Provider
[] p
= Security
.getProviders();
172 for (int i
= 0; i
< p
.length
; i
++)
176 return getInstance(algorithm
, p
[i
]);
178 catch (NoSuchAlgorithmException ignored
) {}
181 throw new NoSuchAlgorithmException(algorithm
);
185 * Generates a <code>Signature</code> object implementing the specified
186 * algorithm, as supplied from the specified provider, if such an algorithm
187 * is available from the provider.
189 * @param algorithm the name of the algorithm requested. See Appendix A in
190 * the Java Cryptography Architecture API Specification & Reference for
191 * information about standard algorithm names.
192 * @param provider the name of the provider.
193 * @return the new <code>Signature</code> object.
194 * @throws NoSuchAlgorithmException if the algorithm is not available in the
195 * package supplied by the requested provider.
196 * @throws NoSuchProviderException if the provider is not available in the
198 * @throws IllegalArgumentException if the provider name is <code>null</code>
202 public static Signature
getInstance(String algorithm
, String provider
)
203 throws NoSuchAlgorithmException
, NoSuchProviderException
205 if (provider
== null || provider
.length() == 0)
206 throw new IllegalArgumentException("Illegal provider");
208 Provider p
= Security
.getProvider(provider
);
210 throw new NoSuchProviderException(provider
);
212 return getInstance(algorithm
, p
);
216 * Generates a <code>Signature</code> object implementing the specified
217 * algorithm, as supplied from the specified provider, if such an algorithm
218 * is available from the provider. Note: the provider doesn't have to be
221 * @param algorithm the name of the algorithm requested. See Appendix A in
222 * the Java Cryptography Architecture API Specification & Reference for
223 * information about standard algorithm names.
224 * @param provider the provider.
225 * @return the new <code>Signature</code> object.
226 * @throws NoSuchAlgorithmException if the <code>algorithm</code> is not
227 * available in the package supplied by the requested <code>provider</code>.
228 * @throws IllegalArgumentException if the <code>provider</code> is
233 public static Signature
getInstance(String algorithm
, Provider provider
)
234 throws NoSuchAlgorithmException
236 if (provider
== null)
237 throw new IllegalArgumentException("Illegal provider");
239 Signature result
= null;
240 Object o
= Engine
.getInstance(SIGNATURE
, algorithm
, provider
);
242 if (o
instanceof SignatureSpi
)
244 result
= new DummySignature((SignatureSpi
) o
, algorithm
);
246 else if (o
instanceof Signature
)
248 result
= (Signature
) o
;
249 result
.algorithm
= algorithm
;
253 throw new NoSuchAlgorithmException(algorithm
);
255 result
.provider
= provider
;
260 * Returns the provider of this signature object.
262 * @return the provider of this signature object.
264 public final Provider
getProvider()
270 * Initializes this object for verification. If this method is called again
271 * with a different argument, it negates the effect of this call.
273 * @param publicKey the public key of the identity whose signature is going
275 * @throws InvalidKeyException if the key is invalid.
277 public final void initVerify(PublicKey publicKey
) throws InvalidKeyException
280 engineInitVerify(publicKey
);
284 * <p>Initializes this object for verification, using the public key from the
285 * given certificate.</p>
287 * <p>If the certificate is of type <i>X.509</i> and has a <i>key usage</i>
288 * extension field marked as <i>critical</i>, and the value of the <i>key
289 * usage</i> extension field implies that the public key in the certificate
290 * and its corresponding private key are not supposed to be used for digital
291 * signatures, an {@link InvalidKeyException} is thrown.</p>
293 * @param certificate the certificate of the identity whose signature is
294 * going to be verified.
295 * @throws InvalidKeyException if the public key in the certificate is not
296 * encoded properly or does not include required parameter information or
297 * cannot be used for digital signature purposes.
299 public final void initVerify(Certificate certificate
)
300 throws InvalidKeyException
303 if (certificate
.getType().equals("X509"))
305 X509Certificate cert
= (X509Certificate
) certificate
;
306 boolean[]array
= cert
.getKeyUsage();
307 if (array
!= null && array
[0] == false)
308 throw new InvalidKeyException(
309 "KeyUsage of this Certificate indicates it cannot be used for digital signing");
311 this.initVerify(certificate
.getPublicKey());
315 * Initialize this object for signing. If this method is called again with a
316 * different argument, it negates the effect of this call.
318 * @param privateKey the private key of the identity whose signature is going
320 * @throws InvalidKeyException if the key is invalid.
322 public final void initSign(PrivateKey privateKey
) throws InvalidKeyException
325 engineInitSign(privateKey
);
329 * Initialize this object for signing. If this method is called again with a
330 * different argument, it negates the effect of this call.
332 * @param privateKey the private key of the identity whose signature is going
334 * @param random the source of randomness for this signature.
335 * @throws InvalidKeyException if the key is invalid.
337 public final void initSign(PrivateKey privateKey
, SecureRandom random
)
338 throws InvalidKeyException
341 engineInitSign(privateKey
, random
);
345 * <p>Returns the signature bytes of all the data updated. The format of the
346 * signature depends on the underlying signature scheme.</p>
348 * <p>A call to this method resets this signature object to the state it was
349 * in when previously initialized for signing via a call to
350 * <code>initSign(PrivateKey)</code>. That is, the object is reset and
351 * available to generate another signature from the same signer, if desired,
352 * via new calls to <code>update()</code> and <code>sign()</code>.</p>
354 * @return the signature bytes of the signing operation's result.
355 * @throws SignatureException if this signature object is not initialized
358 public final byte[] sign() throws SignatureException
362 state
= UNINITIALIZED
;
366 throw new SignatureException();
370 * <p>Finishes the signature operation and stores the resulting signature
371 * bytes in the provided buffer <code>outbuf</code>, starting at <code>offset
372 * </code>. The format of the signature depends on the underlying signature
375 * <p>This signature object is reset to its initial state (the state it was
376 * in after a call to one of the <code>initSign()</code> methods) and can be
377 * reused to generate further signatures with the same private key.</p>
379 * @param outbuf buffer for the signature result.
380 * @param offset offset into outbuf where the signature is stored.
381 * @param len number of bytes within outbuf allotted for the signature.
382 * @return the number of bytes placed into outbuf.
383 * @throws SignatureException if an error occurs or len is less than the
384 * actual signature length.
387 public final int sign(byte[] outbuf
, int offset
, int len
)
388 throws SignatureException
392 state
= UNINITIALIZED
;
393 return engineSign(outbuf
, offset
, len
);
396 throw new SignatureException();
400 * <p>Verifies the passed-in signature.</p>
402 * <p>A call to this method resets this signature object to the state it was
403 * in when previously initialized for verification via a call to
404 * <code>initVerify(PublicKey)</code>. That is, the object is reset and
405 * available to verify another signature from the identity whose public key
406 * was specified in the call to <code>initVerify()</code>.</p>
408 * @param signature the signature bytes to be verified.
409 * @return <code>true</code> if the signature was verified, <code>false</code>
411 * @throws SignatureException if this signature object is not initialized
412 * properly, or the passed-in signature is improperly encoded or of the wrong
415 public final boolean verify(byte[]signature
) throws SignatureException
419 state
= UNINITIALIZED
;
420 return engineVerify(signature
);
423 throw new SignatureException();
427 * <p>Verifies the passed-in <code>signature</code> in the specified array of
428 * bytes, starting at the specified <code>offset</code>.</p>
430 * <p>A call to this method resets this signature object to the state it was
431 * in when previously initialized for verification via a call to
432 * <code>initVerify(PublicKey)</code>. That is, the object is reset and
433 * available to verify another signature from the identity whose public key
434 * was specified in the call to <code>initVerify()</code>.</p>
436 * @param signature the signature bytes to be verified.
437 * @param offset the offset to start from in the array of bytes.
438 * @param length the number of bytes to use, starting at offset.
439 * @return <code>true</code> if the signature was verified, <code>false</code>
441 * @throws SignatureException if this signature object is not initialized
442 * properly, or the passed-in <code>signature</code> is improperly encoded or
443 * of the wrong type, etc.
444 * @throws IllegalArgumentException if the <code>signature</code> byte array
445 * is <code>null</code>, or the <code>offset</code> or <code>length</code> is
446 * less than <code>0</code>, or the sum of the <code>offset</code> and
447 * <code>length</code> is greater than the length of the <code>signature</code>
450 public final boolean verify(byte[] signature
, int offset
, int length
)
451 throws SignatureException
454 throw new SignatureException("illegal state");
456 if (signature
== null)
457 throw new IllegalArgumentException("signaure is null");
459 throw new IllegalArgumentException("offset is less than 0");
461 throw new IllegalArgumentException("length is less than 0");
462 if (offset
+ length
< signature
.length
)
463 throw new IllegalArgumentException("range is out of bounds");
465 state
= UNINITIALIZED
;
466 return engineVerify(signature
, offset
, length
);
470 * Updates the data to be signed or verified by a byte.
472 * @param b the byte to use for the update.
473 * @throws SignatureException if this signature object is not initialized
476 public final void update(byte b
) throws SignatureException
478 if (state
!= UNINITIALIZED
)
481 throw new SignatureException();
485 * Updates the data to be signed or verified, using the specified array of
488 * @param data the byte array to use for the update.
489 * @throws SignatureException if this signature object is not initialized
492 public final void update(byte[]data
) throws SignatureException
494 if (state
!= UNINITIALIZED
)
495 engineUpdate(data
, 0, data
.length
);
497 throw new SignatureException();
501 * Updates the data to be signed or verified, using the specified array of
502 * bytes, starting at the specified offset.
504 * @param data the array of bytes.
505 * @param off the offset to start from in the array of bytes.
506 * @param len the number of bytes to use, starting at offset.
507 * @throws SignatureException if this signature object is not initialized
510 public final void update(byte[]data
, int off
, int len
)
511 throws SignatureException
513 if (state
!= UNINITIALIZED
)
514 engineUpdate(data
, off
, len
);
516 throw new SignatureException();
520 * Returns the name of the algorithm for this signature object.
522 * @return the name of the algorithm for this signature object.
524 public final String
getAlgorithm()
530 * Returns a string representation of this signature object, providing
531 * information that includes the state of the object and the name of the
534 * @return a string representation of this signature object.
536 public String
toString()
538 return (algorithm
+ " Signature");
542 * Sets the specified algorithm parameter to the specified value. This method
543 * supplies a general-purpose mechanism through which it is possible to set
544 * the various parameters of this object. A parameter may be any settable
545 * parameter for the algorithm, such as a parameter size, or a source of
546 * random bits for signature generation (if appropriate), or an indication of
547 * whether or not to perform a specific but optional computation. A uniform
548 * algorithm-specific naming scheme for each parameter is desirable but left
549 * unspecified at this time.
551 * @param param the string identifier of the parameter.
552 * @param value the parameter value.
553 * @throws InvalidParameterException if param is an invalid parameter for this
554 * signature algorithm engine, the parameter is already set and cannot be set
555 * again, a security exception occurs, and so on.
556 * @see #getParameter(String)
557 * @deprecated Use setParameter(AlgorithmParameterSpec).
559 public final void setParameter(String param
, Object value
)
560 throws InvalidParameterException
562 engineSetParameter(param
, value
);
566 * Initializes this signature engine with the specified parameter set.
568 * @param params the parameters.
569 * @throws InvalidAlgorithmParameterException if the given parameters are
570 * inappropriate for this signature engine.
571 * @see #getParameters()
573 public final void setParameter(AlgorithmParameterSpec params
)
574 throws InvalidAlgorithmParameterException
576 engineSetParameter(params
);
580 * <p>Returns the parameters used with this signature object.</p>
582 * <p>The returned parameters may be the same that were used to initialize
583 * this signature, or may contain a combination of default and randomly
584 * generated parameter values used by the underlying signature implementation
585 * if this signature requires algorithm parameters but was not initialized
588 * @return the parameters used with this signature, or <code>null</code> if
589 * this signature does not use any parameters.
590 * @see #setParameter(AlgorithmParameterSpec)
592 public final AlgorithmParameters
getParameters()
594 return engineGetParameters();
598 * Gets the value of the specified algorithm parameter. This method supplies
599 * a general-purpose mechanism through which it is possible to get the various
600 * parameters of this object. A parameter may be any settable parameter for
601 * the algorithm, such as a parameter size, or a source of random bits for
602 * signature generation (if appropriate), or an indication of whether or not
603 * to perform a specific but optional computation. A uniform
604 * algorithm-specific naming scheme for each parameter is desirable but left
605 * unspecified at this time.
607 * @param param the string name of the parameter.
608 * @return the object that represents the parameter value, or null if there
610 * @throws InvalidParameterException if param is an invalid parameter for this
611 * engine, or another exception occurs while trying to get this parameter.
612 * @see #setParameter(String, Object)
615 public final Object
getParameter(String param
)
616 throws InvalidParameterException
618 return engineGetParameter(param
);
622 * Returns a clone if the implementation is cloneable.
624 * @return a clone if the implementation is cloneable.
625 * @throws CloneNotSupportedException if this is called on an implementation
626 * that does not support {@link Cloneable}.
628 public Object
clone() throws CloneNotSupportedException
630 throw new CloneNotSupportedException();