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}