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     * @see <a href="http://en.wikipedia.org/wiki/Padding_(cryptography)">Wikipedia: Cryptographic Padding</a>
035     * @since 1.0
036     */
037    public enum PaddingScheme {
038    
039        /**
040         * No padding.  Useful when the block size is 8 bits for block cipher streaming operations. (Because
041         * a byte is the most primitive block size, there is nothing to pad).
042         */
043        NONE("NoPadding"),
044    
045        /**
046         * Padding scheme as defined in the W3C's &quot;XML Encryption Syntax and Processing&quot; document,
047         * <a href="http://www.w3.org/TR/xmlenc-core/#sec-Alg-Block">Section 5.2 - Block Encryption Algorithms</a>.
048         */
049        ISO10126("ISO10126Padding"),
050    
051        /**
052         * Optimal Asymmetric Encryption Padding defined in RSA's <a href="http://en.wikipedia.org/wiki/PKCS1">PKSC#1
053         * standard</a> (aka <a href="http://tools.ietf.org/html/rfc3447">RFC 3447</a>).
054         * <p/>
055         * <b>NOTE:</b> using this padding requires initializing {@link javax.crypto.Cipher Cipher} instances with a
056         * {@link javax.crypto.spec.OAEPParameterSpec OAEPParameterSpec} object which provides the 1) message digest and
057         * 2) mask generation function to use for the scheme.
058         * <h3>Convenient Alternatives</h3>
059         * While using this scheme enables you full customization of the message digest + mask generation function
060         * combination, it does require the extra burden of providing your own {@code OAEPParameterSpec} object.  This is
061         * often unnecessary, because most combinations are fairly standard.  These common combinations are pre-defined
062         * in this enum in the {@code OAEP}* variants.
063         * <p/>
064         * If you find that these common combinations still do not meet your needs, then you will need to
065         * specify your own message digest and mask generation function, either as an {@code OAEPParameterSpec} object
066         * during Cipher initialization or, maybe more easily, in the scheme name directly.  If you want to use scheme name
067         * approach, the name format is specified in the
068         * <a href="http://java.sun.com/javase/6/docs/technotes/guides/security/StandardNames.html">Standard Names</a>
069         * document in the <code>Cipher Algorithm Padding</code> section.
070         *
071         * @see #OAEPWithMd5AndMgf1
072         * @see #OAEPWithSha1AndMgf1
073         * @see #OAEPWithSha256AndMgf1
074         * @see #OAEPWithSha384AndMgf1
075         * @see #OAEPWithSha512AndMgf1
076         */
077        OAEP("OAEPPadding"),
078    
079        /**
080         * Optimal Asymmetric Encryption Padding with {@code MD5} message digest and {@code MGF1} mask generation function.
081         * <p/>
082         * This is a convenient pre-defined OAEP padding scheme that embeds the message digest and mask generation function.
083         * When using this padding scheme, there is no need to init the {@code Cipher} instance with an
084         * {@link javax.crypto.spec.OAEPParameterSpec OAEPParameterSpec} object, as it is already 'built in' to the scheme
085         * name (unlike the {@link #OAEP OAEP} scheme, which requires a bit more work).
086         */
087        OAEPWithMd5AndMgf1("OAEPWithMD5AndMGF1Padding"),
088    
089        /**
090         * Optimal Asymmetric Encryption Padding with {@code SHA-1} message digest and {@code MGF1} mask generation function.
091         * <p/>
092         * This is a convenient pre-defined OAEP padding scheme that embeds the message digest and mask generation function.
093         * When using this padding scheme, there is no need to init the {@code Cipher} instance with an
094         * {@link javax.crypto.spec.OAEPParameterSpec OAEPParameterSpec} object, as it is already 'built in' to the scheme
095         * name (unlike the {@link #OAEP OAEP} scheme, which requires a bit more work).
096         */
097        OAEPWithSha1AndMgf1("OAEPWithSHA-1AndMGF1Padding"),
098    
099        /**
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        private 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    }