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}