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