001package com.nimbusds.jose; 002 003 004import java.util.Set; 005 006import com.nimbusds.jose.util.Base64URL; 007 008 009/** 010 * Interface for decrypting JSON Web Encryption (JWE) objects. 011 * 012 * <p>Callers can query the decrypter to determine its algorithm capabilities 013 * as well as the JWE algorithms and header parameters that are accepted for 014 * processing. 015 * 016 * @author Vladimir Dzhuvinov 017 * @version $version$ (2014-07-08) 018 */ 019public interface JWEDecrypter extends JWEAlgorithmProvider { 020 021 022 /** 023 * Gets the names of the accepted JWE algorithms. These correspond to 024 * the {@code alg} JWE header parameter. 025 * 026 * @see #setAcceptedAlgorithms 027 * 028 * @return The accepted JWE algorithms, as a read-only set, empty set 029 * if none. 030 */ 031 public Set<JWEAlgorithm> getAcceptedAlgorithms(); 032 033 034 /** 035 * Sets the names of the accepted JWE algorithms. These correspond to 036 * the {@code alg} JWE header parameter. 037 * 038 * <p>For JWE decrypters that support multiple JWE algorithms this 039 * method can be used to indicate that only a subset should be accepted 040 * for processing. 041 * 042 * @param acceptedAlgs The accepted JWE algorithms. Must be a subset of 043 * the supported algorithms and not {@code null}. 044 */ 045 public void setAcceptedAlgorithms(Set<JWEAlgorithm> acceptedAlgs); 046 047 048 /** 049 * Gets the names of the accepted encryption methods. These correspond 050 * to the {@code enc} JWE header parameter. 051 * 052 * @see #setAcceptedEncryptionMethods 053 * 054 * @return The accepted encryption methods, as a read-only set, empty 055 * set if none. 056 */ 057 public Set<EncryptionMethod> getAcceptedEncryptionMethods(); 058 059 060 /** 061 * Sets the names of the accepted encryption methods. These correspond 062 * to the {@code enc} JWE header parameter. 063 * 064 * <p>For JWE decrypters that support multiple encryption methods this 065 * method can be used to indicate that only a subset should be accepted 066 * for processing. 067 * 068 * @param acceptedEncs The accepted encryption methods. Must be a 069 * subset of the supported encryption methods and 070 * not {@code null}. 071 */ 072 public void setAcceptedEncryptionMethods(final Set<EncryptionMethod> acceptedEncs); 073 074 075 /** 076 * Gets the names of the critical JWE header parameters to ignore. 077 * These are indicated by the {@code crit} header parameter. The JWE 078 * decrypter should not ignore critical headers by default. 079 * 080 * @return The names of the critical JWS header parameters to ignore, 081 * empty or {@code null} if none. 082 */ 083 public Set<String> getIgnoredCriticalHeaderParameters(); 084 085 086 /** 087 * Sets the names of the critical JWE header parameters to ignore. 088 * These are indicated by the {@code crit} header parameter. The JWE 089 * decrypter should not ignore critical headers by default. Use this 090 * setter to delegate processing of selected critical headers to the 091 * application. 092 * 093 * @param headers The names of the critical JWS header parameters to 094 * ignore, empty or {@code null} if none. 095 */ 096 public void setIgnoredCriticalHeaderParameters(final Set<String> headers); 097 098 099 /** 100 * Decrypts the specified cipher text of a {@link JWEObject JWE Object}. 101 * 102 * @param header The JSON Web Encryption (JWE) header. Must 103 * specify an accepted JWE algorithm, must contain 104 * only accepted header parameters, and must not 105 * be {@code null}. 106 * @param encryptedKey The encrypted key, {@code null} if not required 107 * by the JWE algorithm. 108 * @param iv The initialisation vector, {@code null} if not 109 * required by the JWE algorithm. 110 * @param cipherText The cipher text to decrypt. Must not be 111 * {@code null}. 112 * @param authTag The authentication tag, {@code null} if not 113 * required. 114 * 115 * @return The clear text. 116 * 117 * @throws JOSEException If the JWE algorithm is not accepted, if a 118 * header parameter is not accepted, or if 119 * decryption failed for some other reason. 120 */ 121 public byte[] decrypt(final JWEHeader header, 122 final Base64URL encryptedKey, 123 final Base64URL iv, 124 final Base64URL cipherText, 125 final Base64URL authTag) 126 throws JOSEException; 127}