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