001/*
002 * nimbus-jose-jwt
003 *
004 * Copyright 2012-2016, Connect2id Ltd.
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use
007 * this file except in compliance with the License. You may obtain a copy of the
008 * License at
009 *
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software distributed
013 * under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
014 * CONDITIONS OF ANY KIND, either express or implied. See the License for the
015 * specific language governing permissions and limitations under the License.
016 */
017
018package com.nimbusds.jwt.proc;
019
020
021import java.text.ParseException;
022
023import com.nimbusds.jose.JOSEException;
024import com.nimbusds.jose.proc.BadJOSEException;
025import com.nimbusds.jose.proc.SecurityContext;
026import com.nimbusds.jwt.*;
027
028
029/**
030 * Interface for parsing and processing {@link com.nimbusds.jwt.PlainJWT
031 * unsecured} (plain), {@link com.nimbusds.jwt.SignedJWT signed} and
032 * {@link com.nimbusds.jwt.EncryptedJWT encrypted} JSON Web Tokens (JWTs).
033 * An optional context parameter is available to facilitate passing of
034 * additional data between the caller and the underlying JOSE processor (in
035 * both directions).
036 *
037 * @author Vladimir Dzhuvinov
038 * @version 2015-08-20
039 */
040public interface JWTProcessor<C extends SecurityContext> {
041
042
043        /**
044         * Parses and processes the specified JWT (unsecured, signed or
045         * encrypted).
046         *
047         * @param jwtString The JWT, compact-encoded to a URL-safe string. Must
048         *                  not be {@code null}.
049         * @param context   Optional context, {@code null} if not required.
050         *
051         * @return The JWT claims set on success.
052         *
053         * @throws ParseException   If the string couldn't be parsed to a valid
054         *                          JWT.
055         * @throws BadJOSEException If the JWT is rejected.
056         * @throws JOSEException    If an internal processing exception is
057         *                          encountered.
058         */
059        JWTClaimsSet process(final String jwtString, final C context)
060                throws ParseException, BadJOSEException, JOSEException;
061
062
063        /**
064         * Processes the specified JWT (unsecured, signed or encrypted).
065         *
066         * @param jwt     The JWT. Must not be {@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 JWT is rejected.
072         * @throws JOSEException    If an internal processing exception is
073         *                          encountered.
074         */
075        JWTClaimsSet process(final JWT jwt, final C context)
076                throws BadJOSEException, JOSEException;
077
078
079        /**
080         * Processes the specified unsecured (plain) JWT, typically by checking
081         * its context.
082         *
083         * @param plainJWT The unsecured (plain) JWT. Not {@code null}.
084         * @param context  Optional context, {@code null} if not required.
085         *
086         * @return The JWT claims set on success.
087         *
088         * @throws BadJOSEException If the unsecured (plain) JWT is rejected,
089         *                          after examining the context or due to the
090         *                          payload not being a JSON object.
091         * @throws JOSEException    If an internal processing exception is
092         *                          encountered.
093         */
094        JWTClaimsSet process(final PlainJWT plainJWT, final C context)
095                throws BadJOSEException, JOSEException;
096
097
098        /**
099         * Processes the specified signed JWT by verifying its signature. The
100         * key candidate(s) are selected by examining the JWS header and / or
101         * the message context.
102         *
103         * @param signedJWT The signed JWT. Not {@code null}.
104         * @param context   Optional context, {@code null} if not required.
105         *
106         * @return The JWT claims set on success.
107         *
108         * @throws BadJOSEException If the signed JWT is rejected, typically
109         *                          due to a bad signature or the payload not
110         *                          being a JSON object.
111         * @throws JOSEException    If an internal processing exception is
112         *                          encountered.
113         */
114        JWTClaimsSet process(final SignedJWT signedJWT, final C context)
115                throws BadJOSEException, JOSEException;
116
117
118        /**
119         * Processes the specified encrypted JWT by decrypting it. The key
120         * candidate(s) are selected by examining the JWS header and / or the
121         * message context.
122         *
123         * @param encryptedJWT The encrypted JWT. Not {@code null}.
124         * @param context      Optional context, {@code null} if not required.
125         *
126         * @return The JWT claims set on success.
127         *
128         * @throws BadJOSEException If the encrypted JWT is rejected, typically
129         *                          due to failed decryption or the payload not
130         *                          being a JSON object.
131         * @throws JOSEException    If an internal processing exception is
132         *                          encountered.
133         */
134        JWTClaimsSet process(final EncryptedJWT encryptedJWT, final C context)
135                throws BadJOSEException, JOSEException;
136}