View Javadoc

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;
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 &quot;XML Encryption Syntax and Processing&quot; 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     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 }