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