1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.shiro.crypto.cipher;
20
21 /**
22 * A {@code CipherPaddingScheme} represents well-known
23 * <a href="http://en.wikipedia.org/wiki/Padding_(cryptography)">padding schemes</a> supported by JPA providers in a
24 * type-safe manner.
25 * <p/>
26 * When encrypted data is transferred, it is usually desirable to ensure that all 'chunks' transferred are a fixed-length:
27 * different length blocks might give cryptanalysts clues about what the data might be, among other reasons. Of course
28 * not all data will convert to neat fixed-length blocks, so padding schemes are used to 'fill in' (pad) any remaining
29 * space with unintelligible data.
30 * <p/>
31 * Padding schemes can be used in both asymmetric key ciphers as well as symmetric key ciphers (e.g. block ciphers).
32 * Block-ciphers especially regularly use padding schemes as they are based on the notion of fixed-length block sizes.
33 *
34 * @see <a href="http://en.wikipedia.org/wiki/Padding_(cryptography)">Wikipedia: Cryptographic Padding</a>
35 * @since 1.0
36 */
37 public enum PaddingScheme {
38
39 /**
40 * No padding. Useful when the block size is 8 bits for block cipher streaming operations. (Because
41 * a byte is the most primitive block size, there is nothing to pad).
42 */
43 NONE("NoPadding"),
44
45 /**
46 * Padding scheme as defined in the W3C's "XML Encryption Syntax and Processing" document,
47 * <a href="http://www.w3.org/TR/xmlenc-core/#sec-Alg-Block">Section 5.2 - Block Encryption Algorithms</a>.
48 */
49 ISO10126("ISO10126Padding"),
50
51 /**
52 * Optimal Asymmetric Encryption Padding defined in RSA's <a href="http://en.wikipedia.org/wiki/PKCS1">PKSC#1
53 * standard</a> (aka <a href="http://tools.ietf.org/html/rfc3447">RFC 3447</a>).
54 * <p/>
55 * <b>NOTE:</b> using this padding requires initializing {@link javax.crypto.Cipher Cipher} instances with a
56 * {@link javax.crypto.spec.OAEPParameterSpec OAEPParameterSpec} object which provides the 1) message digest and
57 * 2) mask generation function to use for the scheme.
58 * <h3>Convenient Alternatives</h3>
59 * While using this scheme enables you full customization of the message digest + mask generation function
60 * combination, it does require the extra burden of providing your own {@code OAEPParameterSpec} object. This is
61 * often unnecessary, because most combinations are fairly standard. These common combinations are pre-defined
62 * in this enum in the {@code OAEP}* variants.
63 * <p/>
64 * If you find that these common combinations still do not meet your needs, then you will need to
65 * specify your own message digest and mask generation function, either as an {@code OAEPParameterSpec} object
66 * during Cipher initialization or, maybe more easily, in the scheme name directly. If you want to use scheme name
67 * approach, the name format is specified in the
68 * <a href="http://java.sun.com/javase/6/docs/technotes/guides/security/StandardNames.html">Standard Names</a>
69 * document in the <code>Cipher Algorithm Padding</code> section.
70 *
71 * @see #OAEPWithMd5AndMgf1
72 * @see #OAEPWithSha1AndMgf1
73 * @see #OAEPWithSha256AndMgf1
74 * @see #OAEPWithSha384AndMgf1
75 * @see #OAEPWithSha512AndMgf1
76 */
77 OAEP("OAEPPadding"),
78
79 /**
80 * Optimal Asymmetric Encryption Padding with {@code MD5} message digest and {@code MGF1} mask generation function.
81 * <p/>
82 * This is a convenient pre-defined OAEP padding scheme that embeds the message digest and mask generation function.
83 * When using this padding scheme, there is no need to init the {@code Cipher} instance with an
84 * {@link javax.crypto.spec.OAEPParameterSpec OAEPParameterSpec} object, as it is already 'built in' to the scheme
85 * name (unlike the {@link #OAEP OAEP} scheme, which requires a bit more work).
86 */
87 OAEPWithMd5AndMgf1("OAEPWithMD5AndMGF1Padding"),
88
89 /**
90 * Optimal Asymmetric Encryption Padding with {@code SHA-1} message digest and {@code MGF1} mask generation function.
91 * <p/>
92 * This is a convenient pre-defined OAEP padding scheme that embeds the message digest and mask generation function.
93 * When using this padding scheme, there is no need to init the {@code Cipher} instance with an
94 * {@link javax.crypto.spec.OAEPParameterSpec OAEPParameterSpec} object, as it is already 'built in' to the scheme
95 * name (unlike the {@link #OAEP OAEP} scheme, which requires a bit more work).
96 */
97 OAEPWithSha1AndMgf1("OAEPWithSHA-1AndMGF1Padding"),
98
99 /**
100 * Optimal Asymmetric Encryption Padding with {@code SHA-256} message digest and {@code MGF1} mask generation function.
101 * <p/>
102 * This is a convenient pre-defined OAEP padding scheme that embeds the message digest and mask generation function.
103 * When using this padding scheme, there is no need to init the {@code Cipher} instance with an
104 * {@link javax.crypto.spec.OAEPParameterSpec OAEPParameterSpec} object, as it is already 'built in' to the scheme
105 * name (unlike the {@link #OAEP OAEP} scheme, which requires a bit more work).
106 */
107 OAEPWithSha256AndMgf1("OAEPWithSHA-256AndMGF1Padding"),
108
109 /**
110 * Optimal Asymmetric Encryption Padding with {@code SHA-384} message digest and {@code MGF1} mask generation function.
111 * <p/>
112 * This is a convenient pre-defined OAEP padding scheme that embeds the message digest and mask generation function.
113 * When using this padding scheme, there is no need to init the {@code Cipher} instance with an
114 * {@link javax.crypto.spec.OAEPParameterSpec OAEPParameterSpec} object, as it is already 'built in' to the scheme
115 * name (unlike the {@link #OAEP OAEP} scheme, which requires a bit more work).
116 */
117 OAEPWithSha384AndMgf1("OAEPWithSHA-384AndMGF1Padding"),
118
119 /**
120 * Optimal Asymmetric Encryption Padding with {@code SHA-512} message digest and {@code MGF1} mask generation function.
121 * <p/>
122 * This is a convenient pre-defined OAEP padding scheme that embeds the message digest and mask generation function.
123 * When using this padding scheme, there is no need to init the {@code Cipher} instance with an
124 * {@link javax.crypto.spec.OAEPParameterSpec OAEPParameterSpec} object, as it is already 'built in' to the scheme
125 * name (unlike the {@link #OAEP OAEP} scheme, which requires a bit more work).
126 */
127 OAEPWithSha512AndMgf1("OAEPWithSHA-512AndMGF1Padding"),
128
129 /**
130 * Padding scheme used with the {@code RSA} algorithm defined in RSA's
131 * <a href="http://en.wikipedia.org/wiki/PKCS1">PKSC#1 standard</a> (aka
132 * <a href="http://tools.ietf.org/html/rfc3447">RFC 3447</a>).
133 */
134 PKCS1("PKCS1Padding"),
135
136 /**
137 * Padding scheme defined in RSA's <a href="http://www.rsa.com/rsalabs/node.asp?id=2127">Password-Based
138 * Cryptography Standard</a>.
139 */
140 PKCS5("PKCS5Padding"),
141
142 /**
143 * Padding scheme defined in the <a href="http://www.mozilla.org/projects/security/pki/nss/ssl/draft302.txt">SSL
144 * 3.0 specification</a>, section <code>5.2.3.2 (CBC block cipher)</code>.
145 */
146 SSL3("SSL3Padding");
147
148 private final String transformationName;
149
150 PaddingScheme(String transformationName) {
151 this.transformationName = transformationName;
152 }
153
154 /**
155 * Returns the actual string name to use when building the {@link javax.crypto.Cipher Cipher}
156 * {@code transformation string}.
157 *
158 * @return the actual string name to use when building the {@link javax.crypto.Cipher Cipher}
159 * {@code transformation string}.
160 * @see javax.crypto.Cipher#getInstance(String)
161 */
162 public String getTransformationName() {
163 return this.transformationName;
164 }
165 }