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 as 013 * well as the JWE algorithms and header parameters that are accepted for 014 * processing. 015 * 016 * @author Vladimir Dzhuvinov 017 * @version $version$ (2014-04-22) 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 * @return The accepted JWE algorithms, as a read-only set, empty set 027 * if none. 028 */ 029 public Set<JWEAlgorithm> getAcceptedAlgorithms(); 030 031 032 /** 033 * Sets the names of the accepted JWE algorithms. These correspond to 034 * the {@code alg} JWE header parameter. 035 * 036 * @param acceptedAlgs The accepted JWE algorithms. Must be a subset of 037 * the supported algorithms and not {@code null}. 038 */ 039 public void setAcceptedAlgorithms(Set<JWEAlgorithm> acceptedAlgs); 040 041 042 /** 043 * Gets the names of the accepted encryption methods. These correspond 044 * to the {@code enc} JWE header parameter. 045 * 046 * @return The accepted encryption methods, as a read-only set, empty 047 * set if none. 048 */ 049 public Set<EncryptionMethod> getAcceptedEncryptionMethods(); 050 051 052 /** 053 * Sets the names of the accepted encryption methods. These correspond 054 * to the {@code enc} JWE header parameter. 055 * 056 * @param acceptedEncs The accepted encryption methods. Must be a 057 * subset of the supported encryption methods and 058 * not {@code null}. 059 */ 060 public void setAcceptedEncryptionMethods(final Set<EncryptionMethod> acceptedEncs); 061 062 063 /** 064 * Gets the names of the critical JWE header parameters to ignore. 065 * These are indicated by the {@code crit} header parameter. The JWE 066 * decrypter should not ignore critical headers by default. 067 * 068 * @return The names of the critical JWS header parameters to ignore, 069 * empty or {@code null} if none. 070 */ 071 public Set<String> getIgnoredCriticalHeaderParameters(); 072 073 074 /** 075 * Sets the names of the critical JWE header parameters to ignore. 076 * These are indicated by the {@code crit} header parameter. The JWE 077 * decrypter should not ignore critical headers by default. Use this 078 * setter to delegate processing of selected critical headers to the 079 * application. 080 * 081 * @param headers The names of the critical JWS header parameters to 082 * ignore, empty or {@code null} if none. 083 */ 084 public void setIgnoredCriticalHeaderParameters(final Set<String> headers); 085 086 087 /** 088 * Decrypts the specified cipher text of a {@link JWEObject JWE Object}. 089 * 090 * @param header The JSON Web Encryption (JWE) header. Must 091 * specify an accepted JWE algorithm, must contain 092 * only accepted header parameters, and must not 093 * be {@code null}. 094 * @param encryptedKey The encrypted key, {@code null} if not required 095 * by the JWE algorithm. 096 * @param iv The initialisation vector, {@code null} if not 097 * required by the JWE algorithm. 098 * @param cipherText The cipher text to decrypt. Must not be 099 * {@code null}. 100 * @param authTag The authentication tag, {@code null} if not 101 * required. 102 * 103 * @return The clear text. 104 * 105 * @throws JOSEException If the JWE algorithm is not accepted, if a 106 * header parameter is not accepted, or if 107 * decryption failed for some other reason. 108 */ 109 public byte[] decrypt(final ReadOnlyJWEHeader header, 110 final Base64URL encryptedKey, 111 final Base64URL iv, 112 final Base64URL cipherText, 113 final Base64URL authTag) 114 throws JOSEException; 115}