001 /* SignatureSpi.java --- Signature Service Provider Interface 002 Copyright (C) 1999, 2003, Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath 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 for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 package java.security; 039 040 import java.nio.ByteBuffer; 041 import 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 */ 053 public 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 }