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. |