ExemptionMechanismSpi


1   /*
2    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
3    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
4    */
5   
6   /*
7    * @(#)ExemptionMechanismSpi.java   1.6 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.Key;
21  import java.security.AlgorithmParameters;
22  import java.security.InvalidKeyException;
23  import java.security.InvalidAlgorithmParameterException;
24  import java.security.spec.AlgorithmParameterSpec;
25  
26  /** 
27   * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
28   * for the <code>ExemptionMechanism</code> class.
29   * All the abstract methods in this class must be implemented by each
30   * cryptographic service provider who wishes to supply the implementation
31   * of a particular exemption mechanism.
32   *
33   * @author Sharon Liu
34   *
35   * @version 1.6, 07/23/01
36   *
37   * @since 1.4
38   */
39  public abstract class ExemptionMechanismSpi
40  {
41  
42      public ExemptionMechanismSpi() { }
43  
44      /** 
45       * Returns the length in bytes that an output buffer would need to be in
46       * order to hold the result of the next
47       * {@link #engineGenExemptionBlob(byte[], int) engineGenExemptionBlob}
48       * operation, given the input length <code>inputLen</code> (in bytes).
49       *
50       * <p>The actual output length of the next
51       * {@link #engineGenExemptionBlob(byte[], int) engineGenExemptionBlob}
52       * call may be smaller than the length returned by this method.
53       *
54       * @param inputLen the input length (in bytes)
55       *
56       * @return the required output buffer size (in bytes)
57       */
58      protected abstract int engineGetOutputSize(int inputLen);
59  
60      /** 
61       * Initializes this exemption mechanism with a key.
62       *
63       * <p>If this exemption mechanism requires any algorithm parameters
64       * that cannot be derived from the given <code>key</code>, the underlying
65       * exemption mechanism implementation is supposed to generate the required
66       * parameters itself (using provider-specific default values); in the case
67       * that algorithm parameters must be specified by the caller, an
68       * <code>InvalidKeyException</code> is raised.
69       *
70       * @param key the key for this exemption mechanism
71       *
72       * @exception InvalidKeyException if the given key is inappropriate for
73       * this exemption mechanism.
74       * @exception ExemptionMechanismException if problem(s) encountered in the
75       * process of initializing.
76       */
77      protected abstract void engineInit(Key key)
78          throws InvalidKeyException, ExemptionMechanismException;
79  
80      /** 
81       * Initializes this exemption mechanism with a key and a set of algorithm
82       * parameters.
83       *
84       * <p>If this exemption mechanism requires any algorithm parameters and
85       * <code>params</code> is null, the underlying exemption mechanism
86       * implementation is supposed to generate the required parameters
87       * itself (using provider-specific default values); in the case that
88       * algorithm parameters must be specified by the caller, an
89       * <code>InvalidAlgorithmParameterException</code> is raised.
90       *
91       * @param key the key for this exemption mechanism
92       * @param params the algorithm parameters
93       *
94       * @exception InvalidKeyException if the given key is inappropriate for
95       * this exemption mechanism.
96       * @exception InvalidAlgorithmParameterException if the given algorithm
97       * parameters are inappropriate for this exemption mechanism.
98       * @exception ExemptionMechanismException if problem(s) encountered in the
99       * process of initializing.
100      */
101     protected abstract void engineInit(Key key, AlgorithmParameterSpec params)
102         throws InvalidKeyException, InvalidAlgorithmParameterException,
103         ExemptionMechanismException;
104 
105     /** 
106      * Initializes this exemption mechanism with a key and a set of algorithm
107      * parameters.
108      *
109      * <p>If this exemption mechanism requires any algorithm parameters
110      * and <code>params</code> is null, the underlying exemption mechanism
111      * implementation is supposed to generate the required parameters
112      * itself (using provider-specific default values); in the case that
113      * algorithm parameters must be specified by the caller, an
114      * <code>InvalidAlgorithmParameterException</code> is raised.
115      *
116      * @param key the key for this exemption mechanism
117      * @param params the algorithm parameters
118      *
119      * @exception InvalidKeyException if the given key is inappropriate for
120      * this exemption mechanism.
121      * @exception InvalidAlgorithmParameterException if the given algorithm
122      * parameters are inappropriate for this exemption mechanism.
123      * @exception ExemptionMechanismException if problem(s) encountered in the
124      * process of initializing.
125      */
126     protected abstract void engineInit(Key key, AlgorithmParameters params)
127         throws InvalidKeyException, InvalidAlgorithmParameterException,
128         ExemptionMechanismException;
129 
130     /** 
131      * Generates the exemption mechanism key blob.
132      *
133      * @return the new buffer with the result key blob.
134      *
135      * @exception ExemptionMechanismException if problem(s) encountered in the
136      * process of generating.
137      */
138     protected abstract byte[] engineGenExemptionBlob()
139         throws ExemptionMechanismException;
140 
141     /** 
142      * Generates the exemption mechanism key blob, and stores the result in
143      * the <code>output</code> buffer, starting at <code>outputOffset</code>
144      * inclusive.
145      *
146      * <p>If the <code>output</code> buffer is too small to hold the result,
147      * a <code>ShortBufferException</code> is thrown. In this case, repeat this
148      * call with a larger output buffer. Use
149      * {@link #engineGetOutputSize(int) engineGetOutputSize} to determine
150      * how big the output buffer should be.
151      *
152      * @param output the buffer for the result
153      * @param outputOffset the offset in <code>output</code> where the result
154      * is stored
155      *
156      * @return the number of bytes stored in <code>output</code>
157      *
158      * @exception ShortBufferException if the given output buffer is too small
159      * to hold the result.
160      * @exception ExemptionMechanismException if problem(s) encountered in the
161      * process of generating.
162      */
163     protected abstract int engineGenExemptionBlob(byte[] output, int
164         outputOffset) throws ShortBufferException, ExemptionMechanismException;
165 }
166
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Java Books Remove Frame
Popular Tags