001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2015-2017 ForgeRock AS.
015 */
016
017package org.forgerock.tokenhandler;
018
019import org.forgerock.json.JsonValue;
020
021/**
022 * Responsible for the validation, generation and parsing of tokens used for keying a JsonValue
023 * representative of some state.  Implementers must catch implementation-specific exceptions
024 * and re-throw as {@link TokenHandlerException}.
025 */
026public interface TokenHandler {
027
028    /**
029     * Generates a new token using the state.
030     *
031     * @param state the state
032     * @return token
033     * @throws TokenHandlerException on failure to generate token
034     */
035    String generate(JsonValue state) throws TokenHandlerException;
036
037    /**
038     * Validates the passed token.
039     *
040     * @param token the token to be validated
041     * @throws InvalidTokenException on invalid token
042     * @throws ExpiredTokenException on expired token
043     * @throws TokenHandlerException on other failure to validate token
044     */
045    void validate(String token) throws TokenHandlerException;
046
047    /**
048     * Validates and parses the token, extracting any encapsulated state.
049     *
050     * @param token the token to be validated and parsed
051     * @return the state
052     * @throws InvalidTokenException on invalid token
053     * @throws ExpiredTokenException on expired token
054     * @throws TokenHandlerException on other failure to validate or extract token
055     */
056    JsonValue validateAndExtractState(String token) throws TokenHandlerException;
057}