001/*
002 * nimbus-jose-jwt
003 *
004 * Copyright 2012-2016, Connect2id Ltd.
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use
007 * this file except in compliance with the License. You may obtain a copy of the
008 * License at
009 *
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software distributed
013 * under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
014 * CONDITIONS OF ANY KIND, either express or implied. See the License for the
015 * specific language governing permissions and limitations under the License.
016 */
017
018package com.nimbusds.jose.crypto;
019
020
021import java.util.Set;
022
023import javax.crypto.SecretKey;
024import javax.crypto.spec.SecretKeySpec;
025
026import com.nimbusds.jose.crypto.impl.*;
027import net.jcip.annotations.ThreadSafe;
028
029import com.nimbusds.jose.*;
030import com.nimbusds.jose.jwk.OctetSequenceKey;
031import com.nimbusds.jose.util.Base64URL;
032
033
034/**
035 * AES and AES GCM key wrap decrypter of {@link com.nimbusds.jose.JWEObject JWE
036 * objects}. Expects an AES key.
037 *
038 * <p>Unwraps the encrypted Content Encryption Key (CEK) with the specified AES
039 * key, and then uses the CEK along with the IV and authentication tag to
040 * decrypt the cipher text. See RFC 7518, sections
041 * <a href="https://tools.ietf.org/html/rfc7518#section-4.4">4.4</a> and
042 * <a href="https://tools.ietf.org/html/rfc7518#section-4.7">4.7</a> for more
043 * information.
044 *
045 * <p>This class is thread-safe.
046 *
047 * <p>Supports the following key management algorithms:
048 *
049 * <ul>
050 *     <li>{@link com.nimbusds.jose.JWEAlgorithm#A128KW}
051 *     <li>{@link com.nimbusds.jose.JWEAlgorithm#A192KW}
052 *     <li>{@link com.nimbusds.jose.JWEAlgorithm#A256KW}
053 *     <li>{@link com.nimbusds.jose.JWEAlgorithm#A128GCMKW}
054 *     <li>{@link com.nimbusds.jose.JWEAlgorithm#A192GCMKW}
055 *     <li>{@link com.nimbusds.jose.JWEAlgorithm#A256GCMKW}
056 * </ul>
057 *
058 * <p>Supports the following content encryption algorithms:
059 *
060 * <ul>
061 *     <li>{@link com.nimbusds.jose.EncryptionMethod#A128CBC_HS256}
062 *     <li>{@link com.nimbusds.jose.EncryptionMethod#A192CBC_HS384}
063 *     <li>{@link com.nimbusds.jose.EncryptionMethod#A256CBC_HS512}
064 *     <li>{@link com.nimbusds.jose.EncryptionMethod#A128GCM}
065 *     <li>{@link com.nimbusds.jose.EncryptionMethod#A192GCM}
066 *     <li>{@link com.nimbusds.jose.EncryptionMethod#A256GCM}
067 *     <li>{@link com.nimbusds.jose.EncryptionMethod#A128CBC_HS256_DEPRECATED}
068 *     <li>{@link com.nimbusds.jose.EncryptionMethod#A256CBC_HS512_DEPRECATED}
069 * </ul>
070 *
071 * @author Melisa Halsband
072 * @author Vladimir Dzhuvinov
073 * @version 2015-06-29
074 */
075@ThreadSafe
076public class AESDecrypter extends AESCryptoProvider implements JWEDecrypter, CriticalHeaderParamsAware {
077
078
079        /**
080         * The critical header policy.
081         */
082        private final CriticalHeaderParamsDeferral critPolicy = new CriticalHeaderParamsDeferral();
083
084
085        /**
086         * Creates a new AES decrypter.
087         *
088         * @param kek The Key Encrypting Key. Must be 128 bits (16 bytes), 192
089         *            bits (24 bytes) or 256 bits (32 bytes). Must not be
090         *            {@code null}.
091         *
092         * @throws KeyLengthException If the KEK length is invalid.
093         */
094        public AESDecrypter(final SecretKey kek)
095                throws KeyLengthException {
096
097                this(kek, null);
098        }
099
100
101        /**
102         * Creates a new AES decrypter.
103         *
104         * @param keyBytes The Key Encrypting Key, as a byte array. Must be 128
105         *                 bits (16 bytes), 192 bits (24 bytes) or 256 bits (32
106         *                 bytes). Must not be {@code null}.
107         *
108         * @throws KeyLengthException If the KEK length is invalid.
109         */
110        public AESDecrypter(final byte[] keyBytes)
111                throws KeyLengthException {
112
113                this(new SecretKeySpec(keyBytes, "AES"));
114        }
115
116
117        /**
118         * Creates a new AES decrypter.
119         *
120         * @param octJWK The Key Encryption Key, as a JWK. Must be 128 bits (16
121         *               bytes), 192 bits (24 bytes), 256 bits (32 bytes), 384
122         *               bits (48 bytes) or 512 bits (64 bytes) long. Must not
123         *               be {@code null}.
124         *
125         * @throws KeyLengthException If the KEK length is invalid.
126         */
127        public AESDecrypter(final OctetSequenceKey octJWK)
128                throws KeyLengthException {
129
130                this(octJWK.toSecretKey("AES"));
131        }
132
133
134        /**
135         * Creates a new AES decrypter.
136         *
137         * @param kek            The Key Encrypting Key. Must be 128 bits (16
138         *                       bytes), 192 bits (24 bytes) or 256 bits (32
139         *                       bytes). Must not be {@code null}.
140         * @param defCritHeaders The names of the critical header parameters
141         *                       that are deferred to the application for
142         *                       processing, empty set or {@code null} if none.
143         *
144         * @throws KeyLengthException If the KEK length is invalid.
145         */
146        public AESDecrypter(final SecretKey kek, final Set<String> defCritHeaders)
147                throws KeyLengthException {
148
149                super(kek);
150
151                critPolicy.setDeferredCriticalHeaderParams(defCritHeaders);
152        }
153
154
155        @Override
156        public Set<String> getProcessedCriticalHeaderParams() {
157
158                return critPolicy.getProcessedCriticalHeaderParams();
159        }
160
161
162        @Override
163        public Set<String> getDeferredCriticalHeaderParams() {
164
165                return critPolicy.getProcessedCriticalHeaderParams();
166        }
167
168
169        @Override
170        public byte[] decrypt(final JWEHeader header,
171                              final Base64URL encryptedKey,
172                              final Base64URL iv,
173                              final Base64URL cipherText,
174                              final Base64URL authTag)
175                throws JOSEException {
176
177                // Validate required JWE parts
178                if (encryptedKey == null) {
179                        throw new JOSEException("Missing JWE encrypted key");
180                }
181
182                if (iv == null) {
183                        throw new JOSEException("Missing JWE initialization vector (IV)");
184                }
185
186                if (authTag == null) {
187                        throw new JOSEException("Missing JWE authentication tag");
188                }
189
190                critPolicy.ensureHeaderPasses(header);
191
192                // Derive the content encryption key
193                JWEAlgorithm alg = header.getAlgorithm();
194                int keyLength = header.getEncryptionMethod().cekBitLength();
195
196                final SecretKey cek;
197
198                if (alg.equals(JWEAlgorithm.A128KW) ||
199                    alg.equals(JWEAlgorithm.A192KW) ||
200                    alg.equals(JWEAlgorithm.A256KW))   {
201
202                        cek = AESKW.unwrapCEK(getKey(), encryptedKey.decode(), getJCAContext().getKeyEncryptionProvider());
203
204                } else if (alg.equals(JWEAlgorithm.A128GCMKW) ||
205                           alg.equals(JWEAlgorithm.A192GCMKW) ||
206                           alg.equals(JWEAlgorithm.A256GCMKW)) {
207
208                        if (header.getIV() == null) {
209                                throw new JOSEException("Missing JWE \"iv\" header parameter");
210                        }
211
212                        byte[] keyIV = header.getIV().decode();
213
214                        if (header.getAuthTag() == null) {
215                                throw new JOSEException("Missing JWE \"tag\" header parameter");
216                        }
217
218                        byte[] keyTag = header.getAuthTag().decode();
219
220                        AuthenticatedCipherText authEncrCEK = new AuthenticatedCipherText(encryptedKey.decode(), keyTag);
221                        cek = AESGCMKW.decryptCEK(getKey(), keyIV, authEncrCEK, keyLength, getJCAContext().getKeyEncryptionProvider());
222
223                } else {
224
225                        throw new JOSEException(AlgorithmSupportMessage.unsupportedJWEAlgorithm(alg, SUPPORTED_ALGORITHMS));
226                }
227
228                return ContentCryptoProvider.decrypt(header, encryptedKey, iv, cipherText, authTag, cek, getJCAContext());
229        }
230}