001package com.nimbusds.jose;
002
003
004import net.jcip.annotations.Immutable;
005
006
007/**
008 * Encryption method name, represents the {@code enc} header parameter in JSON
009 * Web Encryption (JWE) objects. This class is immutable.
010 *
011 * <p>Includes constants for the following standard encryption method names:
012 *
013 * <ul>
014 *     <li>{@link #A128CBC_HS256 A128CBC-HS256}
015 *     <li>{@link #A192CBC_HS384 A192CBC-HS384}
016 *     <li>{@link #A256CBC_HS512 A256CBC-HS512}
017 *     <li>{@link #A128GCM}
018 *     <li>{@link #A192GCM}
019 *     <li>{@link #A256GCM}
020 *     <li>{@link #A128CBC_HS256_DEPRECATED A128CBC+HS256 (deprecated)}
021 *     <li>{@link #A256CBC_HS512_DEPRECATED A256CBC+HS512 (deprecated)}
022 * </ul>
023 *
024 * <p>Additional encryption method names can be defined using the constructors.
025 *
026 * @author Vladimir Dzhuvinov
027 * @version $version$ (2014-05-23)
028 */
029@Immutable
030public final class EncryptionMethod extends Algorithm {
031
032
033        /**
034         * The Content Encryption Key (CEK) bit length, zero if not specified.
035         */
036        private final int cekBitLength;
037
038
039        /**
040         * AES_128_CBC_HMAC_SHA_256 authenticated encryption using a 256 bit 
041         * key (required).
042         */
043        public static final EncryptionMethod A128CBC_HS256 = 
044                new EncryptionMethod("A128CBC-HS256", Requirement.REQUIRED, 256);
045
046
047        /**
048         * AES_192_CBC_HMAC_SHA_384 authenticated encryption using a 384 bit
049         * key (optional).
050         */
051        public static final EncryptionMethod A192CBC_HS384 =
052                new EncryptionMethod("A192CBC-HS384", Requirement.OPTIONAL, 384);
053
054
055        /**
056         * AES_256_CBC_HMAC_SHA_512 authenticated encryption using a 512 bit
057         * key (required).
058         */
059        public static final EncryptionMethod A256CBC_HS512 = 
060                new EncryptionMethod("A256CBC-HS512", Requirement.REQUIRED, 512);
061
062
063        /**
064         * AES_128_CBC_HMAC_SHA_256 authenticated encryption using a 256 bit
065         * key, deprecated in JOSE draft suite version 09.
066         */
067        public static final EncryptionMethod A128CBC_HS256_DEPRECATED =
068                new EncryptionMethod("A128CBC+HS256", Requirement.OPTIONAL, 256);
069
070
071        /**
072         * AES_256_CBC_HMAC_SHA_512 authenticated encryption using a 512 bit
073         * key, deprecated in JOSE draft suite version 09.
074         */
075        public static final EncryptionMethod A256CBC_HS512_DEPRECATED =
076                new EncryptionMethod("A256CBC+HS512", Requirement.OPTIONAL, 512);
077
078
079        /**
080         * AES in Galois/Counter Mode (GCM) (NIST.800-38D) using a 128 bit key 
081         * (recommended).
082         */
083        public static final EncryptionMethod A128GCM = 
084                new EncryptionMethod("A128GCM", Requirement.RECOMMENDED, 128);
085
086
087        /**
088         * AES in Galois/Counter Mode (GCM) (NIST.800-38D) using a 192 bit key
089         * (optional).
090         */
091        public static final EncryptionMethod A192GCM =
092                new EncryptionMethod("A192GCM", Requirement.OPTIONAL, 192);
093
094
095        /**
096         * AES in Galois/Counter Mode (GCM) (NIST.800-38D) using a 256 bit key 
097         * (recommended).
098         */
099        public static final EncryptionMethod A256GCM = 
100                new EncryptionMethod("A256GCM", Requirement.RECOMMENDED, 256);
101
102
103        /**
104         * Creates a new encryption method.
105         *
106         * @param name         The encryption method name. Must not be 
107         *                     {@code null}.
108         * @param req          The implementation requirement, {@code null} if 
109         *                     not known.
110         * @param cekBitLength The Content Encryption Key (CEK) bit length, 
111         *                     zero if not specified.
112         */
113        public EncryptionMethod(final String name, final Requirement req, final int cekBitLength) {
114
115                super(name, req);
116
117                this.cekBitLength = cekBitLength;
118        }
119
120
121        /**
122         * Creates a new encryption method. The Content Encryption Key (CEK)
123         * bit length is not specified.
124         *
125         * @param name The encryption method name. Must not be {@code null}.
126         * @param req  The implementation requirement, {@code null} if not 
127         *             known.
128         */
129        public EncryptionMethod(final String name, final Requirement req) {
130
131                this(name, req, 0);
132        }
133
134
135        /**
136         * Creates a new encryption method. The implementation requirement and
137         * the Content Encryption Key (CEK) bit length are not specified.
138         *
139         * @param name The encryption method name. Must not be {@code null}.
140         */
141        public EncryptionMethod(final String name) {
142
143                this(name, null, 0);
144        }
145
146
147        /**
148         * Gets the length of the associated Content Encryption Key (CEK).
149         *
150         * @return The Content Encryption Key (CEK) bit length, zero if not 
151         *         specified.
152         */
153        public int cekBitLength() {
154
155                return cekBitLength;
156        }
157
158
159        /**
160         * Parses an encryption method from the specified string.
161         *
162         * @param s The string to parse. Must not be {@code null}.
163         *
164         * @return The encryption method  (matching standard algorithm
165         *         constant, else a newly created algorithm).
166         */
167        public static EncryptionMethod parse(final String s) {
168
169                if (s.equals(A128CBC_HS256.getName())) {
170
171                        return A128CBC_HS256;
172
173                } else if (s.equals(A192CBC_HS384.getName())) {
174
175                        return A192CBC_HS384;
176
177                } else if (s.equals(A256CBC_HS512.getName())) {
178
179                        return A256CBC_HS512;
180
181                } else if (s.equals(A128GCM.getName())) {
182
183                        return A128GCM;
184
185                } else if (s.equals(A192GCM.getName())) {
186
187                        return A192GCM;
188
189                } else if (s.equals(A256GCM.getName())) {
190
191                        return A256GCM;
192
193                } else if (s.equals(A128CBC_HS256_DEPRECATED.getName())) {
194
195                        return A128CBC_HS256_DEPRECATED;
196
197                } else if (s.equals(A256CBC_HS512_DEPRECATED.getName())) {
198
199                        return A256CBC_HS512_DEPRECATED;
200
201                } else {
202
203                        return new EncryptionMethod(s);
204                }
205        }
206}