45 * for the <code>Cipher</code> class.
46 * All the abstract methods in this class must be implemented by each
47 * cryptographic service provider who wishes to supply the implementation
48 * of a particular cipher algorithm.
49 *
50 * <p>In order to create an instance of <code>Cipher</code>, which
51 * encapsulates an instance of this <code>CipherSpi</code> class, an
52 * application calls one of the
53 * {@link Cipher#getInstance(java.lang.String) getInstance}
54 * factory methods of the
55 * {@link Cipher Cipher} engine class and specifies the requested
56 * <i>transformation</i>.
57 * Optionally, the application may also specify the name of a provider.
58 *
59 * <p>A <i>transformation</i> is a string that describes the operation (or
60 * set of operations) to be performed on the given input, to produce some
61 * output. A transformation always includes the name of a cryptographic
62 * algorithm (e.g., <i>DES</i>), and may be followed by a feedback mode and
63 * padding scheme.
64 *
65 * <p> A transformation is of the form:<p>
66 *
67 * <ul>
68 * <li>"<i>algorithm/mode/padding</i>" or
69 * <p>
70 * <li>"<i>algorithm</i>"
71 * </ul>
72 *
73 * <P> (in the latter case,
74 * provider-specific default values for the mode and padding scheme are used).
75 * For example, the following is a valid transformation:<p>
76 *
77 * <pre>
78 * Cipher c = Cipher.getInstance("<i>DES/CBC/PKCS5Padding</i>");
79 * </pre>
80 *
81 * <p>A provider may supply a separate class for each combination
82 * of <i>algorithm/mode/padding</i>, or may decide to provide more generic
83 * classes representing sub-transformations corresponding to
84 * <i>algorithm</i> or <i>algorithm/mode</i> or <i>algorithm//padding</i>
85 * (note the double slashes),
86 * in which case the requested mode and/or padding are set automatically by
87 * the <code>getInstance</code> methods of <code>Cipher</code>, which invoke
88 * the {@link #engineSetMode(java.lang.String) engineSetMode} and
89 * {@link #engineSetPadding(java.lang.String) engineSetPadding}
90 * methods of the provider's subclass of <code>CipherSpi</code>.
91 *
92 * <p>A <code>Cipher</code> property in a provider master class may have one of
93 * the following formats:
94 *
95 * <ul>
112 * <pre>
113 * // provider's subclass of "CipherSpi" implements "algName" with the
114 * // specified "padding", with pluggable mode
115 * <code>Cipher.</code><i>algName//padding</i>
116 * </pre>
117 *
118 * <li>
119 * <pre>
120 * // provider's subclass of "CipherSpi" implements "algName" with the
121 * // specified "mode" and "padding"
122 * <code>Cipher.</code><i>algName/mode/padding</i>
123 * </pre>
124 *
125 * </ul>
126 *
127 * <p>For example, a provider may supply a subclass of <code>CipherSpi</code>
128 * that implements <i>DES/ECB/PKCS5Padding</i>, one that implements
129 * <i>DES/CBC/PKCS5Padding</i>, one that implements
130 * <i>DES/CFB/PKCS5Padding</i>, and yet another one that implements
131 * <i>DES/OFB/PKCS5Padding</i>. That provider would have the following
132 * <code>Cipher</code> properties in its master class:<p>
133 *
134 * <ul>
135 *
136 * <li>
137 * <pre>
138 * <code>Cipher.</code><i>DES/ECB/PKCS5Padding</i>
139 * </pre>
140 *
141 * <li>
142 * <pre>
143 * <code>Cipher.</code><i>DES/CBC/PKCS5Padding</i>
144 * </pre>
145 *
146 * <li>
147 * <pre>
148 * <code>Cipher.</code><i>DES/CFB/PKCS5Padding</i>
149 * </pre>
150 *
151 * <li>
152 * <pre>
153 * <code>Cipher.</code><i>DES/OFB/PKCS5Padding</i>
154 * </pre>
155 *
156 * </ul>
157 *
158 * <p>Another provider may implement a class for each of the above modes
159 * (i.e., one class for <i>ECB</i>, one for <i>CBC</i>, one for <i>CFB</i>,
160 * and one for <i>OFB</i>), one class for <i>PKCS5Padding</i>,
161 * and a generic <i>DES</i> class that subclasses from <code>CipherSpi</code>.
162 * That provider would have the following
163 * <code>Cipher</code> properties in its master class:<p>
164 *
165 * <ul>
166 *
167 * <li>
168 * <pre>
169 * <code>Cipher.</code><i>DES</i>
170 * </pre>
171 *
172 * </ul>
173 *
174 * <p>The <code>getInstance</code> factory method of the <code>Cipher</code>
175 * engine class follows these rules in order to instantiate a provider's
176 * implementation of <code>CipherSpi</code> for a
177 * transformation of the form "<i>algorithm</i>":
178 *
179 * <ol>
180 * <li>
181 * Check if the provider has registered a subclass of <code>CipherSpi</code>
182 * for the specified "<i>algorithm</i>".
183 * <p>If the answer is YES, instantiate this
184 * class, for whose mode and padding scheme default values (as supplied by
185 * the provider) are used.
186 * <p>If the answer is NO, throw a <code>NoSuchAlgorithmException</code>
187 * exception.
188 * </ol>
189 *
190 * <p>The <code>getInstance</code> factory method of the <code>Cipher</code>
191 * engine class follows these rules in order to instantiate a provider's
192 * implementation of <code>CipherSpi</code> for a
193 * transformation of the form "<i>algorithm/mode/padding</i>":
194 *
195 * <ol>
196 * <li>
197 * Check if the provider has registered a subclass of <code>CipherSpi</code>
198 * for the specified "<i>algorithm/mode/padding</i>" transformation.
199 * <p>If the answer is YES, instantiate it.
200 * <p>If the answer is NO, go to the next step.<p>
201 * <li>
202 * Check if the provider has registered a subclass of <code>CipherSpi</code>
203 * for the sub-transformation "<i>algorithm/mode</i>".
204 * <p>If the answer is YES, instantiate it, and call
205 * <code>engineSetPadding(<i>padding</i>)</code> on the new instance.
206 * <p>If the answer is NO, go to the next step.<p>
207 * <li>
208 * Check if the provider has registered a subclass of <code>CipherSpi</code>
209 * for the sub-transformation "<i>algorithm//padding</i>" (note the double
210 * slashes).
211 * <p>If the answer is YES, instantiate it, and call
212 * <code>engineSetMode(<i>mode</i>)</code> on the new instance.
213 * <p>If the answer is NO, go to the next step.<p>
214 * <li>
215 * Check if the provider has registered a subclass of <code>CipherSpi</code>
216 * for the sub-transformation "<i>algorithm</i>".
217 * <p>If the answer is YES, instantiate it, and call
218 * <code>engineSetMode(<i>mode</i>)</code> and
219 * <code>engineSetPadding(<i>padding</i>)</code> on the new instance.
220 * <p>If the answer is NO, throw a <code>NoSuchAlgorithmException</code>
221 * exception.
222 * </ol>
223 *
224 * @author Jan Luehe
225 * @see KeyGenerator
226 * @see SecretKey
227 * @since 1.4
228 */
229
230 public abstract class CipherSpi {
231
232 /**
233 * Sets the mode of this cipher.
|
45 * for the <code>Cipher</code> class.
46 * All the abstract methods in this class must be implemented by each
47 * cryptographic service provider who wishes to supply the implementation
48 * of a particular cipher algorithm.
49 *
50 * <p>In order to create an instance of <code>Cipher</code>, which
51 * encapsulates an instance of this <code>CipherSpi</code> class, an
52 * application calls one of the
53 * {@link Cipher#getInstance(java.lang.String) getInstance}
54 * factory methods of the
55 * {@link Cipher Cipher} engine class and specifies the requested
56 * <i>transformation</i>.
57 * Optionally, the application may also specify the name of a provider.
58 *
59 * <p>A <i>transformation</i> is a string that describes the operation (or
60 * set of operations) to be performed on the given input, to produce some
61 * output. A transformation always includes the name of a cryptographic
62 * algorithm (e.g., <i>DES</i>), and may be followed by a feedback mode and
63 * padding scheme.
64 *
65 * <p> A transformation is of the form:
66 *
67 * <ul>
68 * <li>"<i>algorithm/mode/padding</i>" or
69 *
70 * <li>"<i>algorithm</i>"
71 * </ul>
72 *
73 * <P> (in the latter case,
74 * provider-specific default values for the mode and padding scheme are used).
75 * For example, the following is a valid transformation:
76 *
77 * <pre>
78 * Cipher c = Cipher.getInstance("<i>DES/CBC/PKCS5Padding</i>");
79 * </pre>
80 *
81 * <p>A provider may supply a separate class for each combination
82 * of <i>algorithm/mode/padding</i>, or may decide to provide more generic
83 * classes representing sub-transformations corresponding to
84 * <i>algorithm</i> or <i>algorithm/mode</i> or <i>algorithm//padding</i>
85 * (note the double slashes),
86 * in which case the requested mode and/or padding are set automatically by
87 * the <code>getInstance</code> methods of <code>Cipher</code>, which invoke
88 * the {@link #engineSetMode(java.lang.String) engineSetMode} and
89 * {@link #engineSetPadding(java.lang.String) engineSetPadding}
90 * methods of the provider's subclass of <code>CipherSpi</code>.
91 *
92 * <p>A <code>Cipher</code> property in a provider master class may have one of
93 * the following formats:
94 *
95 * <ul>
112 * <pre>
113 * // provider's subclass of "CipherSpi" implements "algName" with the
114 * // specified "padding", with pluggable mode
115 * <code>Cipher.</code><i>algName//padding</i>
116 * </pre>
117 *
118 * <li>
119 * <pre>
120 * // provider's subclass of "CipherSpi" implements "algName" with the
121 * // specified "mode" and "padding"
122 * <code>Cipher.</code><i>algName/mode/padding</i>
123 * </pre>
124 *
125 * </ul>
126 *
127 * <p>For example, a provider may supply a subclass of <code>CipherSpi</code>
128 * that implements <i>DES/ECB/PKCS5Padding</i>, one that implements
129 * <i>DES/CBC/PKCS5Padding</i>, one that implements
130 * <i>DES/CFB/PKCS5Padding</i>, and yet another one that implements
131 * <i>DES/OFB/PKCS5Padding</i>. That provider would have the following
132 * <code>Cipher</code> properties in its master class:
133 *
134 * <ul>
135 *
136 * <li>
137 * <pre>
138 * <code>Cipher.</code><i>DES/ECB/PKCS5Padding</i>
139 * </pre>
140 *
141 * <li>
142 * <pre>
143 * <code>Cipher.</code><i>DES/CBC/PKCS5Padding</i>
144 * </pre>
145 *
146 * <li>
147 * <pre>
148 * <code>Cipher.</code><i>DES/CFB/PKCS5Padding</i>
149 * </pre>
150 *
151 * <li>
152 * <pre>
153 * <code>Cipher.</code><i>DES/OFB/PKCS5Padding</i>
154 * </pre>
155 *
156 * </ul>
157 *
158 * <p>Another provider may implement a class for each of the above modes
159 * (i.e., one class for <i>ECB</i>, one for <i>CBC</i>, one for <i>CFB</i>,
160 * and one for <i>OFB</i>), one class for <i>PKCS5Padding</i>,
161 * and a generic <i>DES</i> class that subclasses from <code>CipherSpi</code>.
162 * That provider would have the following
163 * <code>Cipher</code> properties in its master class:
164 *
165 * <ul>
166 *
167 * <li>
168 * <pre>
169 * <code>Cipher.</code><i>DES</i>
170 * </pre>
171 *
172 * </ul>
173 *
174 * <p>The <code>getInstance</code> factory method of the <code>Cipher</code>
175 * engine class follows these rules in order to instantiate a provider's
176 * implementation of <code>CipherSpi</code> for a
177 * transformation of the form "<i>algorithm</i>":
178 *
179 * <ol>
180 * <li>
181 * Check if the provider has registered a subclass of <code>CipherSpi</code>
182 * for the specified "<i>algorithm</i>".
183 * <p>If the answer is YES, instantiate this
184 * class, for whose mode and padding scheme default values (as supplied by
185 * the provider) are used.
186 * <p>If the answer is NO, throw a <code>NoSuchAlgorithmException</code>
187 * exception.
188 * </ol>
189 *
190 * <p>The <code>getInstance</code> factory method of the <code>Cipher</code>
191 * engine class follows these rules in order to instantiate a provider's
192 * implementation of <code>CipherSpi</code> for a
193 * transformation of the form "<i>algorithm/mode/padding</i>":
194 *
195 * <ol>
196 * <li>
197 * Check if the provider has registered a subclass of <code>CipherSpi</code>
198 * for the specified "<i>algorithm/mode/padding</i>" transformation.
199 * <p>If the answer is YES, instantiate it.
200 * <p>If the answer is NO, go to the next step.
201 * <li>
202 * Check if the provider has registered a subclass of <code>CipherSpi</code>
203 * for the sub-transformation "<i>algorithm/mode</i>".
204 * <p>If the answer is YES, instantiate it, and call
205 * <code>engineSetPadding(<i>padding</i>)</code> on the new instance.
206 * <p>If the answer is NO, go to the next step.
207 * <li>
208 * Check if the provider has registered a subclass of <code>CipherSpi</code>
209 * for the sub-transformation "<i>algorithm//padding</i>" (note the double
210 * slashes).
211 * <p>If the answer is YES, instantiate it, and call
212 * <code>engineSetMode(<i>mode</i>)</code> on the new instance.
213 * <p>If the answer is NO, go to the next step.
214 * <li>
215 * Check if the provider has registered a subclass of <code>CipherSpi</code>
216 * for the sub-transformation "<i>algorithm</i>".
217 * <p>If the answer is YES, instantiate it, and call
218 * <code>engineSetMode(<i>mode</i>)</code> and
219 * <code>engineSetPadding(<i>padding</i>)</code> on the new instance.
220 * <p>If the answer is NO, throw a <code>NoSuchAlgorithmException</code>
221 * exception.
222 * </ol>
223 *
224 * @author Jan Luehe
225 * @see KeyGenerator
226 * @see SecretKey
227 * @since 1.4
228 */
229
230 public abstract class CipherSpi {
231
232 /**
233 * Sets the mode of this cipher.
|