001: /*
002: * @(#)SignatureSpi.java 1.22 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.security;
029:
030: import java.security.spec.AlgorithmParameterSpec;
031: import java.util.*;
032: import java.io.*;
033:
034: /**
035: * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
036: * for the <code>Signature</code> class, which is used to provide the
037: * functionality of a digital signature algorithm. Digital signatures are used
038: * for authentication and integrity assurance of digital data.
039: *.
040: * <p> All the abstract methods in this class must be implemented by each
041: * cryptographic service provider who wishes to supply the implementation
042: * of a particular signature algorithm.
043: *
044: * @author Benjamin Renaud
045: *
046: * @version 1.15, 05/03/00
047: *
048: * @see Signature
049: */
050:
051: public abstract class SignatureSpi {
052:
053: /**
054: * Application-specified source of randomness.
055: */
056: protected SecureRandom appRandom = null;
057:
058: /**
059: * Initializes this signature object with the specified
060: * public key for verification operations.
061: *
062: * @param publicKey the public key of the identity whose signature is
063: * going to be verified.
064: *
065: * @exception InvalidKeyException if the key is improperly
066: * encoded, parameters are missing, and so on.
067: */
068: protected abstract void engineInitVerify(PublicKey publicKey)
069: throws InvalidKeyException;
070:
071: /**
072: * Initializes this signature object with the specified
073: * private key for signing operations.
074: *
075: * @param privateKey the private key of the identity whose signature
076: * will be generated.
077: *
078: * @exception InvalidKeyException if the key is improperly
079: * encoded, parameters are missing, and so on.
080: */
081: protected abstract void engineInitSign(PrivateKey privateKey)
082: throws InvalidKeyException;
083:
084: /**
085: * Initializes this signature object with the specified
086: * private key and source of randomness for signing operations.
087: *
088: * <p>This concrete method has been added to this previously-defined
089: * abstract class. (For backwards compatibility, it cannot be abstract.)
090: *
091: * @param privateKey the private key of the identity whose signature
092: * will be generated.
093: * @param random the source of randomness
094: *
095: * @exception InvalidKeyException if the key is improperly
096: * encoded, parameters are missing, and so on.
097: */
098: protected void engineInitSign(PrivateKey privateKey,
099: SecureRandom random) throws InvalidKeyException {
100: this .appRandom = random;
101: engineInitSign(privateKey);
102: }
103:
104: /**
105: * Updates the data to be signed or verified
106: * using the specified byte.
107: *
108: * @param b the byte to use for the update.
109: *
110: * @exception SignatureException if the engine is not initialized
111: * properly.
112: */
113: protected abstract void engineUpdate(byte b)
114: throws SignatureException;
115:
116: /**
117: * Updates the data to be signed or verified, using the
118: * specified array of bytes, starting at the specified offset.
119: *
120: * @param b the array of bytes
121: * @param off the offset to start from in the array of bytes
122: * @param len the number of bytes to use, starting at offset
123: *
124: * @exception SignatureException if the engine is not initialized
125: * properly
126: */
127: protected abstract void engineUpdate(byte[] b, int off, int len)
128: throws SignatureException;
129:
130: /**
131: * Returns the signature bytes of all the data
132: * updated so far.
133: * The format of the signature depends on the underlying
134: * signature scheme.
135: *
136: * @return the signature bytes of the signing operation's result.
137: *
138: * @exception SignatureException if the engine is not
139: * initialized properly.
140: */
141: protected abstract byte[] engineSign() throws SignatureException;
142:
143: /**
144: * Finishes this signature operation and stores the resulting signature
145: * bytes in the provided buffer <code>outbuf</code>, starting at
146: * <code>offset</code>.
147: * The format of the signature depends on the underlying
148: * signature scheme.
149: *
150: * <p>The signature implementation is reset to its initial state
151: * (the state it was in after a call to one of the
152: * <code>engineInitSign</code> methods)
153: * and can be reused to generate further signatures with the same private
154: * key.
155: *
156: * This method should be abstract, but we leave it concrete for
157: * binary compatibility. Knowledgeable providers should override this
158: * method.
159: *
160: * @param outbuf buffer for the signature result.
161: *
162: * @param offset offset into <code>outbuf</code> where the signature is
163: * stored.
164: *
165: * @param len number of bytes within <code>outbuf</code> allotted for the
166: * signature.
167: * Both this default implementation and the SUN provider do not
168: * return partial digests. If the value of this parameter is less
169: * than the actual signature length, this method will throw a
170: * SignatureException.
171: * This parameter is ignored if its value is greater than or equal to
172: * the actual signature length.
173: *
174: * @return the number of bytes placed into <code>outbuf</code>
175: *
176: * @exception SignatureException if an error occurs or <code>len</code>
177: * is less than the actual signature length.
178: *
179: * @since 1.2
180: */
181: protected int engineSign(byte[] outbuf, int offset, int len)
182: throws SignatureException {
183: byte[] sig = engineSign();
184: if (len < sig.length) {
185: throw new SignatureException(
186: "partial signatures not returned");
187: }
188: if (outbuf.length - offset < sig.length) {
189: throw new SignatureException(
190: "insufficient space in the output buffer to store the "
191: + "signature");
192: }
193: System.arraycopy(sig, 0, outbuf, offset, sig.length);
194: return sig.length;
195: }
196:
197: /**
198: * Verifies the passed-in signature.
199: *
200: * @param sigBytes the signature bytes to be verified.
201: *
202: * @return true if the signature was verified, false if not.
203: *
204: * @exception SignatureException if the engine is not initialized
205: * properly, or the passed-in signature is improperly encoded or
206: * of the wrong type, etc.
207: */
208: protected abstract boolean engineVerify(byte[] sigBytes)
209: throws SignatureException;
210:
211: /**
212: * Verifies the passed-in signature in the specified array
213: * of bytes, starting at the specified offset.
214: *
215: * <p> Note: Subclasses should overwrite the default implementation.
216: *
217: *
218: * @param sigBytes the signature bytes to be verified.
219: * @param offset the offset to start from in the array of bytes.
220: * @param length the number of bytes to use, starting at offset.
221: *
222: * @return true if the signature was verified, false if not.
223: *
224: * @exception SignatureException if the engine is not initialized
225: * properly, or the passed-in signature is improperly encoded or
226: * of the wrong type, etc.
227: */
228: protected boolean engineVerify(byte[] sigBytes, int offset,
229: int length) throws SignatureException {
230: byte[] sigBytesCopy = new byte[length];
231: System.arraycopy(sigBytes, offset, sigBytesCopy, 0, length);
232: return engineVerify(sigBytesCopy);
233: }
234:
235: /**
236: * Sets the specified algorithm parameter to the specified
237: * value. This method supplies a general-purpose mechanism through
238: * which it is possible to set the various parameters of this object.
239: * A parameter may be any settable parameter for the algorithm, such as
240: * a parameter size, or a source of random bits for signature generation
241: * (if appropriate), or an indication of whether or not to perform
242: * a specific but optional computation. A uniform algorithm-specific
243: * naming scheme for each parameter is desirable but left unspecified
244: * at this time.
245: *
246: * param param the string identifier of the parameter.
247: *
248: * param value the parameter value.
249: *
250: * exception InvalidParameterException if <code>param</code> is an
251: * invalid parameter for this signature algorithm engine,
252: * the parameter is already set
253: * and cannot be set again, a security exception occurs, and so on.
254: *
255: * deprecated Replaced by {link
256: * #engineSetParameter(java.security.spec.AlgorithmParameterSpec)
257: * engineSetParameter}.
258: *
259: protected abstract void engineSetParameter(String param, Object value)
260: throws InvalidParameterException;
261: */
262:
263: /**
264: * <p>This method is overridden by providers to initialize
265: * this signature engine with the specified parameter set.
266: *
267: * @param params the parameters
268: *
269: * @exception UnsupportedOperationException if this method is not
270: * overridden by a provider
271: *
272: * @exception InvalidAlgorithmParameterException if this method is
273: * overridden by a provider and the the given parameters
274: * are inappropriate for this signature engine
275: */
276: protected void engineSetParameter(AlgorithmParameterSpec params)
277: throws InvalidAlgorithmParameterException {
278: throw new UnsupportedOperationException();
279: }
280:
281: /**
282: * <p>This method is overridden by providers to return the
283: * parameters used with this signature engine, or null
284: * if this signature engine does not use any parameters.
285: *
286: * <p>The returned parameters may be the same that were used to initialize
287: * this signature engine, or may contain a combination of default and
288: * randomly generated parameter values used by the underlying signature
289: * implementation if this signature engine requires algorithm parameters
290: * but was not initialized with any.
291: *
292: * @return the parameters used with this signature engine, or null if this
293: * signature engine does not use any parameters
294: *
295: * @exception UnsupportedOperationException if this method is
296: * not overridden by a provider
297: */
298: protected AlgorithmParameters engineGetParameters() {
299: throw new UnsupportedOperationException();
300: }
301:
302: /**
303: * Gets the value of the specified algorithm parameter.
304: * This method supplies a general-purpose mechanism through which it
305: * is possible to get the various parameters of this object. A parameter
306: * may be any settable parameter for the algorithm, such as a parameter
307: * size, or a source of random bits for signature generation (if
308: * appropriate), or an indication of whether or not to perform a
309: * specific but optional computation. A uniform algorithm-specific
310: * naming scheme for each parameter is desirable but left unspecified
311: * at this time.
312: *
313: * param param the string name of the parameter.
314: *
315: * return the object that represents the parameter value, or null if
316: * there is none.
317: *
318: * exception InvalidParameterException if <code>param</code> is an
319: * invalid parameter for this engine, or another exception occurs while
320: * trying to get this parameter.
321: *
322: * deprecated
323: *
324: protected abstract Object engineGetParameter(String param)
325: throws InvalidParameterException;
326: */
327:
328: /**
329: * Returns a clone if the implementation is cloneable.
330: *
331: * @return a clone if the implementation is cloneable.
332: *
333: * @exception CloneNotSupportedException if this is called
334: * on an implementation that does not support <code>Cloneable</code>.
335: */
336: public Object clone() throws CloneNotSupportedException {
337: if (this instanceof Cloneable) {
338: return super .clone();
339: } else {
340: throw new CloneNotSupportedException();
341: }
342: }
343: }
|