001/* SignatureSpi.java --- Signature Service Provider Interface
002   Copyright (C) 1999, 2003, Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038package java.security;
039
040import java.nio.ByteBuffer;
041import java.security.spec.AlgorithmParameterSpec;
042
043/**
044 * <code>SignatureSpi</code> defines the Service Provider Interface (SPI) for
045 * the {@link Signature} class. The signature class provides an interface to a
046 * digital signature algorithm. Digital signatures are used for authentication
047 * and integrity of data.
048 *
049 * @author Mark Benvenuto (ivymccough@worldnet.att.net)
050 * @since 1.2
051 * @see Signature
052 */
053public abstract class SignatureSpi
054{
055  /** Source of randomness. */
056  protected SecureRandom appRandom;
057
058  /**
059   * Creates a new instance of <code>SignatureSpi</code>.
060   */
061  public SignatureSpi()
062  {
063    appRandom = null;
064  }
065
066  /**
067   * Initializes this instance with the public key for verification purposes.
068   *
069   * @param publicKey
070   *          the public key to verify with.
071   * @throws InvalidKeyException
072   *           if the key is invalid.
073   */
074  protected abstract void engineInitVerify(PublicKey publicKey)
075    throws InvalidKeyException;
076
077  /**
078   * Initializes this instance with the private key for signing purposes.
079   *
080   * @param privateKey
081   *          the private key to sign with.
082   * @throws InvalidKeyException
083   *           if the key is invalid.
084   */
085  protected abstract void engineInitSign(PrivateKey privateKey)
086    throws InvalidKeyException;
087
088  /**
089   * Initializes this instance with the private key and source of randomness for
090   * signing purposes.
091   *
092   * <p>This method cannot be abstract for backward compatibility reasons.</p>
093   *
094   * @param privateKey
095   *          the private key to sign with.
096   * @param random
097   *          the {@link SecureRandom} to use.
098   * @throws InvalidKeyException
099   *           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}