Source for java.security.SignatureSpi

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