KeyAgreementSpi


1   /*
2    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
3    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
4    */
5   
6   /*
7    * @(#)KeyAgreementSpi.java 1.4 03/12/19
8    */
9     
10  /*
11   * NOTE:
12   * Because of various external restrictions (i.e. US export
13   * regulations, etc.), the actual source code can not be provided
14   * at this time. This file represents the skeleton of the source
15   * file, so that javadocs of the API can be created.
16   */
17  
18  package javax.crypto;
19  
20  import java.security.*;
21  import java.security.spec.*;
22  
23  /** 
24   * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
25   * for the <code>KeyAgreement</code> class.
26   * All the abstract methods in this class must be implemented by each 
27   * cryptographic service provider who wishes to supply the implementation
28   * of a particular key agreement algorithm.
29   *
30   * <p> The keys involved in establishing a shared secret are created by one
31   * of the
32   * key generators (<code>KeyPairGenerator</code> or
33   * <code>KeyGenerator</code>), a <code>KeyFactory</code>, or as a result from
34   * an intermediate phase of the key agreement protocol
35   * (@see #engineDoPhase(java.security.Key, boolean) engineDoPhase).
36   *
37   * <p> For each of the correspondents in the key exchange,
38   * <code>engineDoPhase</code>
39   * needs to be called. For example, if the key exchange is with one other
40   * party, <code>engineDoPhase</code> needs to be called once, with the
41   * <code>lastPhase</code> flag set to <code>true</code>.
42   * If the key exchange is
43   * with two other parties, <code>engineDoPhase</code> needs to be called twice,
44   * the first time setting the <code>lastPhase</code> flag to
45   * <code>false</code>, and the second time setting it to <code>true</code>.
46   * There may be any number of parties involved in a key exchange.
47   *
48   * @author Jan Luehe
49   *
50   * @version 1.4, 12/19/03
51   *
52   * @see KeyGenerator
53   * @see SecretKey
54   * @since 1.4
55   */
56  public abstract class KeyAgreementSpi
57  {
58  
59      public KeyAgreementSpi() { }
60  
61      /** 
62       * Initializes this key agreement with the given key and source of
63       * randomness. The given key is required to contain all the algorithm
64       * parameters required for this key agreement.
65       *
66       * <p> If the key agreement algorithm requires random bytes, it gets them
67       * from the given source of randomness, <code>random</code>.
68       * However, if the underlying
69       * algorithm implementation does not require any random bytes,
70       * <code>random</code> is ignored.
71       *
72       * @param key the party's private information. For example, in the case
73       * of the Diffie-Hellman key agreement, this would be the party's own
74       * Diffie-Hellman private key.
75       * @param random the source of randomness
76       *
77       * @exception InvalidKeyException if the given key is
78       * inappropriate for this key agreement, e.g., is of the wrong type or
79       * has an incompatible algorithm type.
80       */
81      protected abstract void engineInit(Key key, SecureRandom random)
82          throws InvalidKeyException;
83  
84      /** 
85       * Initializes this key agreement with the given key, set of
86       * algorithm parameters, and source of randomness.
87       *
88       * @param key the party's private information. For example, in the case
89       * of the Diffie-Hellman key agreement, this would be the party's own
90       * Diffie-Hellman private key.
91       * @param params the key agreement parameters
92       * @param random the source of randomness
93       *
94       * @exception InvalidKeyException if the given key is
95       * inappropriate for this key agreement, e.g., is of the wrong type or
96       * has an incompatible algorithm type.
97       * @exception InvalidAlgorithmParameterException if the given parameters
98       * are inappropriate for this key agreement.
99       */
100     protected abstract void engineInit(Key key, AlgorithmParameterSpec params,
101         SecureRandom random)
102         throws InvalidKeyException, InvalidAlgorithmParameterException;
103 
104     /** 
105      * Executes the next phase of this key agreement with the given
106      * key that was received from one of the other parties involved in this key
107      * agreement.
108      *
109      * @param key the key for this phase. For example, in the case of
110      * Diffie-Hellman between 2 parties, this would be the other party's
111      * Diffie-Hellman public key.
112      * @param lastPhase flag which indicates whether or not this is the last
113      * phase of this key agreement.
114      *
115      * @return the (intermediate) key resulting from this phase, or null if
116      * this phase does not yield a key
117      *
118      * @exception InvalidKeyException if the given key is inappropriate for
119      * this phase.
120      * @exception IllegalStateException if this key agreement has not been
121      * initialized.
122      */
123     protected abstract Key engineDoPhase(Key key, boolean lastPhase)
124         throws InvalidKeyException, IllegalStateException;
125 
126     /** 
127      * Generates the shared secret and returns it in a new buffer.
128      *
129      * <p>This method resets this <code>KeyAgreementSpi</code> object,
130      * so that it
131      * can be reused for further key agreements. Unless this key agreement is
132      * reinitialized with one of the <code>engineInit</code> methods, the same
133      * private information and algorithm parameters will be used for
134      * subsequent key agreements.
135      *
136      * @return the new buffer with the shared secret
137      *
138      * @exception IllegalStateException if this key agreement has not been
139      * completed yet
140      */
141     protected abstract byte[] engineGenerateSecret()
142         throws IllegalStateException;
143 
144     /** 
145      * Generates the shared secret, and places it into the buffer
146      * <code>sharedSecret</code>, beginning at <code>offset</code> inclusive.
147      *
148      * <p>If the <code>sharedSecret</code> buffer is too small to hold the
149      * result, a <code>ShortBufferException</code> is thrown.
150      * In this case, this call should be repeated with a larger output buffer. 
151      *
152      * <p>This method resets this <code>KeyAgreementSpi</code> object,
153      * so that it
154      * can be reused for further key agreements. Unless this key agreement is
155      * reinitialized with one of the <code>engineInit</code> methods, the same
156      * private information and algorithm parameters will be used for
157      * subsequent key agreements.
158      *
159      * @param sharedSecret the buffer for the shared secret
160      * @param offset the offset in <code>sharedSecret</code> where the
161      * shared secret will be stored
162      *
163      * @return the number of bytes placed into <code>sharedSecret</code>
164      *
165      * @exception IllegalStateException if this key agreement has not been
166      * completed yet
167      * @exception ShortBufferException if the given output buffer is too small
168      * to hold the secret
169      */
170     protected abstract int engineGenerateSecret(byte[] sharedSecret, int
171         offset) throws IllegalStateException, ShortBufferException;
172 
173     /** 
174      * Creates the shared secret and returns it as a secret key object
175      * of the requested algorithm type.
176      *
177      * <p>This method resets this <code>KeyAgreementSpi</code> object,
178      * so that it
179      * can be reused for further key agreements. Unless this key agreement is
180      * reinitialized with one of the <code>engineInit</code> methods, the same
181      * private information and algorithm parameters will be used for
182      * subsequent key agreements.
183      *
184      * @param algorithm the requested secret key algorithm
185      *
186      * @return the shared secret key
187      *
188      * @exception IllegalStateException if this key agreement has not been
189      * completed yet
190      * @exception NoSuchAlgorithmException if the requested secret key
191      * algorithm is not available
192      * @exception InvalidKeyException if the shared secret key material cannot
193      * be used to generate a secret key of the requested algorithm type (e.g.,
194      * the key material is too short)
195      */
196     protected abstract SecretKey engineGenerateSecret(String algorithm)
197         throws IllegalStateException, NoSuchAlgorithmException,
198         InvalidKeyException;
199 }
200
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Java Books Remove Frame
Popular Tags