001package com.nimbusds.jose;
002
003
004import com.nimbusds.jose.util.Base64URL;
005
006
007/**
008 * Interface for verifying JSON Web Signature (JWS) objects.
009 *
010 * <p>Callers can query the verifier to determine its algorithm capabilities as
011 * well as the JWS algorithms and header parameters that are accepted for 
012 * processing.
013 *
014 * @author Vladimir Dzhuvinov
015 * @version $version$ (2013-05-04)
016 */
017public interface JWSVerifier extends JWSAlgorithmProvider {
018
019
020        /**
021         * Gets the JWS header filter associated with the verifier. Specifies 
022         * the names of those {@link #supportedAlgorithms supported JWS 
023         * algorithms} and header parameters that the verifier is configured to
024         * accept.
025         *
026         * <p>Attempting to {@link #verify verify} a JWS object signature with 
027         * an algorithm or header parameter that is not accepted must result in
028         * a {@link JOSEException}.
029         *
030         * @return The JWS header filter.
031         */
032        public JWSHeaderFilter getJWSHeaderFilter();
033
034
035        /**
036         * Verifies the specified {@link JWSObject#getSignature signature} of a
037         * {@link JWSObject JWS object}.
038         *
039         * @param header       The JSON Web Signature (JWS) header. Must 
040         *                     specify an accepted JWS algorithm, must contain
041         *                     only accepted header parameters, and must not be
042         *                     {@code null}.
043         * @param signingInput The signing input. Must not be {@code null}.
044         * @param signature    The signature part of the JWS object. Must not
045         *                     be {@code null}.
046         *
047         * @return {@code true} if the signature was successfully verified, 
048         *         else {@code false}.
049         *
050         * @throws JOSEException If the JWS algorithm is not accepted, if a 
051         *                       header parameter is not accepted, or if 
052         *                       signature verification failed for some other
053         *                       reason.
054         */
055        public boolean verify(final ReadOnlyJWSHeader header, final byte[] signingInput, final Base64URL signature)
056                throws JOSEException;
057}