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 * An optional context parameter is available to facilitate passing of
017 * additional data between the caller and the underlying JOSE processor (in
018 * both directions).
019 *
020 * @author Vladimir Dzhuvinov
021 * @version 2015-08-20
022 */
023public interface JWTProcessor<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, {@code null} if not required.
033         *
034         * @return The JWT claims set on success.
035         *
036         * @throws ParseException   If the string couldn't be parsed to a valid
037         *                          JWT.
038         * @throws BadJOSEException If the JWT is rejected.
039         * @throws JOSEException    If an internal processing exception is
040         *                          encountered.
041         */
042        JWTClaimsSet process(final String jwtString, final C context)
043                throws ParseException, BadJOSEException, JOSEException;
044
045
046        /**
047         * Processes the specified JWT (unsecured, signed or encrypted).
048         *
049         * @param jwt     The JWT. Must not be {@code null}.
050         * @param context Optional context, {@code null} if not required.
051         *
052         * @return The JWT claims set on success.
053         *
054         * @throws BadJOSEException If the JWT is rejected.
055         * @throws JOSEException    If an internal processing exception is
056         *                          encountered.
057         */
058        JWTClaimsSet process(final JWT jwt, final C context)
059                throws BadJOSEException, JOSEException;
060
061
062        /**
063         * Processes the specified unsecured (plain) JWT, typically by checking
064         * its context.
065         *
066         * @param plainJWT The unsecured (plain) JWT. Not {@code null}.
067         * @param context  Optional context, {@code null} 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, {@code null} if not required.
088         *
089         * @return The JWT claims set on success.
090         *
091         * @throws BadJOSEException If the signed JWT is rejected, typically
092         *                          due to a bad signature or the payload not
093         *                          being a JSON object.
094         * @throws JOSEException    If an internal processing exception is
095         *                          encountered.
096         */
097        JWTClaimsSet process(final SignedJWT signedJWT, final C context)
098                throws BadJOSEException, JOSEException;
099
100
101        /**
102         * Processes the specified encrypted JWT by decrypting it. The key
103         * candidate(s) are selected by examining the JWS header and / or the
104         * message context.
105         *
106         * @param encryptedJWT The encrypted JWT. Not {@code null}.
107         * @param context      Optional context, {@code null} if not required.
108         *
109         * @return The JWT claims set on success.
110         *
111         * @throws BadJOSEException If the encrypted JWT is rejected, typically
112         *                          due to failed decryption or the payload not
113         *                          being a JSON object.
114         * @throws JOSEException    If an internal processing exception is
115         *                          encountered.
116         */
117        JWTClaimsSet process(final EncryptedJWT encryptedJWT, final C context)
118                throws BadJOSEException, JOSEException;
119}