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:  * <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: }