1 |
/* SignatureSpi.java --- Signature Service Provider Interface |
/* SignatureSpi.java --- Signature Service Provider Interface |
2 |
Copyright (C) 1999 Free Software Foundation, Inc. |
Copyright (C) 1999, 2003, Free Software Foundation, Inc. |
3 |
|
|
4 |
This file is part of GNU Classpath. |
This file is part of GNU Classpath. |
5 |
|
|
36 |
exception statement from your version. */ |
exception statement from your version. */ |
37 |
|
|
38 |
package java.security; |
package java.security; |
39 |
|
|
40 |
import java.security.spec.AlgorithmParameterSpec; |
import java.security.spec.AlgorithmParameterSpec; |
41 |
|
|
42 |
/** |
/** |
43 |
SignatureSpi defines the Service Provider Interface (SPI) |
* <p>This class defines the <i>Service Provider Interface (SPI)</i> for the |
44 |
for the Signature class. The signature class provides an |
* {@link Signature} class, which is used to provide the functionality of a |
45 |
interface to a digital signature algorithm. Digital signatures |
* digital signature algorithm. Digital signatures are used for authentication |
46 |
are used for authentication and integrity of data. |
* and integrity assurance of digital data.</p> |
47 |
|
* |
48 |
@author Mark Benvenuto <ivymccough@worldnet.att.net> |
* <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 |
@since JDK 1.2 |
* 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 |
public abstract class SignatureSpi |
57 |
{ |
{ |
58 |
/** |
/** Application-specified source of randomness. */ |
|
Source of randomness |
|
|
*/ |
|
59 |
protected SecureRandom appRandom; |
protected SecureRandom appRandom; |
60 |
|
|
|
/** |
|
|
Creates a new instance of SignatureSpi. |
|
|
*/ |
|
61 |
public SignatureSpi() |
public SignatureSpi() |
62 |
{ |
{ |
63 |
appRandom = null; |
appRandom = null; |
64 |
} |
} |
65 |
|
|
66 |
/** |
/** |
67 |
Initializes this class with the public key for |
* Initializes this signature object with the specified public key for |
68 |
verification purposes. |
* verification operations. |
69 |
|
* |
70 |
@param publicKey the public key to verify with |
* @param publicKey the public key of the identity whose signature is going |
71 |
|
* to be verified. |
72 |
@throws InvalidKeyException invalid key |
* @throws InvalidKeyException if the key is improperly encoded, parameters |
73 |
|
* are missing, and so on. |
74 |
*/ |
*/ |
75 |
protected abstract void engineInitVerify(PublicKey publicKey) |
protected abstract void engineInitVerify(PublicKey publicKey) |
76 |
throws InvalidKeyException; |
throws InvalidKeyException; |
77 |
|
|
78 |
/** |
/** |
79 |
Initializes this class with the private key for |
* Initializes this signature object with the specified private key for |
80 |
signing purposes. |
* signing operations. |
81 |
|
* |
82 |
@param privateKey the private key to sign with |
* @param privateKey the private key of the identity whose signature will be |
83 |
|
* generated. |
84 |
@throws InvalidKeyException invalid key |
* @throws InvalidKeyException if the key is improperly encoded, parameters |
85 |
|
* are missing, and so on. |
86 |
*/ |
*/ |
87 |
protected abstract void engineInitSign(PrivateKey privateKey) |
protected abstract void engineInitSign(PrivateKey privateKey) |
88 |
throws InvalidKeyException; |
throws InvalidKeyException; |
89 |
|
|
90 |
/** |
/** |
91 |
Initializes this class with the private key and source |
* <p>Initializes this signature object with the specified private key and |
92 |
of randomness for signing purposes. |
* source of randomness for signing operations.</p> |
93 |
|
* |
94 |
This cannot be abstract backward compatibility reasons |
* <p>This concrete method has been added to this previously-defined abstract |
95 |
|
* class. (For backwards compatibility, it cannot be abstract.)</p> |
96 |
@param privateKey the private key to sign with |
* |
97 |
@param random Source of randomness |
* @param privateKey the private key of the identity whose signature will be |
98 |
|
* generated. |
99 |
@throws InvalidKeyException invalid key |
* @param random the source of randomness. |
100 |
|
* @throws InvalidKeyException if the key is improperly encoded, parameters |
101 |
@since JDK 1.2 |
* are missing, and so on. |
102 |
|
* @since 1.2 |
103 |
*/ |
*/ |
104 |
protected void engineInitSign(PrivateKey privateKey, SecureRandom random) |
protected void engineInitSign(PrivateKey privateKey, SecureRandom random) |
105 |
throws InvalidKeyException |
throws InvalidKeyException |
109 |
} |
} |
110 |
|
|
111 |
/** |
/** |
112 |
Updates the data to be signed or verified with the specified |
* Updates the data to be signed or verified using the specified byte. |
113 |
byte. |
* |
114 |
|
* @param b the byte to use for the update. |
115 |
@param b byte to update with |
* @throws SignatureException if the engine is not initialized properly. |
|
|
|
|
@throws SignatureException Engine not properly initialized |
|
116 |
*/ |
*/ |
117 |
protected abstract void engineUpdate(byte b) throws SignatureException; |
protected abstract void engineUpdate(byte b) throws SignatureException; |
118 |
|
|
119 |
/** |
/** |
120 |
Updates the data to be signed or verified with the specified |
* Updates the data to be signed or verified, using the specified array of |
121 |
bytes. |
* bytes, starting at the specified offset. |
122 |
|
* |
123 |
@param b array of bytes |
* @param b the array of bytes. |
124 |
@param off the offset to start at in the array |
* @param off the offset to start from in the array of bytes. |
125 |
@param len the length of the bytes to use in the array |
* @param len the number of bytes to use, starting at offset. |
126 |
|
* @throws SignatureException if the engine is not initialized properly. |
|
@throws SignatureException engine not properly initialized |
|
127 |
*/ |
*/ |
128 |
protected abstract void engineUpdate(byte[] b, int off, int len) |
protected abstract void engineUpdate(byte[] b, int off, int len) |
129 |
throws SignatureException; |
throws SignatureException; |
130 |
|
|
131 |
/** |
/** |
132 |
Returns the signature bytes of all the data fed to this class. |
* Returns the signature bytes of all the data updated so far. The format of |
133 |
The format of the output depends on the underlying signature |
* the signature depends on the underlying signature scheme. |
134 |
algorithm. |
* |
135 |
|
* @return the signature bytes of the signing operation's result. |
136 |
@return the signature |
* @throws SignatureException if the engine is not initialized properly. |
|
|
|
|
@throws SignatureException engine not properly initialized |
|
137 |
*/ |
*/ |
138 |
protected abstract byte[] engineSign() throws SignatureException; |
protected abstract byte[] engineSign() throws SignatureException; |
139 |
|
|
140 |
/** |
/** |
141 |
Generates signature bytes of all the data fed to this class |
* <p>Finishes this signature operation and stores the resulting signature |
142 |
and outputs it to the passed array. The format of the |
* bytes in the provided buffer <code>outbuf</code>, starting at <code>offset |
143 |
output depends on the underlying signature algorithm. |
* </code>. The format of the signature depends on the underlying signature |
144 |
|
* scheme.</p> |
145 |
This cannot be abstract backward compatibility reasons. |
* |
146 |
After calling this method, the signature is reset to its |
* <p>The signature implementation is reset to its initial state (the state it |
147 |
initial state and can be used to generate additional |
* was in after a call to one of the <code>engineInitSign()</code> methods) |
148 |
signatures. |
* 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 |
@param outbuff array of bytes |
* compatibility. Knowledgeable providers should override this method.</p> |
151 |
@param offset the offset to start at in the array |
* |
152 |
@param len the length of the bytes to put into the array. |
* @param outbuf buffer for the signature result. |
153 |
Neither this method or the GNU provider will |
* @param offset offset into outbuf where the signature is stored. |
154 |
return partial digests. If len is less than the |
* @param len number of bytes within outbuf allotted for the signature. Both |
155 |
signature length, this method will throw |
* this default implementation and the <b>GNU</b> provider do not return |
156 |
SignatureException. If it is greater than or equal |
* partial digests. If the value of this parameter is less than the actual |
157 |
then it is ignored. |
* 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 |
@return number of bytes in outbuf |
* signature length. |
160 |
|
* @return the number of bytes placed into <code>outbuf</code>. |
161 |
@throws SignatureException engine not properly initialized |
* @throws SignatureException if an error occurs or len is less than the |
162 |
|
* actual signature length. |
163 |
@since JDK 1.2 |
* @since 1.2 |
164 |
*/ |
*/ |
165 |
protected int engineSign(byte[] outbuf, int offset, int len) |
protected int engineSign(byte[] outbuf, int offset, int len) |
166 |
throws SignatureException |
throws SignatureException |
167 |
{ |
{ |
168 |
byte tmp[] = engineSign(); |
byte tmp[] = engineSign(); |
|
|
|
169 |
if (tmp.length > len) |
if (tmp.length > len) |
170 |
throw new SignatureException("Invalid Length"); |
throw new SignatureException("Invalid Length"); |
171 |
|
|
172 |
System.arraycopy(outbuf, offset, tmp, 0, tmp.length); |
System.arraycopy(outbuf, offset, tmp, 0, tmp.length); |
|
|
|
173 |
return tmp.length; |
return tmp.length; |
174 |
} |
} |
175 |
|
|
176 |
/** |
/** |
177 |
Verifies the passed signature. |
* Verifies the passed-in signature. |
178 |
|
* |
179 |
@param sigBytes the signature bytes to verify |
* @param sigBytes the signature bytes to be verified. |
180 |
|
* @return <code>true</code> if the signature was verified, <code>false</code> |
181 |
@return true if verified, false otherwise |
* if not. |
182 |
|
* @throws SignatureException if the engine is not initialized properly, or |
183 |
@throws SignatureException engine not properly initialized |
* the passed-in signature is improperly encoded or of the wrong type, etc. |
|
or wrong signature |
|
184 |
*/ |
*/ |
185 |
protected abstract boolean engineVerify(byte[] sigBytes) |
protected abstract boolean engineVerify(byte[] sigBytes) |
186 |
throws SignatureException; |
throws SignatureException; |
187 |
|
|
188 |
/** |
/** |
189 |
Sets the specified algorithm parameter to the specified value. |
* Sets the specified algorithm parameter to the specified value. This method |
190 |
|
* supplies a general-purpose mechanism through which it is possible to set |
191 |
@param param parameter name |
* the various parameters of this object. A parameter may be any settable |
192 |
@param value parameter value |
* parameter for the algorithm, such as a parameter size, or a source of |
193 |
|
* random bits for signature generation (if appropriate), or an indication of |
194 |
@throws InvalidParameterException invalid parameter, parameter |
* whether or not to perform a specific but optional computation. A uniform |
195 |
already set and cannot set again, a security exception, |
* algorithm-specific naming scheme for each parameter is desirable but left |
196 |
etc. |
* unspecified at this time. |
197 |
|
* |
198 |
@deprecated use the other setParameter |
* @param param the string identifier of the parameter. |
199 |
|
* @param value the parameter value. |
200 |
|
* @throws InvalidParameterException if <code>param</code> is an invalid |
201 |
|
* parameter for this signature algorithm engine, the parameter is already set |
202 |
|
* and cannot be set again, a security exception occurs, and so on. |
203 |
|
* @deprecated Replaced by engineSetParameter(AlgorithmParameterSpec). |
204 |
*/ |
*/ |
205 |
protected abstract void engineSetParameter(String param, Object value) |
protected abstract void engineSetParameter(String param, Object value) |
206 |
throws InvalidParameterException; |
throws InvalidParameterException; |
207 |
|
|
208 |
/** |
/** |
209 |
Sets the signature engine with the specified |
* This method is overridden by providers to initialize this signature engine |
210 |
AlgorithmParameterSpec; |
* with the specified parameter set. |
211 |
|
* |
212 |
This cannot be abstract backward compatibility reasons |
* @param params the parameters. |
213 |
By default this always throws UnsupportedOperationException |
* @throws UnsupportedOperationException if this method is not overridden by |
214 |
if not overridden; |
* a provider. |
215 |
|
* @throws InvalidAlgorithmParameterException if this method is overridden by |
216 |
@param params the parameters |
* a provider and the the given parameters are inappropriate for this |
217 |
|
* signature engine. |
|
@throws InvalidParameterException invalid parameter, parameter |
|
|
already set and cannot set again, a security exception, |
|
|
etc. |
|
218 |
*/ |
*/ |
219 |
protected void engineSetParameter(AlgorithmParameterSpec params) |
protected void engineSetParameter(AlgorithmParameterSpec params) |
220 |
throws InvalidAlgorithmParameterException |
throws InvalidAlgorithmParameterException |
223 |
} |
} |
224 |
|
|
225 |
/** |
/** |
226 |
Gets the value for the specified algorithm parameter. |
* Gets the value of the specified algorithm parameter. This method supplies |
227 |
|
* a general-purpose mechanism through which it is possible to get the various |
228 |
@param param parameter name |
* parameters of this object. A parameter may be any settable parameter for |
229 |
|
* the algorithm, such as a parameter size, or a source of random bits for |
230 |
@return parameter value |
* signature generation (if appropriate), or an indication of whether or not |
231 |
|
* to perform a specific but optional computation. A uniform algorithm-specific |
232 |
@throws InvalidParameterException invalid parameter |
* naming scheme for each parameter is desirable but left unspecified at this |
233 |
|
* time. |
234 |
@deprecated use the other getParameter |
* |
235 |
|
* @param param the string name of the parameter. |
236 |
|
* @return the object that represents the parameter value, or <code>null</code> |
237 |
|
* if there is none. |
238 |
|
* @throws InvalidParameterException if <code>param<?code> is an invalid |
239 |
|
* parameter for this engine, or another exception occurs while trying to get |
240 |
|
* this parameter. |
241 |
|
* @deprecated |
242 |
*/ |
*/ |
243 |
protected abstract Object engineGetParameter(String param) |
protected abstract Object engineGetParameter(String param) |
244 |
throws InvalidParameterException; |
throws InvalidParameterException; |
245 |
|
|
246 |
/** |
/** |
247 |
Returns a clone if cloneable. |
* Returns a clone if the implementation is cloneable. |
248 |
|
* |
249 |
@return a clone if cloneable. |
* @return a clone if the implementation is cloneable. |
250 |
|
* @throws CloneNotSupportedException if this is called on an implementation |
251 |
@throws CloneNotSupportedException if the implementation does |
* that does not support {@link Cloneable}. |
252 |
not support cloning |
* @see Cloneable |
253 |
*/ |
*/ |
254 |
public Object clone() throws CloneNotSupportedException |
public Object clone() throws CloneNotSupportedException |
255 |
{ |
{ |