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.security.interfaces.ECPrivateKey;
022import java.security.interfaces.ECPublicKey;
023import java.util.Collections;
024import java.util.LinkedHashSet;
025import java.util.Set;
026import javax.crypto.SecretKey;
027
028import com.nimbusds.jose.*;
029import com.nimbusds.jose.crypto.utils.ECChecks;
030import com.nimbusds.jose.jwk.Curve;
031import com.nimbusds.jose.jwk.ECKey;
032import com.nimbusds.jose.util.Base64URL;
033
034
035/**
036 * Elliptic Curve Diffie-Hellman decrypter of
037 * {@link com.nimbusds.jose.JWEObject JWE objects} for curves using EC JWK keys.
038 * Expects a private EC key (with a P-256, P-384 or P-521 curve).
039 *
040 * <p>See RFC 7518
041 * <a href="https://tools.ietf.org/html/rfc7518#section-4.6">section 4.6</a>
042 * for more information.
043 *
044 * <p>For Curve25519/X25519, see {@link X25519Decrypter} instead.
045 *
046 * <p>This class is thread-safe.
047 *
048 * <p>Supports the following key management algorithms:
049 *
050 * <ul>
051 *     <li>{@link com.nimbusds.jose.JWEAlgorithm#ECDH_ES}
052 *     <li>{@link com.nimbusds.jose.JWEAlgorithm#ECDH_ES_A128KW}
053 *     <li>{@link com.nimbusds.jose.JWEAlgorithm#ECDH_ES_A192KW}
054 *     <li>{@link com.nimbusds.jose.JWEAlgorithm#ECDH_ES_A256KW}
055 * </ul>
056 *
057 * <p>Supports the following elliptic curves:
058 *
059 * <ul>
060 *     <li>{@link com.nimbusds.jose.jwk.Curve#P_256}
061 *     <li>{@link com.nimbusds.jose.jwk.Curve#P_384}
062 *     <li>{@link com.nimbusds.jose.jwk.Curve#P_521}
063 * </ul>
064 *
065 * <p>Supports the following content encryption algorithms:
066 *
067 * <ul>
068 *     <li>{@link com.nimbusds.jose.EncryptionMethod#A128CBC_HS256}
069 *     <li>{@link com.nimbusds.jose.EncryptionMethod#A192CBC_HS384}
070 *     <li>{@link com.nimbusds.jose.EncryptionMethod#A256CBC_HS512}
071 *     <li>{@link com.nimbusds.jose.EncryptionMethod#A128GCM}
072 *     <li>{@link com.nimbusds.jose.EncryptionMethod#A192GCM}
073 *     <li>{@link com.nimbusds.jose.EncryptionMethod#A256GCM}
074 *     <li>{@link com.nimbusds.jose.EncryptionMethod#A128CBC_HS256_DEPRECATED}
075 *     <li>{@link com.nimbusds.jose.EncryptionMethod#A256CBC_HS512_DEPRECATED}
076 * </ul>
077 *
078 * @author Vladimir Dzhuvinov
079 * @version 2017-04-13
080 */
081public class ECDHDecrypter extends ECDHCryptoProvider implements JWEDecrypter, CriticalHeaderParamsAware {
082
083
084        /**
085         * The supported EC JWK curves by the ECDH crypto provider class.
086         */
087        public static final Set<Curve> SUPPORTED_ELLIPTIC_CURVES;
088
089
090        static {
091                Set<Curve> curves = new LinkedHashSet<>();
092                curves.add(Curve.P_256);
093                curves.add(Curve.P_384);
094                curves.add(Curve.P_521);
095                SUPPORTED_ELLIPTIC_CURVES = Collections.unmodifiableSet(curves);
096        }
097
098
099        /**
100         * The private EC key.
101         */
102        private final ECPrivateKey privateKey;
103
104
105        /**
106         * The critical header policy.
107         */
108        private final CriticalHeaderParamsDeferral critPolicy = new CriticalHeaderParamsDeferral();
109
110
111        /**
112         * Creates a new Elliptic Curve Diffie-Hellman decrypter.
113         *
114         * @param privateKey The private EC key. Must not be {@code null}.
115         *
116         * @throws JOSEException If the elliptic curve is not supported.
117         */
118        public ECDHDecrypter(final ECPrivateKey privateKey)
119                throws JOSEException {
120
121                this(privateKey, null);
122        }
123
124
125        /**
126         * Creates a new Elliptic Curve Diffie-Hellman decrypter.
127         *
128         * @param ecJWK The EC JSON Web Key (JWK). Must contain a private
129         *              part. Must not be {@code null}.
130         *
131         * @throws JOSEException If the elliptic curve is not supported.
132         */
133        public ECDHDecrypter(final ECKey ecJWK)
134                throws JOSEException {
135
136                super(ecJWK.getCurve());
137
138                if (! ecJWK.isPrivate()) {
139                        throw new JOSEException("The EC JWK doesn't contain a private part");
140                }
141
142                this.privateKey = ecJWK.toECPrivateKey();
143        }
144
145
146        /**
147         * Creates a new Elliptic Curve Diffie-Hellman decrypter.
148         *
149         * @param privateKey     The private EC key. Must not be {@code null}.
150         * @param defCritHeaders The names of the critical header parameters
151         *                       that are deferred to the application for
152         *                       processing, empty set or {@code null} if none.
153         *
154         * @throws JOSEException If the elliptic curve is not supported.
155         */
156        public ECDHDecrypter(final ECPrivateKey privateKey, final Set<String> defCritHeaders)
157                throws JOSEException {
158
159                super(Curve.forECParameterSpec(privateKey.getParams()));
160
161                critPolicy.setDeferredCriticalHeaderParams(defCritHeaders);
162
163                this.privateKey = privateKey;
164        }
165
166
167        /**
168         * Returns the private EC key.
169         *
170         * @return The private EC key.
171         */
172        public ECPrivateKey getPrivateKey() {
173
174                return privateKey;
175        }
176
177
178        @Override
179        public Set<Curve> supportedEllipticCurves() {
180
181                return SUPPORTED_ELLIPTIC_CURVES;
182        }
183
184
185        @Override
186        public Set<String> getProcessedCriticalHeaderParams() {
187
188                return critPolicy.getProcessedCriticalHeaderParams();
189        }
190
191
192        @Override
193        public Set<String> getDeferredCriticalHeaderParams() {
194
195                return critPolicy.getProcessedCriticalHeaderParams();
196        }
197
198
199        @Override
200        public byte[] decrypt(final JWEHeader header,
201                              final Base64URL encryptedKey,
202                              final Base64URL iv,
203                              final Base64URL cipherText,
204                              final Base64URL authTag)
205                throws JOSEException {
206
207                critPolicy.ensureHeaderPasses(header);
208
209                // Get ephemeral EC key
210                ECKey ephemeralKey = (ECKey) header.getEphemeralPublicKey();
211
212                if (ephemeralKey == null) {
213                        throw new JOSEException("Missing ephemeral public EC key \"epk\" JWE header parameter");
214                }
215
216                ECPublicKey ephemeralPublicKey = ephemeralKey.toECPublicKey();
217                
218                // Curve check
219                if (! ECChecks.isPointOnCurve(ephemeralPublicKey, getPrivateKey())) {
220                        throw new JOSEException("Invalid ephemeral public EC key: Point(s) not on the expected curve");
221                }
222
223                // Derive 'Z'
224                SecretKey Z = ECDH.deriveSharedSecret(
225                        ephemeralPublicKey,
226                        privateKey,
227                        getJCAContext().getKeyEncryptionProvider());
228
229                return decryptWithZ(header, Z, encryptedKey, iv, cipherText, authTag);
230        }
231}