libjava/classpath/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., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 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.nio.ByteBuffer;
  41 import java.security.spec.AlgorithmParameterSpec;
  42
  43 /**
  44  * <code>SignatureSpi</code> defines the Service Provider Interface (SPI) for
  45  * the {@link Signature} class. The signature class provides an interface to a
  46  * digital signature algorithm. Digital signatures are used for authentication
  47  * and integrity of data.
  48  *
  49  * @author Mark Benvenuto (ivymccough@worldnet.att.net)
  50  * @since 1.2
  51  * @see Signature
  52  */
  53 public abstract class SignatureSpi
  54 {
  55   /** Source of randomness. */
  56   protected SecureRandom appRandom;
  57
  58   /**
  59    * Creates a new instance of <code>SignatureSpi</code>.
  60    */
  61   public SignatureSpi()
  62   {
  63     appRandom = null;
  64   }
  65
  66   /**
  67    * Initializes this instance with the public key for verification purposes.
  68    *
  69    * @param publicKey
  70    *          the public key to verify with.
  71    * @throws InvalidKeyException
  72    *           if the key is invalid.
  73    */
  74   protected abstract void engineInitVerify(PublicKey publicKey)
  75     throws InvalidKeyException;
  76
  77   /**
  78    * Initializes this instance with the private key for signing purposes.
  79    *
  80    * @param privateKey
  81    *          the private key to sign with.
  82    * @throws InvalidKeyException
  83    *           if the key is invalid.
  84    */
  85   protected abstract void engineInitSign(PrivateKey privateKey)
  86     throws InvalidKeyException;
  87
  88   /**
  89    * Initializes this instance with the private key and source of randomness for
  90    * signing purposes.
  91    *
  92    * <p>This method cannot be abstract for backward compatibility reasons.</p>
  93    *
  94    * @param privateKey
  95    *          the private key to sign with.
  96    * @param random
  97    *          the {@link SecureRandom} to use.
  98    * @throws InvalidKeyException
  99    *           if the key is invalid.
 100    * @since 1.2
 101    */
 102   protected void engineInitSign(PrivateKey privateKey, SecureRandom random)
 103     throws InvalidKeyException
 104   {
 105     appRandom = random;
 106     engineInitSign(privateKey);
 107   }
 108
 109   /**
 110    * Updates the data to be signed or verified with the specified byte.
 111    *
 112    * @param b
 113    *          byte to update with.
 114    * @throws SignatureException
 115    *           if the engine is not properly initialized.
 116    */
 117   protected abstract void engineUpdate(byte b) throws SignatureException;
 118
 119   /**
 120    * Updates the data to be signed or verified with the specified bytes.
 121    *
 122    * @param b
 123    *          the array of bytes to use.
 124    * @param off
 125    *          the offset to start at in the array.
 126    * @param len
 127    *          the number of the bytes to use from the array.
 128    * @throws SignatureException
 129    *           if the engine is not properly initialized.
 130    */
 131   protected abstract void engineUpdate(byte[] b, int off, int len)
 132     throws SignatureException;
 133
 134   /**
 135    * Update this signature with the {@link java.nio.Buffer#remaining()}
 136    * bytes of the given buffer.
 137    *
 138    * @param input The input buffer.
 139    * @throws IllegalStateException if the engine is not properly initialized.
 140    */
 141   protected void engineUpdate(ByteBuffer input)
 142   {
 143     byte[] buf = new byte[4096];
 144     while (input.hasRemaining())
 145       {
 146         int l = Math.min(input.remaining(), buf.length);
 147         input.get(buf, 0, l);
 148         try
 149           {
 150             engineUpdate(buf, 0, l);
 151           }
 152         catch (SignatureException se)
 153           {
 154             throw new IllegalStateException(se);
 155           }
 156       }
 157   }
 158
 159   /**
 160    * Returns the signature bytes of all the data fed to this instance. The
 161    * format of the output depends on the underlying signature algorithm.
 162    *
 163    * @return the signature bytes.
 164    * @throws SignatureException
 165    *           if the engine is not properly initialized.
 166    */
 167   protected abstract byte[] engineSign() throws SignatureException;
 168
 169   /**
 170    * Generates signature bytes of all the data fed to this instance and stores
 171    * the result in the designated array. The format of the output depends on
 172    * the underlying signature algorithm.
 173    *
 174    * <p>This method cannot be abstract for backward compatibility reasons.
 175    * After calling this method, the signature is reset to its initial state and
 176    * can be used to generate additional signatures.</p>
 177    *
 178    * <p><b>IMPLEMENTATION NOTE:</b>: Neither this method nor the GNU provider
 179    * will return partial digests. If <code>len</code> is less than the
 180    * signature length, this method will throw a {@link SignatureException}. If
 181    * it is greater than or equal then it is ignored.</p>
 182    *
 183    * @param outbuf
 184    *          the array of bytes to store the result in.
 185    * @param offset
 186    *          the offset to start at in the array.
 187    * @param len
 188    *          the number of the bytes to use in the array.
 189    * @return the real number of bytes used.
 190    * @throws SignatureException
 191    *           if the engine is not properly initialized.
 192    * @since 1.2
 193    */
 194   protected int engineSign(byte[] outbuf, int offset, int len)
 195     throws SignatureException
 196   {
 197     byte[] tmp = engineSign();
 198     if (tmp.length > len)
 199       throw new SignatureException("Invalid Length");
 200
 201     System.arraycopy(outbuf, offset, tmp, 0, tmp.length);
 202     return tmp.length;
 203   }
 204
 205   /**
 206    * Verifies a designated signature.
 207    *
 208    * @param sigBytes
 209    *          the signature bytes to verify.
 210    * @return <code>true</code> if verified, <code>false</code> otherwise.
 211    * @throws SignatureException
 212    *           if the engine is not properly initialized or if it is the wrong
 213    *           signature.
 214    */
 215   protected abstract boolean engineVerify(byte[] sigBytes)
 216     throws SignatureException;
 217
 218   /**
 219    * Convenience method which calls the method with the same name and one
 220    * argument after copying the designated bytes into a temporary byte array.
 221    * Subclasses may override this method for performance reasons.
 222    *
 223    * @param sigBytes
 224    *          the array of bytes to use.
 225    * @param offset
 226    *          the offset to start from in the array of bytes.
 227    * @param length
 228    *          the number of bytes to use, starting at offset.
 229    * @return <code>true</code> if verified, <code>false</code> otherwise.
 230    * @throws SignatureException
 231    *           if the engine is not properly initialized.
 232    */
 233   protected boolean engineVerify(byte[] sigBytes, int offset, int length)
 234     throws SignatureException
 235   {
 236     byte[] tmp = new byte[length];
 237     System.arraycopy(sigBytes, offset, tmp, 0, length);
 238     return engineVerify(tmp);
 239   }
 240
 241   /**
 242    * Sets the specified algorithm parameter to the specified value.
 243    *
 244    * @param param
 245    *          the parameter name.
 246    * @param value
 247    *          the parameter value.
 248    * @throws InvalidParameterException
 249    *           if the parameter invalid, the parameter is already set and
 250    *           cannot be changed, a security exception occured, etc.
 251    * @deprecated use the other setParameter.
 252    */
 253   protected abstract void engineSetParameter(String param, Object value)
 254     throws InvalidParameterException;
 255
 256   /**
 257    * Sets the signature engine with the specified {@link AlgorithmParameterSpec}.
 258    *
 259    * <p>This method cannot be abstract for backward compatibility reasons. By
 260    * default it always throws {@link UnsupportedOperationException} unless
 261    * overridden.</p>
 262    *
 263    * @param params
 264    *          the parameters.
 265    * @throws InvalidParameterException
 266    *           if the parameter is invalid, the parameter is already set and
 267    *           cannot be changed, a security exception occured, etc.
 268    */
 269   protected void engineSetParameter(AlgorithmParameterSpec params)
 270     throws InvalidAlgorithmParameterException
 271   {
 272     throw new UnsupportedOperationException();
 273   }
 274
 275   /**
 276    * The default implementaion of this method always throws a
 277    * {@link UnsupportedOperationException}. It MUST be overridden by concrete
 278    * implementations to return the appropriate {@link AlgorithmParameters} for
 279    * this signature engine (or <code>null</code> when that engine does not use
 280    * any parameters.
 281    *
 282    * @return the parameters used with this signature engine, or
 283    *         <code>null</code> if it does not use any parameters.
 284    * @throws UnsupportedOperationException
 285    *           always.
 286    */
 287   protected AlgorithmParameters engineGetParameters()
 288   {
 289     throw new UnsupportedOperationException();
 290   }
 291
 292   /**
 293    * Returns the value for the specified algorithm parameter.
 294    *
 295    * @param param
 296    *          the parameter name.
 297    * @return the parameter value.
 298    * @throws InvalidParameterException
 299    *           if the parameter is invalid.
 300    * @deprecated use the other getParameter
 301    */
 302   protected abstract Object engineGetParameter(String param)
 303     throws InvalidParameterException;
 304
 305   /**
 306    * Returns a clone of this instance.
 307    *
 308    * @return a clone of this instance.
 309    * @throws CloneNotSupportedException
 310    *           if the implementation does not support cloning.
 311    */
 312   public Object clone() throws CloneNotSupportedException
 313   {
 314     return super.clone();
 315   }
 316 }