001    package com.nimbusds.jose;
002    
003    
004    import 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$ (2012-10-16)
016     */
017    public 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 integrityValue The integrity value, {@code null} if not 
049             *                       required by the JWE algorithm.
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 integrityValue)
062                                            throws JOSEException;
063    }