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 import javax.crypto.spec.GCMParameterSpec;
22 import java.security.spec.AlgorithmParameterSpec;
23
24 /**
25 * {@code CipherService} using the {@code AES} cipher algorithm for all encryption, decryption, and key operations.
26 * <p/>
27 * The AES algorithm can support key sizes of {@code 128}, {@code 192} and {@code 256} bits<b>*</b>. This implementation
28 * defaults to 128 bits.
29 * <p/>
30 * Note that this class retains changes the parent class's default
31 * {@link OperationMode#CBC CBC} modeto {@link OperationMode#GCM GCM} of operation
32 * instead of the typical JDK default of {@link OperationMode#ECB ECB}.
33 * {@code ECB} should not be used in security-sensitive environments because {@code ECB}
34 * does not allow for initialization vectors, which are considered necessary for strong encryption.
35 * See the {@link DefaultBlockCipherService parent class}'s JavaDoc and the
36 * {@link JcaCipherService JcaCipherService} JavaDoc for more on why the JDK default should not be used and is not
37 * used in this implementation.
38 * <p/>
39 * <b>*</b> Generating and using AES key sizes greater than 128 require installation of the
40 * <a href="http://java.sun.com/javase/downloads/index.jsp">Java Cryptography Extension (JCE) Unlimited Strength
41 * Jurisdiction Policy files</a>.
42 *
43 * @since 1.0
44 */
45 public class AesCipherService extends DefaultBlockCipherService {
46
47 private static final String ALGORITHM_NAME = "AES";
48
49 /**
50 * Creates a new {@link CipherService} instance using the {@code AES} cipher algorithm with the following
51 * important cipher default attributes:
52 * <table>
53 * <tr>
54 * <th>Attribute</th>
55 * <th>Value</th>
56 * </tr>
57 * <tr>
58 * <td>{@link #setKeySize keySize}</td>
59 * <td>{@code 128} bits</td>
60 * </tr>
61 * <tr>
62 * <td>{@link #setBlockSize blockSize}</td>
63 * <td>{@code 128} bits (required for {@code AES}</td>
64 * </tr>
65 * <tr>
66 * <td>{@link #setMode mode}</td>
67 * <td>{@link OperationMode#GCM GCM}<b>*</b></td>
68 * </tr>
69 * <tr>
70 * <td>{@link #setPaddingScheme paddingScheme}</td>
71 * <td>{@link PaddingScheme#NONE NoPadding}***</td>
72 * </tr>
73 * <tr>
74 * <td>{@link #setInitializationVectorSize(int) initializationVectorSize}</td>
75 * <td>{@code 128} bits</td>
76 * </tr>
77 * <tr>
78 * <td>{@link #setGenerateInitializationVectors(boolean) generateInitializationVectors}</td>
79 * <td>{@code true}<b>**</b></td>
80 * </tr>
81 * </table>
82 * <p/>
83 * <b>*</b> The {@link OperationMode#GCM GCM} operation mode is used instead of the JDK default {@code ECB} to
84 * ensure strong encryption. {@code ECB} should not be used in security-sensitive environments - see the
85 * {@link DefaultBlockCipherService DefaultBlockCipherService} class JavaDoc's "Operation Mode" section
86 * for more.
87 * <p/>
88 * <b>**</b>In conjunction with the default {@code GCM} operation mode, initialization vectors are generated by
89 * default to ensure strong encryption. See the {@link JcaCipherService JcaCipherService} class JavaDoc for more.
90 * <p/>
91 * <b>**</b>Since {@code GCM} is a stream cipher, padding is implemented in the operation mode and an external padding scheme
92 * cannot be used in conjunction with {@code GCM}. In fact, {@code AES/GCM/PKCS5Padding} is just an alias in most JVM for
93 * {@code AES/GCM/NoPadding}.
94 * <p/>
95 * <b>NOTE:</b> As of Java 14, setting a streaming padding for the above example will throw a NoSuchAlgorithmException
96 *
97 * @see <a href="https://www.oracle.com/java/technologies/javase/14-relnote-issues.html#JDK-8180392">JDK-8180392</a>
98 */
99 public AesCipherService() {
100 super(ALGORITHM_NAME);
101 setMode(OperationMode.GCM);
102 setStreamingMode(OperationMode.GCM);
103 setPaddingScheme(PaddingScheme.NONE);
104 setStreamingPaddingScheme(PaddingScheme.NONE);
105 }
106
107 @Override
108 protected AlgorithmParameterSpec createParameterSpec(byte[] iv, boolean streaming) {
109
110 if ((streaming && OperationMode.GCM.name().equals(getStreamingModeName()))
111 || (!streaming && OperationMode.GCM.name().equals(getModeName()))) {
112 return new GCMParameterSpec(getKeySize(), iv);
113 }
114
115 return super.createParameterSpec(iv, streaming);
116 }
117 }