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