| Frames | No Frames |
1: /* KeyAgreement.java -- Engine for key agreement methods. 2: Copyright (C) 2004 Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package javax.crypto; 40: 41: import gnu.java.security.Engine; 42: 43: import java.lang.reflect.InvocationTargetException; 44: import java.security.InvalidAlgorithmParameterException; 45: import java.security.InvalidKeyException; 46: import java.security.Key; 47: import java.security.NoSuchAlgorithmException; 48: import java.security.NoSuchProviderException; 49: import java.security.Provider; 50: import java.security.SecureRandom; 51: import java.security.Security; 52: import java.security.spec.AlgorithmParameterSpec; 53: 54: /** 55: * Key agreement is a method in which two or more parties may agree on a 56: * secret key for symmetric cryptography or message authentication 57: * without transmitting any secrets in the clear. Key agreement 58: * algorithms typically use a public/private <i>key pair</i>, and the 59: * public key (along with some additional information) is sent across 60: * untrusted networks. 61: * 62: * <p>The most common form of key agreement used today is the 63: * <i>Diffie-Hellman key exchange algorithm</i>, described in <a 64: * href="http://www.rsasecurity.com/rsalabs/pkcs/pkcs-3/">PKCS #3 - 65: * Diffie Hellman Key Agreement Standard</a>. 66: * 67: * @author Casey Marshall (csm@gnu.org) 68: * @since 1.4 69: * @see KeyGenerator 70: * @see SecretKey 71: */ 72: public class KeyAgreement 73: { 74: 75: // Fields. 76: // ------------------------------------------------------------------------ 77: 78: private static final String SERVICE = "KeyAgreement"; 79: 80: /** The underlying key agreement implementation. */ 81: private KeyAgreementSpi kaSpi; 82: 83: /** The provider of this implementation. */ 84: private Provider provider; 85: 86: /** The name of this instance's algorithm. */ 87: private String algorithm; 88: 89: /** Singnals whether or not this instance has been initialized. */ 90: private boolean virgin; 91: 92: // Constructor. 93: // ------------------------------------------------------------------------ 94: 95: protected KeyAgreement(KeyAgreementSpi kaSpi, Provider provider, 96: String algorithm) 97: { 98: this.kaSpi = kaSpi; 99: this.provider = provider; 100: this.algorithm = algorithm; 101: virgin = true; 102: } 103: 104: /** 105: * Get an implementation of an algorithm from the first provider that 106: * implements it. 107: * 108: * @param algorithm The name of the algorithm to get. 109: * @return The proper KeyAgreement instacne, if found. 110: * @throws NoSuchAlgorithmException If the specified algorithm is not 111: * implemented by any installed provider. 112: * @throws IllegalArgumentException if <code>algorithm</code> is 113: * <code>null</code> or is an empty string. 114: */ 115: public static final KeyAgreement getInstance(String algorithm) 116: throws NoSuchAlgorithmException 117: { 118: Provider[] p = Security.getProviders(); 119: NoSuchAlgorithmException lastException = null; 120: for (int i = 0; i < p.length; i++) 121: try 122: { 123: return getInstance(algorithm, p[i]); 124: } 125: catch (NoSuchAlgorithmException x) 126: { 127: lastException = x; 128: } 129: if (lastException != null) 130: throw lastException; 131: throw new NoSuchAlgorithmException(algorithm); 132: } 133: 134: /** 135: * Return an implementation of an algorithm from a named provider. 136: * 137: * @param algorithm The name of the algorithm to create. 138: * @param provider The name of the provider from which to get the 139: * implementation. 140: * @return The proper KeyAgreement instance, if found. 141: * @throws NoSuchAlgorithmException If the named provider does not implement 142: * the algorithm. 143: * @throws NoSuchProviderException If the named provider does not exist. 144: * @throws IllegalArgumentException if either <code>algorithm</code> or 145: * <code>provider</code> is <code>null</code>, or if 146: * <code>algorithm</code> is an empty string. 147: */ 148: public static final KeyAgreement getInstance(String algorithm, String provider) 149: throws NoSuchAlgorithmException, NoSuchProviderException 150: { 151: if (provider == null) 152: throw new IllegalArgumentException("provider MUST NOT be null"); 153: Provider p = Security.getProvider(provider); 154: if (p == null) 155: throw new NoSuchProviderException(provider); 156: return getInstance(algorithm, p); 157: } 158: 159: /** 160: * Return an implementation of an algorithm from a specific provider. 161: * 162: * @param algorithm The name of the algorithm to get. 163: * @param provider The provider from which to get the implementation. 164: * @return The proper KeyAgreement instance, if found. 165: * @throws NoSuchAlgorithmException If this provider does not implement the 166: * algorithm. 167: * @throws IllegalArgumentException if either <code>algorithm</code> or 168: * <code>provider</code> is <code>null</code>, or if 169: * <code>algorithm</code> is an empty string. 170: */ 171: public static final KeyAgreement getInstance(String algorithm, 172: Provider provider) 173: throws NoSuchAlgorithmException 174: { 175: StringBuilder sb = new StringBuilder("KeyAgreement algorithm [") 176: .append(algorithm).append("] from provider[") 177: .append(provider).append("] could not be created"); 178: Throwable cause; 179: try 180: { 181: Object spi = Engine.getInstance(SERVICE, algorithm, provider); 182: return new KeyAgreement((KeyAgreementSpi) spi, provider, algorithm); 183: } 184: catch (InvocationTargetException x) 185: { 186: cause = x.getCause(); 187: if (cause instanceof NoSuchAlgorithmException) 188: throw (NoSuchAlgorithmException) cause; 189: if (cause == null) 190: cause = x; 191: } 192: catch (ClassCastException x) 193: { 194: cause = x; 195: } 196: NoSuchAlgorithmException x = new NoSuchAlgorithmException(sb.toString()); 197: x.initCause(cause); 198: throw x; 199: } 200: 201: /** 202: * Do a phase in the key agreement. The number of times this method is 203: * called depends upon the algorithm and the number of parties 204: * involved, but must be called at least once with the 205: * <code>lastPhase</code> flag set to <code>true</code>. 206: * 207: * @param key The key for this phase. 208: * @param lastPhase Should be <code>true</code> if this will be the 209: * last phase before generating the shared secret. 210: * @return The intermediate result, or <code>null</code> if there is 211: * no intermediate result. 212: * @throws java.lang.IllegalStateException If this instance has not 213: * been initialized. 214: * @throws java.security.InvalidKeyException If the key is 215: * inappropriate for this algorithm. 216: */ 217: public final Key doPhase(Key key, boolean lastPhase) 218: throws IllegalStateException, InvalidKeyException 219: { 220: if (virgin) 221: { 222: throw new IllegalStateException("not initialized"); 223: } 224: return kaSpi.engineDoPhase(key, lastPhase); 225: } 226: 227: /** 228: * Generate the shared secret in a new byte array. 229: * 230: * @return The shared secret. 231: * @throws java.lang.IllegalStateException If this instnace has not 232: * been initialized, or if not enough calls to 233: * <code>doPhase</code> have been made. 234: */ 235: public final byte[] generateSecret() throws IllegalStateException 236: { 237: if (virgin) 238: { 239: throw new IllegalStateException("not initialized"); 240: } 241: return kaSpi.engineGenerateSecret(); 242: } 243: 244: /** 245: * Generate the shared secret and store it into the supplied array. 246: * 247: * @param sharedSecret The array in which to store the secret. 248: * @param offset The index in <code>sharedSecret</code> to start 249: * storing data. 250: * @return The length of the shared secret, in bytes. 251: * @throws java.lang.IllegalStateException If this instnace has not 252: * been initialized, or if not enough calls to 253: * <code>doPhase</code> have been made. 254: * @throws javax.crypto.ShortBufferException If the supplied array is 255: * not large enough to store the result. 256: */ 257: public final int generateSecret(byte[] sharedSecret, int offset) 258: throws IllegalStateException, ShortBufferException 259: { 260: if (virgin) 261: { 262: throw new IllegalStateException("not initialized"); 263: } 264: return kaSpi.engineGenerateSecret(sharedSecret, offset); 265: } 266: 267: /** 268: * Generate the shared secret and return it as an appropriate {@link 269: * SecretKey}. 270: * 271: * @param algorithm The secret key's algorithm. 272: * @return The shared secret as a secret key. 273: * @throws java.lang.IllegalStateException If this instnace has not 274: * been initialized, or if not enough calls to 275: * <code>doPhase</code> have been made. 276: * @throws java.security.InvalidKeyException If the shared secret 277: * cannot be used to make a {@link SecretKey}. 278: * @throws java.security.NoSuchAlgorithmException If the specified 279: * algorithm does not exist. 280: */ 281: public final SecretKey generateSecret(String algorithm) 282: throws IllegalStateException, InvalidKeyException, NoSuchAlgorithmException 283: { 284: if (virgin) 285: { 286: throw new IllegalStateException("not initialized"); 287: } 288: return kaSpi.engineGenerateSecret(algorithm); 289: } 290: 291: /** 292: * Return the name of this key-agreement algorithm. 293: * 294: * @return The algorithm name. 295: */ 296: public final String getAlgorithm() 297: { 298: return algorithm; 299: } 300: 301: /** 302: * Return the provider of the underlying implementation. 303: * 304: * @return The provider. 305: */ 306: public final Provider getProvider() 307: { 308: return provider; 309: } 310: 311: /** 312: * Initialize this key agreement with a key. This method will use the 313: * highest-priority {@link java.security.SecureRandom} as its source 314: * of randomness. 315: * 316: * @param key The key, usually the user's private key. 317: * @throws java.security.InvalidKeyException If the supplied key is 318: * not appropriate. 319: */ 320: public final void init(Key key) throws InvalidKeyException 321: { 322: init(key, new SecureRandom()); 323: } 324: 325: /** 326: * Initialize this key agreement with a key and a source of 327: * randomness. 328: * 329: * @param key The key, usually the user's private key. 330: * @param random The source of randomness. 331: * @throws java.security.InvalidKeyException If the supplied key is 332: * not appropriate. 333: */ 334: public final void init(Key key, SecureRandom random) 335: throws InvalidKeyException 336: { 337: kaSpi.engineInit(key, random); 338: virgin = false; // w00t! 339: } 340: 341: /** 342: * Initialize this key agreement with a key and parameters. This 343: * method will use the highest-priority {@link 344: * java.security.SecureRandom} as its source of randomness. 345: * 346: * @param key The key, usually the user's private key. 347: * @param params The algorithm parameters. 348: * @throws java.security.InvalidAlgorithmParameterException If the 349: * supplied parameters are not appropriate. 350: * @throws java.security.InvalidKeyException If the supplied key is 351: * not appropriate. 352: */ 353: public final void init(Key key, AlgorithmParameterSpec params) 354: throws InvalidAlgorithmParameterException, InvalidKeyException 355: { 356: init(key, params, new SecureRandom()); 357: } 358: 359: /** 360: * Initialize this key agreement with a key, parameters, and source of 361: * randomness. 362: * 363: * @param key The key, usually the user's private key. 364: * @param params The algorithm parameters. 365: * @param random The source of randomness. 366: * @throws java.security.InvalidAlgorithmParameterException If the 367: * supplied parameters are not appropriate. 368: * @throws java.security.InvalidKeyException If the supplied key is 369: * not appropriate. 370: */ 371: public final void init(Key key, AlgorithmParameterSpec params, 372: SecureRandom random) 373: throws InvalidAlgorithmParameterException, InvalidKeyException 374: { 375: kaSpi.engineInit(key, params, random); 376: virgin = false; // w00t! 377: } 378: }