KeyAgreement


1   /*
2    * @(#)KeyAgreement.java    1.7 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7     
8   /*
9    * NOTE:
10   * Because of various external restrictions (i.e. US export
11   * regulations, etc.), the actual source code can not be provided
12   * at this time. This file represents the skeleton of the source
13   * file, so that javadocs of the API can be created.
14   */
15  
16  package javax.crypto;
17  
18  import java.util.*;
19  import java.security.*;
20  import java.security.spec.*;
21  import sun.security.jca.*;
22  
23  import java.security.Provider.Service;
24  import sun.security.util.Debug;
25  import sun.security.jca.GetInstance.Instance;
26  
27  /** 
28   * This class provides the functionality of a key agreement (or key
29   * exchange) protocol.
30   * The keys involved in establishing a shared secret are created by one of the
31   * key generators (<code>KeyPairGenerator</code> or
32   * <code>KeyGenerator</code>), a <code>KeyFactory</code>, or as a result from
33   * an intermediate phase of the key agreement protocol
34   *
35   * For each of the correspondents in the key exchange, <code>doPhase</code>
36   * needs to be called. For example, if this key exchange is with one other
37   * party, <code>doPhase</code> needs to be called once, with the
38   * <code>lastPhase</code> flag set to <code>true</code>.
39   * If this key exchange is
40   * with two other parties, <code>doPhase</code> needs to be called twice,
41   * the first time setting the <code>lastPhase</code> flag to
42   * <code>false</code>, and the second time setting it to <code>true</code>.
43   * There may be any number of parties involved in a key exchange.
44   *
45   * @author Jan Luehe
46   *
47   * @version 1.44, 10/29/03
48   *
49   * @see KeyGenerator
50   * @see SecretKey
51   * @since 1.4
52   */
53  public class KeyAgreement
54  {
55  
56      /** 
57       * Creates a KeyAgreement object.
58       *
59       * @param keyAgreeSpi the delegate
60       * @param provider the provider
61       * @param algorithm the algorithm
62       */
63      protected KeyAgreement(KeyAgreementSpi keyAgreeSpi, Provider provider,
64          String algorithm)
65      { }
66  
67      /** 
68       * Returns the algorithm name of this <code>KeyAgreement</code> object.
69       *
70       * <p>This is the same name that was specified in one of the
71       * <code>getInstance</code> calls that created this
72       * <code>KeyAgreement</code> object.
73       * 
74       * @return the algorithm name of this <code>KeyAgreement</code> object. 
75       */
76      public final String getAlgorithm() { }
77  
78      /** 
79       * Generates a <code>KeyAgreement</code> object that implements the
80       * specified key agreement algorithm.
81       * If the default provider package provides an implementation of the
82       * requested key agreement algorithm, an instance of
83       * <code>KeyAgreement</code> containing that implementation is returned.
84       * If the algorithm is not available in the default provider package,
85       * other provider packages are searched.
86       *
87       * @param algorithm the standard name of the requested key agreement
88       * algorithm. 
89       * See Appendix A in the
90       * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppA">
91       * Java Cryptography Extension Reference Guide</a> 
92       * for information about standard algorithm names.
93       *
94       * @return the new <code>KeyAgreement</code> object
95       *
96       * @exception NullPointerException if the specified algorithm
97       * is null.
98       * @exception NoSuchAlgorithmException if the specified algorithm is not
99       * available in the default provider package or any of the other provider
100      * packages that were searched.  
101      */
102     public static final KeyAgreement getInstance(String algorithm)
103         throws NoSuchAlgorithmException
104     { }
105 
106     /** 
107      * Generates a <code>KeyAgreement</code> object for the specified key
108      * agreement algorithm from the specified provider.
109      *
110      * @param algorithm the standard name of the requested key agreement
111      * algorithm.
112      * See Appendix A in the
113      * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppA">
114      * Java Cryptography Extension Reference Guide</a> 
115      * for information about standard algorithm names.
116      * @param provider the name of the provider
117      *
118      * @return the new <code>KeyAgreement</code> object
119      *
120      * @exception NullPointerException if the specified algorithm
121      * is null.
122      * @exception NoSuchAlgorithmException if the specified algorithm is not
123      * available from the specified provider.
124      * @exception NoSuchProviderException if the specified provider has not
125      * been configured. 
126      * @exception IllegalArgumentException if the <code>provider</code>
127      * is null.
128      */
129     public static final KeyAgreement getInstance(String algorithm, String
130         provider) throws NoSuchAlgorithmException, NoSuchProviderException
131     { }
132 
133     /** 
134      * Generates a <code>KeyAgreement</code> object for the specified key
135      * agreement algorithm from the specified provider. Note: the 
136      * <code>provider</code> doesn't have to be registered.
137      *
138      * @param algorithm the standard name of the requested key agreement
139      * algorithm.
140      * See Appendix A in the
141      * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppA">
142      * Java Cryptography Extension Reference Guide</a> 
143      * for information about standard algorithm names.
144      * @param provider the provider
145      *
146      * @return the new <code>KeyAgreement</code> object
147      *
148      * @exception NullPointerException if the specified algorithm
149      * is null.
150      * @exception NoSuchAlgorithmException if the specified algorithm is not
151      * available from the specified provider.
152      * @exception IllegalArgumentException if the <code>provider</code>
153      * is null.
154      */
155     public static final KeyAgreement getInstance(String algorithm, Provider
156         provider) throws NoSuchAlgorithmException
157     { }
158 
159     /** 
160      * Returns the provider of this <code>KeyAgreement</code> object.
161      * 
162      * @return the provider of this <code>KeyAgreement</code> object
163      */
164     public final Provider getProvider() { }
165 
166     /** 
167      * Initializes this key agreement with the given key, which is required to
168      * contain all the algorithm parameters required for this key agreement.
169      *
170      * <p> If this key agreement requires any random bytes, it will get
171      * them using the
172      * {@link SecureRandom <code>SecureRandom</code>}
173      * implementation of the highest-priority
174      * installed provider as the source of randomness.
175      * (If none of the installed providers supply an implementation of
176      * SecureRandom, a system-provided source of randomness will be used.)
177      *
178      * @param key the party's private information. For example, in the case
179      * of the Diffie-Hellman key agreement, this would be the party's own
180      * Diffie-Hellman private key.
181      *
182      * @exception InvalidKeyException if the given key is
183      * inappropriate for this key agreement, e.g., is of the wrong type or
184      * has an incompatible algorithm type.
185      */
186     public final void init(Key key) throws InvalidKeyException { }
187 
188     /** 
189      * Initializes this key agreement with the given key and source of
190      * randomness. The given key is required to contain all the algorithm
191      * parameters required for this key agreement.
192      *
193      * <p> If the key agreement algorithm requires random bytes, it gets them
194      * from the given source of randomness, <code>random</code>.
195      * However, if the underlying
196      * algorithm implementation does not require any random bytes,
197      * <code>random</code> is ignored.
198      *
199      * @param key the party's private information. For example, in the case
200      * of the Diffie-Hellman key agreement, this would be the party's own
201      * Diffie-Hellman private key.
202      * @param random the source of randomness
203      *
204      * @exception InvalidKeyException if the given key is
205      * inappropriate for this key agreement, e.g., is of the wrong type or
206      * has an incompatible algorithm type.
207      */
208     public final void init(Key key, SecureRandom random)
209         throws InvalidKeyException
210     { }
211 
212     /** 
213      * Initializes this key agreement with the given key and set of
214      * algorithm parameters.
215      *
216      * <p> If this key agreement requires any random bytes, it will get
217      * them using the
218      * {@link SecureRandom <code>SecureRandom</code>}
219      * implementation of the highest-priority
220      * installed provider as the source of randomness.
221      * (If none of the installed providers supply an implementation of
222      * SecureRandom, a system-provided source of randomness will be used.)
223      *
224      * @param key the party's private information. For example, in the case
225      * of the Diffie-Hellman key agreement, this would be the party's own
226      * Diffie-Hellman private key.
227      * @param params the key agreement parameters
228      *
229      * @exception InvalidKeyException if the given key is
230      * inappropriate for this key agreement, e.g., is of the wrong type or
231      * has an incompatible algorithm type.
232      * @exception InvalidAlgorithmParameterException if the given parameters
233      * are inappropriate for this key agreement.
234      */
235     public final void init(Key key, AlgorithmParameterSpec params)
236         throws InvalidKeyException, InvalidAlgorithmParameterException
237     { }
238 
239     /** 
240      * Initializes this key agreement with the given key, set of
241      * algorithm parameters, and source of randomness.
242      *
243      * @param key the party's private information. For example, in the case
244      * of the Diffie-Hellman key agreement, this would be the party's own
245      * Diffie-Hellman private key.
246      * @param params the key agreement parameters
247      * @param random the source of randomness
248      *
249      * @exception InvalidKeyException if the given key is
250      * inappropriate for this key agreement, e.g., is of the wrong type or
251      * has an incompatible algorithm type.
252      * @exception InvalidAlgorithmParameterException if the given parameters
253      * are inappropriate for this key agreement.
254      */
255     public final void init(Key key, AlgorithmParameterSpec params, SecureRandom
256         random) throws InvalidKeyException, InvalidAlgorithmParameterException
257     { }
258 
259     /** 
260      * Executes the next phase of this key agreement with the given
261      * key that was received from one of the other parties involved in this key
262      * agreement.
263      *
264      * @param key the key for this phase. For example, in the case of
265      * Diffie-Hellman between 2 parties, this would be the other party's
266      * Diffie-Hellman public key.
267      * @param lastPhase flag which indicates whether or not this is the last
268      * phase of this key agreement.
269      *
270      * @return the (intermediate) key resulting from this phase, or null
271      * if this phase does not yield a key
272      *
273      * @exception InvalidKeyException if the given key is inappropriate for
274      * this phase.
275      * @exception IllegalStateException if this key agreement has not been
276      * initialized.
277      */
278     public final Key doPhase(Key key, boolean lastPhase)
279         throws InvalidKeyException, IllegalStateException
280     { }
281 
282     /** 
283      * Generates the shared secret and returns it in a new buffer.
284      *
285      * <p>This method resets this <code>KeyAgreement</code> object, so that it
286      * can be reused for further key agreements. Unless this key agreement is
287      * reinitialized with one of the <code>init</code> methods, the same
288      * private information and algorithm parameters will be used for
289      * subsequent key agreements.
290      *
291      * @return the new buffer with the shared secret
292      *
293      * @exception IllegalStateException if this key agreement has not been
294      * completed yet
295      */
296     public final byte[] generateSecret() throws IllegalStateException { }
297 
298     /** 
299      * Generates the shared secret, and places it into the buffer
300      * <code>sharedSecret</code>, beginning at <code>offset</code> inclusive.
301      *
302      * <p>If the <code>sharedSecret</code> buffer is too small to hold the
303      * result, a <code>ShortBufferException</code> is thrown.
304      * In this case, this call should be repeated with a larger output buffer. 
305      *
306      * <p>This method resets this <code>KeyAgreement</code> object, so that it
307      * can be reused for further key agreements. Unless this key agreement is
308      * reinitialized with one of the <code>init</code> methods, the same
309      * private information and algorithm parameters will be used for
310      * subsequent key agreements.
311      *
312      * @param sharedSecret the buffer for the shared secret
313      * @param offset the offset in <code>sharedSecret</code> where the
314      * shared secret will be stored
315      *
316      * @return the number of bytes placed into <code>sharedSecret</code>
317      *
318      * @exception IllegalStateException if this key agreement has not been
319      * completed yet
320      * @exception ShortBufferException if the given output buffer is too small
321      * to hold the secret
322      */
323     public final int generateSecret(byte[] sharedSecret, int offset)
324         throws IllegalStateException, ShortBufferException
325     { }
326 
327     /** 
328      * Creates the shared secret and returns it as a <code>SecretKey</code>
329      * object of the specified algorithm.
330      *
331      * <p>This method resets this <code>KeyAgreement</code> object, so that it
332      * can be reused for further key agreements. Unless this key agreement is
333      * reinitialized with one of the <code>init</code> methods, the same
334      * private information and algorithm parameters will be used for
335      * subsequent key agreements.
336      *
337      * @param algorithm the requested secret-key algorithm
338      *
339      * @return the shared secret key
340      *
341      * @exception IllegalStateException if this key agreement has not been
342      * completed yet
343      * @exception NoSuchAlgorithmException if the specified secret-key
344      * algorithm is not available
345      * @exception InvalidKeyException if the shared secret-key material cannot
346      * be used to generate a secret key of the specified algorithm (e.g.,
347      * the key material is too short)    
348      */
349     public final SecretKey generateSecret(String algorithm)
350         throws IllegalStateException, NoSuchAlgorithmException,
351         InvalidKeyException
352     { }
353 }
354
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Java Books Remove Frame
Popular Tags