001package com.nimbusds.jose;
002
003
004import com.nimbusds.jose.util.Base64URL;
005
006
007/**
008 * Interface for decrypting JSON Web Encryption (JWE) objects.
009 *
010 * <p>Callers can query the decrypter to determine its algorithm capabilities as
011 * well as the JWE algorithms and header parameters that are accepted for 
012 * processing.
013 *
014 * @author Vladimir Dzhuvinov
015 * @version $version$ (2013-05-06)
016 */
017public interface JWEDecrypter extends JWEAlgorithmProvider {
018
019
020        /**
021         * Gets the JWE header filter associated with the decrypter. Specifies 
022         * the names of those {@link #supportedAlgorithms supported JWE 
023         * algorithms} and header parameters that the decrypter is configured to
024         * accept.
025         *
026         * <p>Attempting to {@link #decrypt decrypt} a JWE object with an
027         * algorithm or header parameter that is not accepted must result in a 
028         * {@link JOSEException}.
029         *
030         * @return The JWE header filter.
031         */
032        public JWEHeaderFilter getJWEHeaderFilter();
033
034
035        /**
036         * Decrypts the specified cipher text of a {@link JWEObject JWE Object}.
037         *
038         * @param header         The JSON Web Encryption (JWE) header. Must 
039         *                       specify an accepted JWE algorithm, must contain
040         *                       only accepted header parameters, and must not 
041         *                       be {@code null}.
042         * @param encryptedKey   The encrypted key, {@code null} if not required
043         *                       by the JWE algorithm.
044         * @param iv             The initialisation vector, {@code null} if not
045         *                       required by the JWE algorithm.
046         * @param cipherText     The cipher text to decrypt. Must not be 
047         *                       {@code null}.
048         * @param authTag        The authentication tag, {@code null} if not 
049         *                       required.
050         *
051         * @return The clear text.
052         *
053         * @throws JOSEException If the JWE algorithm is not accepted, if a 
054         *                       header parameter is not accepted, or if
055         *                       decryption failed for some other reason.
056         */
057        public byte[] decrypt(final ReadOnlyJWEHeader header, 
058                              final Base64URL encryptedKey,
059                              final Base64URL iv,
060                              final Base64URL cipherText,
061                              final Base64URL authTag)
062                throws JOSEException;
063}