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; 019 020 021import com.nimbusds.jose.util.ArrayUtils; 022import net.jcip.annotations.Immutable; 023 024 025/** 026 * JSON Web Encryption (JWE) algorithm name, represents the {@code alg} header 027 * parameter in JWE objects. This class is immutable. 028 * 029 * <p>Includes constants for the following standard JWE algorithm names: 030 * 031 * <ul> 032 * <li>{@link #RSA_OAEP_256 RSA-OAEP-256} 033 * <li>{@link #RSA_OAEP RSA-OAEP} (deprecated) 034 * <li>{@link #RSA1_5} (deprecated) 035 * <li>{@link #A128KW} 036 * <li>{@link #A192KW} 037 * <li>{@link #A256KW} 038 * <li>{@link #DIR dir} 039 * <li>{@link #ECDH_ES ECDH-ES} 040 * <li>{@link #ECDH_ES_A128KW ESDH-ES+A128KW} 041 * <li>{@link #ECDH_ES_A128KW ESDH-ES+A192KW} 042 * <li>{@link #ECDH_ES_A256KW ESDH-ES+A256KW} 043 * <li>{@link #PBES2_HS256_A128KW PBES2-HS256+A128KW} 044 * <li>{@link #PBES2_HS384_A192KW PBES2-HS256+A192KW} 045 * <li>{@link #PBES2_HS512_A256KW PBES2-HS256+A256KW} 046 * </ul> 047 * 048 * <p>Additional JWE algorithm names can be defined using the constructors. 049 * 050 * @author Vladimir Dzhuvinov 051 * @version 2017-04-09 052 */ 053@Immutable 054public final class JWEAlgorithm extends Algorithm { 055 056 057 private static final long serialVersionUID = 1L; 058 059 060 /** 061 * RSAES-PKCS1-V1_5 (RFC 3447). Use of this RSA encryption algorithm is 062 * no longer recommended, use {@link #RSA_OAEP_256} instead. 063 */ 064 @Deprecated 065 public static final JWEAlgorithm RSA1_5 = new JWEAlgorithm("RSA1_5", Requirement.REQUIRED); 066 067 068 /** 069 * RSAES using Optimal Asymmetric Encryption Padding (OAEP) (RFC 3447), 070 * with the default parameters specified by RFC 3447 in section A.2.1. 071 * Use of this encryption algorithm is no longer recommended, use 072 * {@link #RSA_OAEP_256} instead. 073 */ 074 @Deprecated 075 public static final JWEAlgorithm RSA_OAEP = new JWEAlgorithm("RSA-OAEP", Requirement.OPTIONAL); 076 077 078 /** 079 * RSAES using Optimal Asymmetric Encryption Padding (OAEP) (RFC 3447), 080 * with the SHA-256 hash function and the MGF1 with SHA-256 mask 081 * generation function. 082 */ 083 public static final JWEAlgorithm RSA_OAEP_256 = new JWEAlgorithm("RSA-OAEP-256", Requirement.OPTIONAL); 084 085 086 /** 087 * Advanced Encryption Standard (AES) Key Wrap Algorithm (RFC 3394) 088 * using 128 bit keys. 089 */ 090 public static final JWEAlgorithm A128KW = new JWEAlgorithm("A128KW", Requirement.RECOMMENDED); 091 092 093 /** 094 * Advanced Encryption Standard (AES) Key Wrap Algorithm (RFC 3394) 095 * using 192 bit keys. 096 */ 097 public static final JWEAlgorithm A192KW = new JWEAlgorithm("A192KW", Requirement.OPTIONAL); 098 099 100 /** 101 * Advanced Encryption Standard (AES) Key Wrap Algorithm (RFC 3394) 102 * using 256 bit keys. 103 */ 104 public static final JWEAlgorithm A256KW = new JWEAlgorithm("A256KW", Requirement.RECOMMENDED); 105 106 107 /** 108 * Direct use of a shared symmetric key as the Content Encryption Key 109 * (CEK) for the block encryption step (rather than using the symmetric 110 * key to wrap the CEK). 111 */ 112 public static final JWEAlgorithm DIR = new JWEAlgorithm("dir", Requirement.RECOMMENDED); 113 114 115 /** 116 * Elliptic Curve Diffie-Hellman Ephemeral Static (RFC 6090) key 117 * agreement using the Concat KDF, as defined in section 5.8.1 of 118 * NIST.800-56A, with the agreed-upon key being used directly as the 119 * Content Encryption Key (CEK) (rather than being used to wrap the 120 * CEK). 121 */ 122 public static final JWEAlgorithm ECDH_ES = new JWEAlgorithm("ECDH-ES", Requirement.RECOMMENDED); 123 124 125 /** 126 * Elliptic Curve Diffie-Hellman Ephemeral Static key agreement per 127 * "ECDH-ES", but where the agreed-upon key is used to wrap the Content 128 * Encryption Key (CEK) with the "A128KW" function (rather than being 129 * used directly as the CEK). 130 */ 131 public static final JWEAlgorithm ECDH_ES_A128KW = new JWEAlgorithm("ECDH-ES+A128KW", Requirement.RECOMMENDED); 132 133 134 /** 135 * Elliptic Curve Diffie-Hellman Ephemeral Static key agreement per 136 * "ECDH-ES", but where the agreed-upon key is used to wrap the Content 137 * Encryption Key (CEK) with the "A192KW" function (rather than being 138 * used directly as the CEK). 139 */ 140 public static final JWEAlgorithm ECDH_ES_A192KW = new JWEAlgorithm("ECDH-ES+A192KW", Requirement.OPTIONAL); 141 142 143 /** 144 * Elliptic Curve Diffie-Hellman Ephemeral Static key agreement per 145 * "ECDH-ES", but where the agreed-upon key is used to wrap the Content 146 * Encryption Key (CEK) with the "A256KW" function (rather than being 147 * used directly as the CEK). 148 */ 149 public static final JWEAlgorithm ECDH_ES_A256KW = new JWEAlgorithm("ECDH-ES+A256KW", Requirement.RECOMMENDED); 150 151 152 /** 153 * AES in Galois/Counter Mode (GCM) (NIST.800-38D) 128 bit keys. 154 */ 155 public static final JWEAlgorithm A128GCMKW = new JWEAlgorithm("A128GCMKW", Requirement.OPTIONAL); 156 157 158 /** 159 * AES in Galois/Counter Mode (GCM) (NIST.800-38D) 192 bit keys. 160 */ 161 public static final JWEAlgorithm A192GCMKW = new JWEAlgorithm("A192GCMKW", Requirement.OPTIONAL); 162 163 164 /** 165 * AES in Galois/Counter Mode (GCM) (NIST.800-38D) 256 bit keys. 166 */ 167 public static final JWEAlgorithm A256GCMKW = new JWEAlgorithm("A256GCMKW", Requirement.OPTIONAL); 168 169 170 /** 171 * PBES2 (RFC 2898) with HMAC SHA-256 as the PRF and AES Key Wrap 172 * (RFC 3394) using 128 bit keys for the encryption scheme. 173 */ 174 public static final JWEAlgorithm PBES2_HS256_A128KW = new JWEAlgorithm("PBES2-HS256+A128KW", Requirement.OPTIONAL); 175 176 177 /** 178 * PBES2 (RFC 2898) with HMAC SHA-384 as the PRF and AES Key Wrap 179 * (RFC 3394) using 192 bit keys for the encryption scheme. 180 */ 181 public static final JWEAlgorithm PBES2_HS384_A192KW = new JWEAlgorithm("PBES2-HS384+A192KW", Requirement.OPTIONAL); 182 183 184 /** 185 * PBES2 (RFC 2898) with HMAC SHA-512 as the PRF and AES Key Wrap 186 * (RFC 3394) using 256 bit keys for the encryption scheme. 187 */ 188 public static final JWEAlgorithm PBES2_HS512_A256KW = new JWEAlgorithm("PBES2-HS512+A256KW", Requirement.OPTIONAL); 189 190 191 /** 192 * JWE algorithm family. 193 */ 194 public static final class Family extends AlgorithmFamily<JWEAlgorithm> { 195 196 197 private static final long serialVersionUID = 1L; 198 199 200 /** 201 * RSA key encryption. 202 */ 203 public static final Family RSA = new Family(RSA1_5, RSA_OAEP, RSA_OAEP_256); 204 205 206 /** 207 * AES key wrap. 208 */ 209 public static final Family AES_KW = new Family(A128KW, A192KW, A256KW); 210 211 212 /** 213 * Elliptic Curve Diffie-Hellman Ephemeral Static key 214 * agreement. 215 */ 216 public static final Family ECDH_ES = new Family(JWEAlgorithm.ECDH_ES, ECDH_ES_A128KW, ECDH_ES_A192KW, ECDH_ES_A256KW); 217 218 219 /** 220 * AES GCM key wrap. 221 */ 222 public static final Family AES_GCM_KW = new Family(A128GCMKW, A192GCMKW, A256GCMKW); 223 224 225 /** 226 * Password-Based Cryptography Specification Version 2.0 227 */ 228 public static final Family PBES2 = new Family(PBES2_HS256_A128KW, PBES2_HS384_A192KW, PBES2_HS512_A256KW); 229 230 231 /** 232 * Super family of all asymmetric (public / private key based) 233 * JWE algorithms. 234 */ 235 public static final Family ASYMMETRIC = new Family(ArrayUtils.concat( 236 RSA.toArray(new JWEAlgorithm[]{}), 237 ECDH_ES.toArray(new JWEAlgorithm[]{}))); 238 239 240 /** 241 * Super family of all symmetric (shared key based) JWE 242 * algorithms. 243 */ 244 public static final Family SYMMETRIC = new Family(ArrayUtils.concat( 245 AES_KW.toArray(new JWEAlgorithm[]{}), 246 AES_GCM_KW.toArray(new JWEAlgorithm[]{}), 247 new JWEAlgorithm[]{JWEAlgorithm.DIR})); 248 249 250 /*** 251 * Creates a new JWE algorithm family. 252 * 253 * @param algs The JWE algorithms of the family. Must not be 254 * {@code null}. 255 */ 256 public Family(final JWEAlgorithm ... algs) { 257 super(algs); 258 } 259 } 260 261 262 /** 263 * Creates a new JSON Web Encryption (JWE) algorithm. 264 * 265 * @param name The algorithm name. Must not be {@code null}. 266 * @param req The implementation requirement, {@code null} if not 267 * known. 268 */ 269 public JWEAlgorithm(final String name, final Requirement req) { 270 271 super(name, req); 272 } 273 274 275 /** 276 * Creates a new JSON Web Encryption (JWE) algorithm. 277 * 278 * @param name The algorithm name. Must not be {@code null}. 279 */ 280 public JWEAlgorithm(final String name) { 281 282 super(name, null); 283 } 284 285 286 /** 287 * Parses a JWE algorithm from the specified string. 288 * 289 * @param s The string to parse. Must not be {@code null}. 290 * 291 * @return The JWE algorithm (matching standard algorithm constant, else 292 * a newly created algorithm). 293 */ 294 public static JWEAlgorithm parse(final String s) { 295 296 if (s.equals(RSA1_5.getName())) { 297 return RSA1_5; 298 } else if (s.equals(RSA_OAEP.getName())) { 299 return RSA_OAEP; 300 } else if (s.equals(RSA_OAEP_256.getName())) { 301 return RSA_OAEP_256; 302 } else if (s.equals(A128KW.getName())) { 303 return A128KW; 304 } else if (s.equals(A192KW.getName())) { 305 return A192KW; 306 } else if (s.equals(A256KW.getName())) { 307 return A256KW; 308 } else if (s.equals(DIR.getName())) { 309 return DIR; 310 } else if (s.equals(ECDH_ES.getName())) { 311 return ECDH_ES; 312 } else if (s.equals(ECDH_ES_A128KW.getName())) { 313 return ECDH_ES_A128KW; 314 } else if (s.equals(ECDH_ES_A192KW.getName())) { 315 return ECDH_ES_A192KW; 316 } else if (s.equals(ECDH_ES_A256KW.getName())) { 317 return ECDH_ES_A256KW; 318 } else if (s.equals(A128GCMKW.getName())) { 319 return A128GCMKW; 320 } else if (s.equals(A192GCMKW.getName())) { 321 return A192GCMKW; 322 } else if (s.equals(A256GCMKW.getName())) { 323 return A256GCMKW; 324 } else if (s.equals(PBES2_HS256_A128KW.getName())) { 325 return PBES2_HS256_A128KW; 326 } else if (s.equals(PBES2_HS384_A192KW.getName())) { 327 return PBES2_HS384_A192KW; 328 } else if (s.equals(PBES2_HS512_A256KW.getName())) { 329 return PBES2_HS512_A256KW; 330 } else { 331 return new JWEAlgorithm(s); 332 } 333 } 334}