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