001package com.nimbusds.jose;
002
003
004import java.util.Set;
005
006import com.nimbusds.jose.util.Base64URL;
007
008
009/**
010 * Interface for verifying JSON Web Signature (JWS) objects.
011 *
012 * <p>Callers can query the verifier to determine its algorithm capabilities as
013 * well as the JWS algorithms and header parameters that are accepted for 
014 * processing.
015 *
016 * @author Vladimir Dzhuvinov
017 * @version $version$ (2014-04-22)
018 */
019public interface JWSVerifier extends JWSAlgorithmProvider {
020
021
022        /**
023         * Gets the names of the accepted JWS algorithms. These correspond to
024         * the {@code alg} JWS header parameter.
025         *
026         * @return The accepted JWS algorithms, as a read-only set, empty set
027         *         if none.
028         */
029        public Set<JWSAlgorithm> getAcceptedAlgorithms();
030
031
032        /**
033         * Sets the names of the accepted JWS algorithms. These correspond to
034         * the {@code alg} JWS header parameter.
035         *
036         * @param acceptedAlgs The accepted JWS algorithms. Must be a subset of
037         *                     the supported algorithms and not {@code null}.
038         */
039        public void setAcceptedAlgorithms(Set<JWSAlgorithm> acceptedAlgs);
040
041
042        /**
043         * Gets the names of the critical JWS header parameters to ignore.
044         * These are indicated by the {@code crit} header parameter. The JWS
045         * verifier should not ignore critical headers by default.
046         *
047         * @return The names of the critical JWS header parameters to ignore,
048         *         empty or {@code null} if none.
049         */
050        public Set<String> getIgnoredCriticalHeaderParameters();
051
052
053        /**
054         * Sets the names of the critical JWS header parameters to ignore.
055         * These are indicated by the {@code crit} header parameter. The JWS
056         * verifier should not ignore critical headers by default. Use this
057         * setter to delegate processing of selected critical headers to the
058         * application.
059         *
060         * @param headers The names of the critical JWS header parameters to
061         *                ignore, empty or {@code null} if none.
062         */
063        public void setIgnoredCriticalHeaderParameters(final Set<String> headers);
064
065
066        /**
067         * Verifies the specified {@link JWSObject#getSignature signature} of a
068         * {@link JWSObject JWS object}.
069         *
070         * @param header       The JSON Web Signature (JWS) header. Must 
071         *                     specify an accepted JWS algorithm, must contain
072         *                     only accepted header parameters, and must not be
073         *                     {@code null}.
074         * @param signingInput The signing input. Must not be {@code null}.
075         * @param signature    The signature part of the JWS object. Must not
076         *                     be {@code null}.
077         *
078         * @return {@code true} if the signature was successfully verified, 
079         *         else {@code false}.
080         *
081         * @throws JOSEException If the JWS algorithm is not accepted, if a 
082         *                       header parameter is not accepted, or if 
083         *                       signature verification failed for some other
084         *                       reason.
085         */
086        public boolean verify(final ReadOnlyJWSHeader header, final byte[] signingInput, final Base64URL signature)
087                throws JOSEException;
088}