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-07-08)
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         * @see #setAcceptedAlgorithms
027         *
028         * @return The accepted JWS algorithms, as a read-only set, empty set
029         *         if none.
030         */
031        public Set<JWSAlgorithm> getAcceptedAlgorithms();
032
033
034        /**
035         * Sets the names of the accepted JWS algorithms. These correspond to
036         * the {@code alg} JWS header parameter.
037         *
038         * <p>For JWS verifiers that support multiple JWS algorithms this
039         * method can be used to indicate that only a subset should be accepted
040         * for processing.
041         *
042         * @param acceptedAlgs The accepted JWS algorithms. Must be a subset of
043         *                     the supported algorithms and not {@code null}.
044         */
045        public void setAcceptedAlgorithms(final Set<JWSAlgorithm> acceptedAlgs);
046
047
048        /**
049         * Gets the names of the critical JWS header parameters to ignore.
050         * These are indicated by the {@code crit} header parameter. The JWS
051         * verifier should not ignore critical headers by default.
052         *
053         * @return The names of the critical JWS header parameters to ignore,
054         *         empty or {@code null} if none.
055         */
056        public Set<String> getIgnoredCriticalHeaderParameters();
057
058
059        /**
060         * Sets the names of the critical JWS header parameters to ignore.
061         * These are indicated by the {@code crit} header parameter. The JWS
062         * verifier should not ignore critical headers by default. Use this
063         * setter to delegate processing of selected critical headers to the
064         * application.
065         *
066         * @param headers The names of the critical JWS header parameters to
067         *                ignore, empty or {@code null} if none.
068         */
069        public void setIgnoredCriticalHeaderParameters(final Set<String> headers);
070
071
072        /**
073         * Verifies the specified {@link JWSObject#getSignature signature} of a
074         * {@link JWSObject JWS object}.
075         *
076         * @param header       The JSON Web Signature (JWS) header. Must 
077         *                     specify an accepted JWS algorithm, must contain
078         *                     only accepted header parameters, and must not be
079         *                     {@code null}.
080         * @param signingInput The signing input. Must not be {@code null}.
081         * @param signature    The signature part of the JWS object. Must not
082         *                     be {@code null}.
083         *
084         * @return {@code true} if the signature was successfully verified, 
085         *         else {@code false}.
086         *
087         * @throws JOSEException If the JWS algorithm is not accepted, if a 
088         *                       header parameter is not accepted, or if 
089         *                       signature verification failed for some other
090         *                       reason.
091         */
092        public boolean verify(final JWSHeader header,
093                              final byte[] signingInput,
094                              final Base64URL signature)
095                throws JOSEException;
096}