001package com.nimbusds.jwt.proc;
002
003
004import java.text.ParseException;
005
006import com.nimbusds.jose.JOSEException;
007import com.nimbusds.jose.proc.BadJOSEException;
008import com.nimbusds.jose.proc.SecurityContext;
009import com.nimbusds.jwt.*;
010
011
012/**
013 * Interface for parsing and processing {@link com.nimbusds.jwt.PlainJWT
014 * unsecured} (plain), {@link com.nimbusds.jwt.SignedJWT signed} and
015 * {@link com.nimbusds.jwt.EncryptedJWT encrypted} JSON Web Tokens (JWTs).
016 *
017 * @author Vladimir Dzhuvinov
018 * @version 2015-08-20
019 */
020public interface JWTProcessor<C extends SecurityContext> {
021
022
023        /**
024         * Parses and processes the specified JWT (unsecured, signed or
025         * encrypted).
026         *
027         * @param jwtString The JWT, compact-encoded to a URL-safe string. Must
028         *                  not be {@code null}.
029         * @param context   Optional context of the JOSE object, {@code null}
030         *                  if not required.
031         *
032         * @return The JWT claims set on success.
033         *
034         * @throws ParseException   If the string couldn't be parsed to a valid
035         *                          JWT.
036         * @throws BadJOSEException If the JWT is rejected.
037         * @throws JOSEException    If an internal processing exception is
038         *                          encountered.
039         */
040        JWTClaimsSet process(final String jwtString, final C context)
041                throws ParseException, BadJOSEException, JOSEException;
042
043
044        /**
045         * Processes the specified JWT (unsecured, signed or encrypted).
046         *
047         * @param jwt     The JWT. Must not be {@code null}.
048         * @param context Optional context of the JOSE object, {@code null} if
049         *                not required.
050         *
051         * @return The JWT claims set on success.
052         *
053         * @throws BadJOSEException If the JWT is rejected.
054         * @throws JOSEException    If an internal processing exception is
055         *                          encountered.
056         */
057        JWTClaimsSet process(final JWT jwt, final C context)
058                throws BadJOSEException, JOSEException;
059
060
061        /**
062         * Processes the specified unsecured (plain) JWT, typically by checking
063         * its context.
064         *
065         * @param plainJWT The unsecured (plain) JWT. Not {@code null}.
066         * @param context  Optional context of the unsecured JWT, {@code null}
067         *                 if not required.
068         *
069         * @return The JWT claims set on success.
070         *
071         * @throws BadJOSEException If the unsecured (plain) JWT is rejected,
072         *                          after examining the context or due to the
073         *                          payload not being a JSON object.
074         * @throws JOSEException    If an internal processing exception is
075         *                          encountered.
076         */
077        JWTClaimsSet process(final PlainJWT plainJWT, final C context)
078                throws BadJOSEException, JOSEException;
079
080
081        /**
082         * Processes the specified signed JWT by verifying its signature. The
083         * key candidate(s) are selected by examining the JWS header and / or
084         * the message context.
085         *
086         * @param signedJWT The signed JWT. Not {@code null}.
087         * @param context   Optional context of the signed JWT, {@code null} if
088         *                  not required.
089         *
090         * @return The JWT claims set on success.
091         *
092         * @throws BadJOSEException If the signed JWT is rejected, typically
093         *                          due to a bad signature or the payload not
094         *                          being a JSON object.
095         * @throws JOSEException    If an internal processing exception is
096         *                          encountered.
097         */
098        JWTClaimsSet process(final SignedJWT signedJWT, final C context)
099                throws BadJOSEException, JOSEException;
100
101
102        /**
103         * Processes the specified encrypted JWT by decrypting it. The key
104         * candidate(s) are selected by examining the JWS header and / or the
105         * message context.
106         *
107         * @param encryptedJWT The encrypted JWT. Not {@code null}.
108         * @param context      Optional context of the encrypted JWT,
109         *                     {@code null} if not required.
110         *
111         * @return The JWT claims set on success.
112         *
113         * @throws BadJOSEException If the encrypted JWT is rejected, typically
114         *                          due to failed decryption or the payload not
115         *                          being a JSON object.
116         * @throws JOSEException    If an internal processing exception is
117         *                          encountered.
118         */
119        JWTClaimsSet process(final EncryptedJWT encryptedJWT, final C context)
120                throws BadJOSEException, JOSEException;
121}