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. An optional context
013 * parameter is available to facilitate passing of additional data between the
014 * caller and the underlying JOSE processor (in both directions).
015 *
016 * @author Vladimir Dzhuvinov
017 * @version 2015-08-20
018 */
019public interface JOSEProcessor<C extends SecurityContext> {
020
021
022        /**
023         * Parses and processes the specified JOSE object (unsecured, JWS or
024         * JWE).
025         *
026         * @param compactEncodedJOSE The JOSE object, compact-encoded to a
027         *                           URL-safe string. Must not be {@code null}.
028         * @param context            Optional context, {@code null} if not
029         *                           required.
030         *
031         * @return The payload on success.
032         *
033         * @throws ParseException   If the string couldn't be parsed to a valid
034         *                          JOSE object.
035         * @throws BadJOSEException If the JOSE object is rejected.
036         * @throws JOSEException    If an internal processing exception is
037         *                          encountered.
038         */
039        Payload process(final String compactEncodedJOSE, final C context)
040                throws ParseException, BadJOSEException, JOSEException;
041
042
043        /**
044         * Processes the specified JOSE object (unsecured, JWS or JWE).
045         *
046         * @param joseObject The JOSE object. Must not be {@code null}.
047         * @param context    Optional context, {@code null} if not required.
048         *
049         * @return The payload on success.
050         *
051         * @throws BadJOSEException If the JOSE object is rejected.
052         * @throws JOSEException    If an internal processing exception is
053         *                          encountered.
054         */
055        Payload process(final JOSEObject joseObject, final C context)
056                throws BadJOSEException, JOSEException;
057
058
059        /**
060         * Processes the specified unsecured (plain) JOSE object, typically by
061         * checking its context.
062         *
063         * @param plainObject The unsecured (plain) JOSE object. Not
064         *                    {@code null}.
065         * @param context     Optional context, {@code null} if not required.
066         *
067         * @return The payload on success.
068         *
069         * @throws BadJOSEException If the unsecured (plain) JOSE object is
070         *                          rejected.
071         * @throws JOSEException    If an internal processing exception is
072         *                          encountered.
073         */
074        Payload process(final PlainObject plainObject, final C context)
075                throws BadJOSEException, JOSEException;
076
077
078        /**
079         * Processes the specified JWS object by verifying its signature. The
080         * key candidate(s) are selected by examining the JWS header and / or
081         * the message context.
082         *
083         * @param jwsObject The JWS object. Not {@code null}.
084         * @param context   Optional context, {@code null} if not required.
085         *
086         * @return The payload on success.
087         *
088         * @throws BadJOSEException If the JWS object is rejected, typically
089         *                          due to a bad signature.
090         * @throws JOSEException    If an internal processing exception is
091         *                          encountered.
092         */
093        Payload process(final JWSObject jwsObject, final C context)
094                throws BadJOSEException, JOSEException;
095
096
097        /**
098         * Processes the specified JWE object by decrypting it. The key
099         * candidate(s) are selected by examining the JWS header and / or the
100         * message context.
101         *
102         * @param jweObject The JWE object. Not {@code null}.
103         * @param context   Optional context of the JWE object, {@code null} if
104         *                  not required.
105         *
106         * @return The payload on success.
107         *
108         * @throws BadJOSEException If the JWE object is rejected, typically
109         *                          due to failed decryption.
110         * @throws JOSEException    If an internal processing exception is
111         *                          encountered.
112         */
113        Payload process(final JWEObject jweObject, final C context)
114                throws BadJOSEException, JOSEException;
115}
116