001    package com.nimbusds.jose;
002    
003    
004    import java.util.Set;
005    
006    import 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$ (2012-10-16)
018     */
019    public interface JWEDecrypter extends JWEAlgorithmProvider {
020    
021            
022            /**
023             * Gets the JWE header filter associated with the decrypter. Specifies 
024             * the names of those {@link #supportedAlgorithms supported JWE 
025             * algorithms} and header parameters that the decrypter is configured to
026             * accept.
027             *
028             * <p>Attempting to {@link #decrypt decrypt} a JWE object with an
029             * algorithm or header parameter that is not accepted must result in a 
030             * {@link JOSEException}.
031             *
032             * @return The JWE header filter.
033             */
034            public JWEHeaderFilter getJWEHeaderFilter();
035            
036            
037            /**
038             * Decrypts the specified cipher text of a {@link JWEObject JWE Object}.
039             *
040             * @param header         The JSON Web Encryption (JWE) header. Must 
041             *                       specify an accepted JWE algorithm, must contain
042             *                       only accepted header parameters, and must not 
043             *                       be {@code null}.
044             * @param encryptedKey   The encrypted key, {@code null} if not required
045             *                       by the JWE algorithm.
046             * @param iv             The initialisation vector, {@code null} if not
047             *                       required by the JWE algorithm.
048             * @param cipherText     The cipher text to decrypt. Must not be 
049             *                       {@code null}.
050             * @param integrityValue The integrity value, {@code null} if not 
051             *                       required by the JWE algorithm.
052             *
053             * @return The clear text.
054             *
055             * @throws JOSEException If the JWE algorithm is not accepted, if a 
056             *                       header parameter is not accepted, or if
057             *                       decryption failed for some other reason.
058             */
059            public byte[] decrypt(final ReadOnlyJWEHeader header, 
060                                  final Base64URL encryptedKey,
061                                  final Base64URL iv,
062                                  final Base64URL cipherText,
063                                  final Base64URL integrityValue)
064                    throws JOSEException;
065    }