001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019 package org.apache.shiro.crypto;
020
021 /**
022 * A {@code CipherPaddingScheme} represents well-known
023 * <a href="http://en.wikipedia.org/wiki/Padding_(cryptography)">padding schemes</a> supported by JPA providers in a
024 * type-safe manner.
025 * <p/>
026 * When encrypted data is transferred, it is usually desirable to ensure that all 'chunks' transferred are a fixed-length:
027 * different length blocks might give cryptanalysts clues about what the data might be, among other reasons. Of course
028 * not all data will convert to neat fixed-length blocks, so padding schemes are used to 'fill in' (pad) any remaining
029 * space with unintelligible data.
030 * <p/>
031 * Padding schemes can be used in both asymmetric key ciphers as well as symmetric key ciphers (e.g. block ciphers).
032 * Block-ciphers especially regularly use padding schemes as they are based on the notion of fixed-length block sizes.
033 *
034 * @author Les Hazlewood
035 * @see <a href="http://en.wikipedia.org/wiki/Padding_(cryptography)">Wikipedia: Cryptographic Padding</a>
036 * @since 1.0
037 */
038 public enum PaddingScheme {
039
040 /**
041 * No padding. Useful when the block size is 8 bits for block cipher streaming operations. (Because
042 * a byte is the most primitive block size, there is nothing to pad).
043 */
044 NONE("NoPadding"),
045
046 /**
047 * Padding scheme as defined in the W3C's "XML Encryption Syntax and Processing" document,
048 * <a href="http://www.w3.org/TR/xmlenc-core/#sec-Alg-Block">Section 5.2 - Block Encryption Algorithms</a>.
049 */
050 ISO10126("ISO10126Padding"),
051
052 /**
053 * Optimal Asymmetric Encryption Padding defined in RSA's <a href="http://en.wikipedia.org/wiki/PKCS1">PKSC#1
054 * standard</a> (aka <a href="http://tools.ietf.org/html/rfc3447">RFC 3447</a>).
055 * <p/>
056 * <b>NOTE:</b> using this padding requires initializing {@link javax.crypto.Cipher Cipher} instances with a
057 * {@link javax.crypto.spec.OAEPParameterSpec OAEPParameterSpec} object which provides the 1) message digest and
058 * 2) mask generation function to use for the scheme.
059 * <h3>Convenient Alternatives</h3>
060 * While using this scheme enables you full customization of the message digest + mask generation function
061 * combination, it does require the extra burden of providing your own {@code OAEPParameterSpec} object. This is
062 * often unnecessary, because most combinations are fairly standard. These common combinations are pre-defined
063 * in this enum in the {@code OAEP}* variants.
064 * <p/>
065 * If you find that these common combinations still do not meet your needs, then you will need to
066 * specify your own message digest and mask generation function, either as an {@code OAEPParameterSpec} object
067 * during Cipher initialization or, maybe more easily, in the scheme name directly. If you want to use scheme name
068 * approach, the name format is specified in the
069 * <a href="http://java.sun.com/javase/6/docs/technotes/guides/security/StandardNames.html">Standard Names</a>
070 * document in the <code>Cipher Algorithm Padding</code> section.
071 *
072 * @see #OAEPWithMd5AndMgf1
073 * @see #OAEPWithSha1AndMgf1
074 * @see #OAEPWithSha256AndMgf1
075 * @see #OAEPWithSha384AndMgf1
076 * @see #OAEPWithSha512AndMgf1
077 */
078 OAEP("OAEPPadding"),
079
080 /**
081 * Optimal Asymmetric Encryption Padding with {@code MD5} message digest and {@code MGF1} mask generation function.
082 * <p/>
083 * This is a convenient pre-defined OAEP padding scheme that embeds the message digest and mask generation function.
084 * When using this padding scheme, there is no need to init the {@code Cipher} instance with an
085 * {@link javax.crypto.spec.OAEPParameterSpec OAEPParameterSpec} object, as it is already 'built in' to the scheme
086 * name (unlike the {@link #OAEP OAEP} scheme, which requires a bit more work).
087 */
088 OAEPWithMd5AndMgf1("OAEPWithMD5AndMGF1Padding"),
089
090 /**
091 * Optimal Asymmetric Encryption Padding with {@code SHA-1} message digest and {@code MGF1} mask generation function.
092 * <p/>
093 * This is a convenient pre-defined OAEP padding scheme that embeds the message digest and mask generation function.
094 * When using this padding scheme, there is no need to init the {@code Cipher} instance with an
095 * {@link javax.crypto.spec.OAEPParameterSpec OAEPParameterSpec} object, as it is already 'built in' to the scheme
096 * name (unlike the {@link #OAEP OAEP} scheme, which requires a bit more work).
097 */
098 OAEPWithSha1AndMgf1("OAEPWithSHA-1AndMGF1Padding"),
099
100 /**
101 * Optimal Asymmetric Encryption Padding with {@code SHA-256} message digest and {@code MGF1} mask generation function.
102 * <p/>
103 * This is a convenient pre-defined OAEP padding scheme that embeds the message digest and mask generation function.
104 * When using this padding scheme, there is no need to init the {@code Cipher} instance with an
105 * {@link javax.crypto.spec.OAEPParameterSpec OAEPParameterSpec} object, as it is already 'built in' to the scheme
106 * name (unlike the {@link #OAEP OAEP} scheme, which requires a bit more work).
107 */
108 OAEPWithSha256AndMgf1("OAEPWithSHA-256AndMGF1Padding"),
109
110 /**
111 * Optimal Asymmetric Encryption Padding with {@code SHA-384} message digest and {@code MGF1} mask generation function.
112 * <p/>
113 * This is a convenient pre-defined OAEP padding scheme that embeds the message digest and mask generation function.
114 * When using this padding scheme, there is no need to init the {@code Cipher} instance with an
115 * {@link javax.crypto.spec.OAEPParameterSpec OAEPParameterSpec} object, as it is already 'built in' to the scheme
116 * name (unlike the {@link #OAEP OAEP} scheme, which requires a bit more work).
117 */
118 OAEPWithSha384AndMgf1("OAEPWithSHA-384AndMGF1Padding"),
119
120 /**
121 * Optimal Asymmetric Encryption Padding with {@code SHA-512} message digest and {@code MGF1} mask generation function.
122 * <p/>
123 * This is a convenient pre-defined OAEP padding scheme that embeds the message digest and mask generation function.
124 * When using this padding scheme, there is no need to init the {@code Cipher} instance with an
125 * {@link javax.crypto.spec.OAEPParameterSpec OAEPParameterSpec} object, as it is already 'built in' to the scheme
126 * name (unlike the {@link #OAEP OAEP} scheme, which requires a bit more work).
127 */
128 OAEPWithSha512AndMgf1("OAEPWithSHA-512AndMGF1Padding"),
129
130 /**
131 * Padding scheme used with the {@code RSA} algorithm defined in RSA's
132 * <a href="http://en.wikipedia.org/wiki/PKCS1">PKSC#1 standard</a> (aka
133 * <a href="http://tools.ietf.org/html/rfc3447">RFC 3447</a>).
134 */
135 PKCS1("PKCS1Padding"),
136
137 /**
138 * Padding scheme defined in RSA's <a href="http://www.rsa.com/rsalabs/node.asp?id=2127">Password-Based
139 * Cryptography Standard</a>.
140 */
141 PKCS5("PKCS5Padding"),
142
143 /**
144 * Padding scheme defined in the <a href="http://www.mozilla.org/projects/security/pki/nss/ssl/draft302.txt">SSL
145 * 3.0 specification</a>, section <code>5.2.3.2 (CBC block cipher)</code>.
146 */
147 SSL3("SSL3Padding");
148
149 private final String transformationName;
150
151 private PaddingScheme(String transformationName) {
152 this.transformationName = transformationName;
153 }
154
155 /**
156 * Returns the actual string name to use when building the {@link javax.crypto.Cipher Cipher}
157 * {@code transformation string}.
158 *
159 * @return the actual string name to use when building the {@link javax.crypto.Cipher Cipher}
160 * {@code transformation string}.
161 * @see javax.crypto.Cipher#getInstance(String)
162 */
163 public String getTransformationName() {
164 return this.transformationName;
165 }
166 }