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