001: /*
002: *
003: *
004: * Copyright 1990-2007 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: package com.sun.midp.crypto;
028:
029: /**
030: * This <code>Signature</code> class is used to provide applications
031: * the functionality
032: * of a digital signature algorithm. Digital signatures are used for
033: * authentication and integrity assurance of digital data.
034: *
035: * <p> The signature algorithm can be, among others, the NIST standard
036: * DSA, using DSA and SHA-1. The DSA algorithm using the
037: * SHA-1 message digest algorithm can be specified as <tt>SHA1withDSA</tt>.
038: * In the case of RSA, there are multiple choices for the message digest
039: * algorithm, so the signing algorithm could be specified as, for example,
040: * <tt>MD2withRSA</tt>, <tt>MD5withRSA</tt>, or <tt>SHA1withRSA</tt>.
041: * The algorithm name must be specified, as there is no default.
042: *
043: * When an algorithm name is specified, the system will
044: * determine if there is an implementation of the algorithm requested
045: * available in the environment, and if there is more than one, if
046: * there is a preferred one.<p>
047: *
048: * <p>A <code>Signature</code> object can be used to generate and
049: * verify digital signatures.
050: *
051: * <p>There are three phases to the use of a <code>Signature</code>
052: * object for verifying a signature:<ol>
053: *
054: * <li>Initialization, with a public key, which initializes the
055: * signature for verification
056: * </li>
057: *
058: * <li>Updating
059: *
060: * <p>Depending on the type of initialization, this will update the
061: * bytes to be verified. </li>
062: * <li> Verifying a signature on all updated bytes. </li>
063: *
064: * </ol>
065: */
066: public abstract class Signature {
067:
068: /**
069: * Protected constructor.
070: */
071: protected Signature() {
072: }
073:
074: /**
075: * Generates a <code>Signature</code> object that implements
076: * the specified digest
077: * algorithm.
078: *
079: * @param algorithm the standard name of the algorithm requested.
080: * See Appendix A in the
081: * Java Cryptography Architecture API Specification & Reference
082: * for information about standard algorithm names.
083: *
084: * @return the new <code>Signature</code> object.
085: *
086: * @exception NoSuchAlgorithmException if the algorithm is
087: * not available in the environment.
088: */
089: public static Signature getInstance(String algorithm)
090: throws NoSuchAlgorithmException {
091:
092: if (algorithm == null) {
093: throw new NoSuchAlgorithmException();
094: }
095:
096: algorithm = algorithm.toUpperCase();
097:
098: try {
099: Class sigClass;
100:
101: if (algorithm.equals("MD5WITHRSA")) {
102: sigClass = Class
103: .forName("com.sun.midp.crypto.RsaMd5Sig");
104: } else if (algorithm.equals("SHA1WITHRSA")) {
105: sigClass = Class
106: .forName("com.sun.midp.crypto.RsaShaSig");
107: } else {
108: throw new NoSuchAlgorithmException();
109: }
110:
111: return (Signature) sigClass.newInstance();
112: } catch (Throwable e) {
113: throw new NoSuchAlgorithmException("Provider not found");
114: }
115: }
116:
117: /**
118: * Gets the signature algorithm.
119: *
120: * @return the algorithm code defined above
121: */
122: public abstract String getAlgorithm();
123:
124: /**
125: * Gets the byte length of the signature data.
126: *
127: * @return the byte length of signature data
128: */
129: public abstract int getLength();
130:
131: /**
132: * Initializes the <CODE>Signature</CODE> object with the appropriate
133: * <CODE>Key</CODE> for signature verification.
134: * <P />
135: * @param theKey the key object to use for verification
136: *
137: * @exception InvalidKeyException if the key type is inconsistent
138: * with the mode or signature implementation.
139: */
140: public abstract void initVerify(PublicKey theKey)
141: throws InvalidKeyException;
142:
143: /**
144: * Initializes the <CODE>Signature</CODE> object with the appropriate
145: * <CODE>Key</CODE> for signature creation.
146: * <P />
147: * @param theKey the key object to use for signing
148: *
149: * @exception InvalidKeyException if the key type is inconsistent
150: * with the mode or signature implementation.
151: */
152: public abstract void initSign(PrivateKey theKey)
153: throws InvalidKeyException;
154:
155: /**
156: * Accumulates a signature of the input data. When this method is used,
157: * temporary storage of intermediate results is required. This method
158: * should only be used if all the input data required for the signature
159: * is not available in one byte array. The sign() or verify() method is
160: * recommended whenever possible.
161: * <P />
162: * @param inBuf the input buffer of data to be signed
163: * @param inOff starting offset within the input buffer for data to
164: * be signed
165: * @param inLen the byte length of data to be signed
166: *
167: * @exception SignatureException if this signature object is not
168: * initialized properly.
169: */
170: public abstract void update(byte[] inBuf, int inOff, int inLen)
171: throws SignatureException;
172:
173: /**
174: * Generates the signature of all/last input data. A call to this
175: * method also resets this signature object to the state it was in
176: * when previously initialized via a call to initSign() and the
177: * message to sign given via a call to update().
178: * That is, the object is reset and available to sign another message.
179: * <P />
180: * @param outbuf the output buffer to store signature data
181: *
182: * @return number of bytes of signature output in sigBuf
183: *
184: * @exception SignatureException if this signature object is not
185: * initialized properly, or outbuf.length is less than the actual signature
186: */
187: public int sign(byte[] outbuf) throws SignatureException {
188: return sign(outbuf, 0, outbuf.length);
189: }
190:
191: /**
192: * Generates the signature of all/last input data. A call to this
193: * method also resets this signature object to the state it was in
194: * when previously initialized via a call to initSign() and the
195: * message to sign given via a call to update().
196: * That is, the object is reset and available to sign another message.
197: * <P />
198: * @param outbuf the output buffer to store signature data
199: * @param offset starting offset within the output buffer at which
200: * to begin signature data
201: * @param len max byte to write to the buffer
202: *
203: * @return number of bytes of signature output in sigBuf
204: *
205: * @exception SignatureException if this signature object is not
206: * initialized properly, or len is less than the actual signature
207: */
208: public abstract int sign(byte[] outbuf, int offset, int len)
209: throws SignatureException;
210:
211: /**
212: * Verifies the passed-in signature.
213: *
214: * <p>A call to this method resets this signature object to the state
215: * it was in when previously initialized for verification via a
216: * call to <code>initVerify(PublicKey)</code>. That is, the object is
217: * reset and available to verify another signature from the identity
218: * whose public key was specified in the call to <code>initVerify</code>.
219: *
220: * @param signature the signature bytes to be verified.
221: *
222: * @return true if the signature was verified, false if not.
223: *
224: * @exception SignatureException if this signature object is not
225: * initialized properly, or the passed-in signature is improperly
226: * encoded or of the wrong type, etc.
227: */
228: public boolean verify(byte[] signature) throws SignatureException {
229: return verify(signature, 0, signature.length);
230: }
231:
232: /**
233: * Verifies the passed-in signature.
234: *
235: * <p>A call to this method resets this signature object to the state
236: * it was in when previously initialized for verification via a
237: * call to <code>initVerify(PublicKey)</code>. That is, the object is
238: * reset and available to verify another signature from the identity
239: * whose public key was specified in the call to <code>initVerify</code>.
240: *
241: * @param signature the input buffer containing signature data
242: * @param offset starting offset within the sigBuf where signature
243: * data begins
244: * @param length byte length of signature data
245: *
246: * @return true if signature verifies, false otherwise
247: *
248: * @exception SignatureException if this signature object is not
249: * initialized properly, or the passed-in signature is improperly
250: * encoded or of the wrong type, etc.
251: */
252: public abstract boolean verify(byte[] signature, int offset,
253: int length) throws SignatureException;
254: }
|