io.jsonwebtoken.security.DigestAlgorithm Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of jjwt-api Show documentation

There is a newer version: 0.12.6

/*
 * Copyright © 2022 jsonwebtoken.io
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package io.jsonwebtoken.security;

import io.jsonwebtoken.Identifiable;
import io.jsonwebtoken.lang.Registry;

import javax.crypto.SecretKey;
import java.io.InputStream;
import java.security.PrivateKey;
import java.security.PublicKey;

/**
 * A {@code DigestAlgorithm} is a
 * Cryptographic Hash Function
 * that computes and verifies cryptographic digests.  There are three types of {@code DigestAlgorithm}s represented
 * by subtypes, and RFC-standard implementations are available as constants in {@link Registry} singletons:
 *
 * 
 *     
 *     
 *         
 *             
 *             
 *             
 *         
 *     
 *     
 *         
 *             
 *             
 *             
 *         
 *         
 *             
 *             
 *             
 *         
 *         
 *             
 *             
 *             
 *         
 *     
 * Types of {@code DigestAlgorithm}sSubtype Standard Implementation Registry Security Model
{@link HashAlgorithm} {@link Jwks.HASH} Unsecured (unkeyed), does not require a key to compute or verify digests.
{@link MacAlgorithm} {@link io.jsonwebtoken.Jwts.SIG Jwts.SIG} Requires a {@link SecretKey} to both compute and verify digests (aka
 *                 "Message Authentication Codes").
{@link SignatureAlgorithm} {@link io.jsonwebtoken.Jwts.SIG Jwts.SIG} Requires a {@link PrivateKey} to compute and {@link PublicKey} to verify digests
 *                 (aka "Digital Signatures").
 *
 * Standard Identifier
 *
 * {@code DigestAlgorithm} extends {@link Identifiable}: the value returned from
 * {@link Identifiable#getId() getId()} will be used as the JWT standard identifier where required.
 *
 * For example,
 * when a {@link MacAlgorithm} or {@link SignatureAlgorithm} is used to secure a JWS, the value returned from
 * {@code algorithm.getId()} will be used as the JWS "alg" protected header value.  Or when a
 * {@link HashAlgorithm} is used to compute a {@link JwkThumbprint}, it's {@code algorithm.getId()} value will be
 * used within the thumbprint's {@link JwkThumbprint#toURI() URI} per JWT RFC requirements.
 *
 * @param  the type of {@link Request} used when computing a digest.
 * @param  the type of {@link VerifyDigestRequest} used when verifying a digest.
 * @see Jwks.HASH
 * @see io.jsonwebtoken.Jwts.SIG Jwts.SIG
 * @since 0.12.0
 */
public interface DigestAlgorithm, V extends VerifyDigestRequest> extends Identifiable {

    /**
     * Returns a cryptographic digest of the request {@link Request#getPayload() payload}.
     *
     * @param request the request containing the data to be hashed, mac'd or signed.
     * @return a cryptographic digest of the request {@link Request#getPayload() payload}.
     * @throws SecurityException if there is invalid key input or a problem during digest creation.
     */
    byte[] digest(R request) throws SecurityException;

    /**
     * Returns {@code true} if the provided {@link VerifyDigestRequest#getDigest() digest} matches the expected value
     * for the given {@link VerifyDigestRequest#getPayload() payload}, {@code false} otherwise.
     *
     * @param request the request containing the {@link VerifyDigestRequest#getDigest() digest} to verify for the
     *                associated {@link VerifyDigestRequest#getPayload() payload}.
     * @return {@code true} if the provided {@link VerifyDigestRequest#getDigest() digest} matches the expected value
     * for the given {@link VerifyDigestRequest#getPayload() payload}, {@code false} otherwise.
     * @throws SecurityException if there is an invalid key input or a problem that won't allow digest verification.
     */
    boolean verify(V request) throws SecurityException;
}

Subtype	Standard Implementation Registry	Security Model
{@link HashAlgorithm}	{@link Jwks.HASH}	Unsecured (unkeyed), does not require a key to compute or verify digests.
{@link MacAlgorithm}	{@link io.jsonwebtoken.Jwts.SIG Jwts.SIG}	Requires a {@link SecretKey} to both compute and verify digests (aka * "Message Authentication Codes").
{@link SignatureAlgorithm}	{@link io.jsonwebtoken.Jwts.SIG Jwts.SIG}	Requires a {@link PrivateKey} to compute and {@link PublicKey} to verify digests * (aka "Digital Signatures").