ExemptionMechanism


1   /*
2    * @(#)ExemptionMechanism.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.security.AlgorithmParameters;
19  import java.security.Provider;
20  import java.security.Key;
21  import java.security.NoSuchAlgorithmException;
22  import java.security.NoSuchProviderException;
23  import java.security.InvalidKeyException;
24  import java.security.InvalidAlgorithmParameterException;
25  import java.security.spec.AlgorithmParameterSpec;
26  import sun.security.jca.GetInstance.Instance;
27  
28  /** 
29   * This class provides the functionality of an exemption mechanism, examples
30   * of which are <i>key recovery</i>, <i>key weakening</i>, and
31   * <i>key escrow</i>.
32   *
33   * <p>Applications or applets that use an exemption mechanism may be granted
34   * stronger encryption capabilities than those which don't.
35   *
36   * @version 1.11, 11/30/03
37   * @since 1.4
38   */
39  public class ExemptionMechanism
40  {
41  
42      /** 
43       * Creates a ExemptionMechanism object.
44       *
45       * @param exmechSpi the delegate
46       * @param provider the provider
47       * @param mechanism the exemption mechanism
48       */
49      protected ExemptionMechanism(ExemptionMechanismSpi exmechSpi, Provider
50          provider, String mechanism)
51      { }
52  
53      /** 
54       * Returns the exemption mechanism name of this
55       * <code>ExemptionMechanism</code> object.
56       *
57       * <p>This is the same name that was specified in one of the
58       * <code>getInstance</code> calls that created this
59       * <code>ExemptionMechanism</code> object.
60       *
61       * @return the exemption mechanism name of this
62       * <code>ExemptionMechanism</code> object.
63       */
64      public final String getName() { }
65  
66      /** 
67       * Generates a <code>ExemptionMechanism</code> object that implements the
68       * specified exemption mechanism algorithm.
69       * If the default provider package provides an implementation of the
70       * requested exemption mechanism algorithm, an instance of
71       * <code>ExemptionMechanism</code> containing that implementation is
72       * returned.
73       * If the exemption mechanism is not available in the default provider
74       * package, other provider packages are searched.
75       *
76       * @param algorithm the standard name of the requested exemption
77       * mechanism.
78       * See Appendix A in the
79       * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppA">
80       * Java Cryptography Extension Reference Guide</a>
81       * for information about standard exemption mechanism names.
82       *
83       * @return the new <code>ExemptionMechanism</code> object
84       *
85       * @exception NullPointerException if <code>algorithm</code>
86       * is null.
87       * @exception NoSuchAlgorithmException if the specified algorithm
88       * is not available in the default provider package or any of
89       * the other provider packages that were searched.
90       */
91      public static final ExemptionMechanism getInstance(String algorithm)
92          throws NoSuchAlgorithmException
93      { }
94  
95      /** 
96       * Generates a <code>ExemptionMechanism</code> object for the specified
97       * exemption mechanism from the specified provider.
98       *
99       * @param algorithm the standard name of the requested exemption mechanism.
100      * See Appendix A in the
101      * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppA">
102      * Java Cryptography Extension Reference Guide</a>
103      * for information about standard exemption mechanism names.
104      * @param provider the name of the provider
105      *
106      * @return the new <code>ExemptionMechanism</code> object
107      *
108      * @exception NullPointerException if <code>algorithm</code>
109      * is null.
110      * @exception NoSuchAlgorithmException if the specified algorithm
111      * is not available from the specified provider.
112      * @exception NoSuchProviderException if the specified provider has not
113      * been configured.
114      * @exception IllegalArgumentException if the <code>provider</code>
115      * is null.
116      */
117     public static final ExemptionMechanism getInstance(String algorithm, String
118         provider) throws NoSuchAlgorithmException, NoSuchProviderException
119     { }
120 
121     /** 
122      * Generates a <code>ExemptionMechanism</code> object for the specified
123      * exemption mechanism algorithm from the specified provider. Note: the 
124      * <code>provider</code> doesn't have to be registered.
125      *
126      * @param algorithm the standard name of the requested exemption mechanism.
127      * See Appendix A in the
128      * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppA">
129      * Java Cryptography Extension Reference Guide</a>
130      * for information about standard exemption mechanism names.
131      * @param provider the provider
132      *
133      * @return the new <code>ExemptionMechanism</code> object
134      *
135      * @exception NullPointerException if <code>algorithm</code>
136      * is null.
137      * @exception NoSuchAlgorithmException if the specified algorithm
138      * is not available from the specified provider.
139      * @exception IllegalArgumentException if the <code>provider</code>
140      * is null.
141      */
142     public static final ExemptionMechanism getInstance(String algorithm,
143         Provider provider) throws NoSuchAlgorithmException
144     { }
145 
146     /** 
147      * Returns the provider of this <code>ExemptionMechanism</code> object.
148      *
149      * @return the provider of this <code>ExemptionMechanism</code> object.
150      */
151     public final Provider getProvider() { }
152 
153     /** 
154      * Returns whether the result blob has been generated successfully by this
155      * exemption mechanism.
156      *
157      * <p>The method also makes sure that the key passed in is the same as
158      * the one this exemption mechanism used in initializing and generating
159      * phases.
160      *
161      * @param key the key the crypto is going to use.
162      *
163      * @return whether the result blob of the same key has been generated
164      * successfully by this exemption mechanism; false if <code>key</code> 
165      * is null.
166      *
167      * @exception ExemptionMechanismException if problem(s) encountered
168      * while determining whether the result blob has been generated successfully
169      * by this exemption mechanism object.
170      */
171     public final boolean isCryptoAllowed(Key key)
172         throws ExemptionMechanismException
173     { }
174 
175     /** 
176      * Returns the length in bytes that an output buffer would need to be in
177      * order to hold the result of the next
178      * {@link #genExemptionBlob(byte[]) genExemptionBlob}
179      * operation, given the input length <code>inputLen</code> (in bytes).
180      *
181      * <p>The actual output length of the next
182      * {@link #genExemptionBlob(byte[]) genExemptionBlob}
183      * call may be smaller than the length returned by this method.
184      *
185      * @param inputLen the input length (in bytes)
186      *
187      * @return the required output buffer size (in bytes)
188      *
189      * @exception IllegalStateException if this exemption mechanism is in a
190      * wrong state (e.g., has not yet been initialized)
191      */
192     public final int getOutputSize(int inputLen) throws IllegalStateException
193     { }
194 
195     /** 
196      * Initializes this exemption mechanism with a key.
197      *
198      * <p>If this exemption mechanism requires any algorithm parameters
199      * that cannot be derived from the given <code>key</code>, the
200      * underlying exemption mechanism implementation is supposed to
201      * generate the required parameters itself (using provider-specific
202      * default values); in the case that algorithm parameters must be
203      * specified by the caller, an <code>InvalidKeyException</code> is raised.
204      *
205      * @param key the key for this exemption mechanism
206      *
207      * @exception InvalidKeyException if the given key is inappropriate for
208      * this exemption mechanism.
209      * @exception ExemptionMechanismException if problem(s) encountered in the
210      * process of initializing.
211      */
212     public final void init(Key key)
213         throws InvalidKeyException, ExemptionMechanismException
214     { }
215 
216     /** 
217      * Initializes this exemption mechanism with a key and a set of algorithm
218      * parameters.
219      *
220      * <p>If this exemption mechanism requires any algorithm parameters
221      * and <code>params</code> is null, the underlying exemption
222      * mechanism implementation is supposed to generate the required
223      * parameters itself (using provider-specific default values); in the case
224      * that algorithm parameters must be specified by the caller, an
225      * <code>InvalidAlgorithmParameterException</code> is raised.
226      *
227      * @param key the key for this exemption mechanism
228      * @param params the algorithm parameters
229      *
230      * @exception InvalidKeyException if the given key is inappropriate for
231      * this exemption mechanism.
232      * @exception InvalidAlgorithmParameterException if the given algorithm
233      * parameters are inappropriate for this exemption mechanism.
234      * @exception ExemptionMechanismException if problem(s) encountered in the
235      * process of initializing.
236      */
237     public final void init(Key key, AlgorithmParameterSpec params)
238         throws InvalidKeyException, InvalidAlgorithmParameterException,
239         ExemptionMechanismException
240     { }
241 
242     /** 
243      * Initializes this exemption mechanism with a key and a set of algorithm
244      * parameters.
245      *
246      * <p>If this exemption mechanism requires any algorithm parameters
247      * and <code>params</code> is null, the underlying exemption mechanism
248      * implementation is supposed to generate the required parameters itself
249      * (using provider-specific default values); in the case that algorithm
250      * parameters must be specified by the caller, an
251      * <code>InvalidAlgorithmParameterException</code> is raised.
252      *
253      * @param key the key for this exemption mechanism
254      * @param params the algorithm parameters
255      *
256      * @exception InvalidKeyException if the given key is inappropriate for
257      * this exemption mechanism.
258      * @exception InvalidAlgorithmParameterException if the given algorithm
259      * parameters are inappropriate for this exemption mechanism.
260      * @exception ExemptionMechanismException if problem(s) encountered in the
261      * process of initializing.
262      */
263     public final void init(Key key, AlgorithmParameters params)
264         throws InvalidKeyException, InvalidAlgorithmParameterException,
265         ExemptionMechanismException
266     { }
267 
268     /** 
269      * Generates the exemption mechanism key blob.
270      *
271      * @return the new buffer with the result key blob.
272      *
273      * @exception IllegalStateException if this exemption mechanism is in
274      * a wrong state (e.g., has not been initialized).
275      * @exception ExemptionMechanismException if problem(s) encountered in the
276      * process of generating.
277      */
278     public final byte[] genExemptionBlob()
279         throws IllegalStateException, ExemptionMechanismException
280     { }
281 
282     /** 
283      * Generates the exemption mechanism key blob, and stores the result in
284      * the <code>output</code> buffer.
285      *
286      * <p>If the <code>output</code> buffer is too small to hold the result,
287      * a <code>ShortBufferException</code> is thrown. In this case, repeat this
288      * call with a larger output buffer. Use
289      * {@link #getOutputSize(int) getOutputSize} to determine how big
290      * the output buffer should be.
291      *
292      * @param output the buffer for the result
293      *
294      * @return the number of bytes stored in <code>output</code>
295      *
296      * @exception IllegalStateException if this exemption mechanism is in
297      * a wrong state (e.g., has not been initialized).
298      * @exception ShortBufferException if the given output buffer is too small
299      * to hold the result.
300      * @exception ExemptionMechanismException if problem(s) encountered in the
301      * process of generating.
302      */
303     public final int genExemptionBlob(byte[] output)
304         throws IllegalStateException, ShortBufferException,
305         ExemptionMechanismException
306     { }
307 
308     /** 
309      * Generates the exemption mechanism key blob, and stores the result in
310      * the <code>output</code> buffer, starting at <code>outputOffset</code>
311      * inclusive.
312      *
313      * <p>If the <code>output</code> buffer is too small to hold the result,
314      * a <code>ShortBufferException</code> is thrown. In this case, repeat this
315      * call with a larger output buffer. Use
316      * {@link #getOutputSize(int) getOutputSize} to determine how big
317      * the output buffer should be.
318      *
319      * @param output the buffer for the result
320      * @param outputOffset the offset in <code>output</code> where the result
321      * is stored
322      *
323      * @return the number of bytes stored in <code>output</code>
324      *
325      * @exception IllegalStateException if this exemption mechanism is in
326      * a wrong state (e.g., has not been initialized).
327      * @exception ShortBufferException if the given output buffer is too small
328      * to hold the result.
329      * @exception ExemptionMechanismException if problem(s) encountered in the
330      * process of generating.
331      */
332     public final int genExemptionBlob(byte[] output, int outputOffset)
333         throws IllegalStateException, ShortBufferException,
334         ExemptionMechanismException
335     { }
336 
337     /** 
338      * Ensures that the key stored away by this ExemptionMechanism
339      * object will be wiped out when there are no more references to it.
340      */
341     protected void finalize() { }
342 }
343
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Java Books Remove Frame
Popular Tags