libjava/java/security/SignatureSpi.java

   1 /* SignatureSpi.java --- Signature Service Provider Interface
   2    Copyright (C) 1999, 2003, Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   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)
   9 any later version.
  10
  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.
  15
  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
  19 02111-1307 USA.
  20
  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
  24 combination.
  25
  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. */
  37
  38 package java.security;
  39
  40 import java.security.spec.AlgorithmParameterSpec;
  41
  42 /**
  43  * <p>This class defines the <i>Service Provider Interface (SPI)</i> for the
  44  * {@link Signature} class, which is used to provide the functionality of a
  45  * digital signature algorithm. Digital signatures are used for authentication
  46  * and integrity assurance of digital data.</p>
  47  *
  48  * <p>All the abstract methods in this class must be implemented by each
  49  * cryptographic service provider who wishes to supply the implementation of a
  50  * particular signature algorithm.
  51  *
  52  * @author Mark Benvenuto (ivymccough@worldnet.att.net)
  53  * @since 1.2
  54  * @see Signature
  55  */
  56 public abstract class SignatureSpi
  57 {
  58   /** Application-specified source of randomness. */
  59   protected SecureRandom appRandom;
  60
  61   public SignatureSpi()
  62   {
  63     appRandom = null;
  64   }
  65
  66   /**
  67    * Initializes this signature object with the specified public key for
  68    * verification operations.
  69    *
  70    * @param publicKey the public key of the identity whose signature is going
  71    * to be verified.
  72    * @throws InvalidKeyException if the key is improperly encoded, parameters
  73    * are missing, and so on.
  74    */
  75   protected abstract void engineInitVerify(PublicKey publicKey)
  76     throws InvalidKeyException;
  77
  78   /**
  79    * Initializes this signature object with the specified private key for
  80    * signing operations.
  81    *
  82    * @param privateKey the private key of the identity whose signature will be
  83    * generated.
  84    * @throws InvalidKeyException if the key is improperly encoded, parameters
  85    * are missing, and so on.
  86    */
  87   protected abstract void engineInitSign(PrivateKey privateKey)
  88     throws InvalidKeyException;
  89
  90   /**
  91    * <p>Initializes this signature object with the specified private key and
  92    * source of randomness for signing operations.</p>
  93    *
  94    * <p>This concrete method has been added to this previously-defined abstract
  95    * class. (For backwards compatibility, it cannot be abstract.)</p>
  96    *
  97    * @param privateKey the private key of the identity whose signature will be
  98    * generated.
  99    * @param random the source of randomness.
 100    * @throws InvalidKeyException if the key is improperly encoded, parameters
 101    * are missing, and so on.
 102    * @since 1.2
 103    */
 104   protected void engineInitSign(PrivateKey privateKey, SecureRandom random)
 105     throws InvalidKeyException
 106   {
 107     appRandom = random;
 108     engineInitSign(privateKey);
 109   }
 110
 111   /**
 112    * Updates the data to be signed or verified using the specified byte.
 113    *
 114    * @param b the byte to use for the update.
 115    * @throws SignatureException if the engine is not initialized properly.
 116    */
 117   protected abstract void engineUpdate(byte b) throws SignatureException;
 118
 119   /**
 120    * Updates the data to be signed or verified, using the specified array of
 121    * bytes, starting at the specified offset.
 122    *
 123    * @param b the array of bytes.
 124    * @param off the offset to start from in the array of bytes.
 125    * @param len the number of bytes to use, starting at offset.
 126    * @throws SignatureException if the engine is not initialized properly.
 127    */
 128   protected abstract void engineUpdate(byte[] b, int off, int len)
 129     throws SignatureException;
 130
 131   /**
 132    * Returns the signature bytes of all the data updated so far. The format of
 133    * the signature depends on the underlying signature scheme.
 134    *
 135    * @return the signature bytes of the signing operation's result.
 136    * @throws SignatureException if the engine is not initialized properly.
 137    */
 138   protected abstract byte[] engineSign() throws SignatureException;
 139
 140   /**
 141    * <p>Finishes this signature operation and stores the resulting signature
 142    * bytes in the provided buffer <code>outbuf</code>, starting at <code>offset
 143    * </code>. The format of the signature depends on the underlying signature
 144    * scheme.</p>
 145    *
 146    * <p>The signature implementation is reset to its initial state (the state it
 147    * was in after a call to one of the <code>engineInitSign()</code> methods)
 148    * and can be reused to generate further signatures with the same private key.
 149    * This method should be abstract, but we leave it concrete for binary
 150    * compatibility. Knowledgeable providers should override this method.</p>
 151    *
 152    * @param outbuf buffer for the signature result.
 153    * @param offset offset into outbuf where the signature is stored.
 154    * @param len number of bytes within outbuf allotted for the signature. Both
 155    * this default implementation and the <b>GNU</b> provider do not return
 156    * partial digests. If the value of this parameter is less than the actual
 157    * signature length, this method will throw a {@link SignatureException}. This
 158    * parameter is ignored if its value is greater than or equal to the actual
 159    * signature length.
 160    * @return the number of bytes placed into <code>outbuf</code>.
 161    * @throws SignatureException if an error occurs or len is less than the
 162    * actual signature length.
 163    * @since 1.2
 164    */
 165   protected int engineSign(byte[] outbuf, int offset, int len)
 166     throws SignatureException
 167   {
 168     byte[] tmp = engineSign();
 169     if (tmp.length > len)
 170       throw new SignatureException("Invalid Length");
 171
 172     System.arraycopy(outbuf, offset, tmp, 0, tmp.length);
 173     return tmp.length;
 174   }
 175
 176   /**
 177    * Verifies the passed-in signature.
 178    *
 179    * @param sigBytes the signature bytes to be verified.
 180    * @return <code>true</code> if the signature was verified, <code>false</code>
 181    * if not.
 182    * @throws SignatureException if the engine is not initialized properly, or
 183    * the passed-in signature is improperly encoded or of the wrong type, etc.
 184    */
 185   protected abstract boolean engineVerify(byte[] sigBytes)
 186     throws SignatureException;
 187
 188   /**
 189    * <p>Verifies the passed-in <code>signature</code> in the specified array of
 190    * bytes, starting at the specified <code>offset</code>.</p>
 191    *
 192    * <p>Note: Subclasses should overwrite the default implementation.</p>
 193    *
 194    * @param sigBytes the signature bytes to be verified.
 195    * @param offset the offset to start from in the array of bytes.
 196    * @param length the number of bytes to use, starting at offset.
 197    * @return <code>true</code> if the signature was verified, <code>false</code>
 198    * if not.
 199    * @throws SignatureException if the engine is not initialized properly, or
 200    * the passed-in <code>signature</code> is improperly encoded or of the wrong
 201    * type, etc.
 202    */
 203   protected boolean engineVerify(byte[] sigBytes, int offset, int length)
 204     throws SignatureException
 205   {
 206     byte[] tmp = new byte[length];
 207     System.arraycopy(sigBytes, offset, tmp, 0, length);
 208     return engineVerify(tmp);
 209   }
 210
 211   /**
 212    * Sets the specified algorithm parameter to the specified value. This method
 213    * supplies a general-purpose mechanism through which it is possible to set
 214    * the various parameters of this object. A parameter may be any settable
 215    * parameter for the algorithm, such as a parameter size, or a source of
 216    * random bits for signature generation (if appropriate), or an indication of
 217    * whether or not to perform a specific but optional computation. A uniform
 218    * algorithm-specific naming scheme for each parameter is desirable but left
 219    * unspecified at this time.
 220    *
 221    * @param param the string identifier of the parameter.
 222    * @param value the parameter value.
 223    * @throws InvalidParameterException if <code>param</code> is an invalid
 224    * parameter for this signature algorithm engine, the parameter is already set
 225    * and cannot be set again, a security exception occurs, and so on.
 226    * @deprecated Replaced by engineSetParameter(AlgorithmParameterSpec).
 227    */
 228   protected abstract void engineSetParameter(String param, Object value)
 229     throws InvalidParameterException;
 230
 231   /**
 232    * This method is overridden by providers to initialize this signature engine
 233    * with the specified parameter set.
 234    *
 235    * @param params the parameters.
 236    * @throws UnsupportedOperationException if this method is not overridden by
 237    * a provider.
 238    * @throws InvalidAlgorithmParameterException if this method is overridden by
 239    * a provider and the the given parameters are inappropriate for this
 240    * signature engine.
 241    */
 242   protected void engineSetParameter(AlgorithmParameterSpec params)
 243     throws InvalidAlgorithmParameterException
 244   {
 245     throw new UnsupportedOperationException();
 246   }
 247
 248   /**
 249    * <p>This method is overridden by providers to return the parameters used
 250    * with this signature engine, or <code>null</code> if this signature engine
 251    * does not use any parameters.</p>
 252    *
 253    * <p>The returned parameters may be the same that were used to initialize
 254    * this signature engine, or may contain a combination of default and randomly
 255    * generated parameter values used by the underlying signature implementation
 256    * if this signature engine requires algorithm parameters but was not
 257    * initialized with any.</p>
 258    *
 259    * @return the parameters used with this signature engine, or <code>null</code>
 260    * if this signature engine does not use any parameters.
 261    * @throws UnsupportedOperationException if this method is not overridden by
 262    * a provider.
 263    */
 264   protected AlgorithmParameters engineGetParameters()
 265   {
 266     throw new UnsupportedOperationException();
 267   }
 268
 269   /**
 270    * Gets the value of the specified algorithm parameter. This method supplies
 271    * a general-purpose mechanism through which it is possible to get the various
 272    * parameters of this object. A parameter may be any settable parameter for
 273    * the algorithm, such as a parameter size, or a source of random bits for
 274    * signature generation (if appropriate), or an indication of whether or not
 275    * to perform a specific but optional computation. A uniform algorithm-specific
 276    * naming scheme for each parameter is desirable but left unspecified at this
 277    * time.
 278    *
 279    * @param param the string name of the parameter.
 280    * @return the object that represents the parameter value, or <code>null</code>
 281    * if there is none.
 282    * @throws InvalidParameterException if <code>param</code> is an invalid
 283    * parameter for this engine, or another exception occurs while trying to get
 284    * this parameter.
 285    * @deprecated
 286    */
 287   protected abstract Object engineGetParameter(String param)
 288     throws InvalidParameterException;
 289
 290   /**
 291    * Returns a clone if the implementation is cloneable.
 292    *
 293    * @return a clone if the implementation is cloneable.
 294    * @throws CloneNotSupportedException if this is called on an implementation
 295    * that does not support {@link Cloneable}.
 296    * @see Cloneable
 297    */
 298   public Object clone() throws CloneNotSupportedException
 299   {
 300     return super.clone();
 301   }
 302 }