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 module hunt.shiro.crypto.PaddingScheme; 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 enum PaddingScheme : string { 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 // 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 }