io.jsonwebtoken.security.AeadAlgorithm Maven / Gradle / Ivy
/*
* Copyright (C) 2021 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.Jwts;
import javax.crypto.SecretKey;
import java.io.OutputStream;
/**
* A cryptographic algorithm that performs
* Authenticated encryption with additional data.
* Per JWE RFC 7516, Section 4.1.2, all JWEs
* MUST use an AEAD algorithm to encrypt or decrypt the JWE payload/content. Consequently, all
* JWA "enc" algorithms are AEAD
* algorithms, and they are accessible as concrete instances via {@link Jwts.ENC}.
*
* "enc" identifier
*
* {@code AeadAlgorithm} extends {@code Identifiable}: the value returned from {@link Identifiable#getId() getId()}
* will be used as the JWE "enc" protected header value.
*
* Key Strength
*
* Encryption strength is in part attributed to how difficult it is to discover the encryption key. As such,
* cryptographic algorithms often require keys of a minimum length to ensure the keys are difficult to discover
* and the algorithm's security properties are maintained.
*
* The {@code AeadAlgorithm} interface extends the {@link KeyLengthSupplier} interface to represent the length
* in bits a key must have to be used with its implementation. If you do not want to worry about lengths and
* parameters of keys required for an algorithm, it is often easier to automatically generate a key that adheres
* to the algorithms requirements, as discussed below.
*
* Key Generation
*
* {@code AeadAlgorithm} extends {@link KeyBuilderSupplier} to enable {@link SecretKey} generation. Each AEAD
* algorithm instance will return a {@link KeyBuilder} that ensures any created keys will have a sufficient length
* and algorithm parameters required by that algorithm. For example:
*
*
* SecretKey key = aeadAlgorithm.key().build();
*
*
* The resulting {@code key} is guaranteed to have the correct algorithm parameters and strength/length necessary for
* that exact {@code aeadAlgorithm} instance.
*
* @see Jwts.ENC
* @see Identifiable#getId()
* @see KeyLengthSupplier
* @see KeyBuilderSupplier
* @see KeyBuilder
* @since 0.12.0
*/
public interface AeadAlgorithm extends Identifiable, KeyLengthSupplier, KeyBuilderSupplier {
/**
* Encrypts plaintext and signs any {@link AeadRequest#getAssociatedData() associated data}, placing the resulting
* ciphertext, initialization vector and authentication tag in the provided {@code result}.
*
* @param req the encryption request representing the plaintext to be encrypted, any additional
* integrity-protected data and the encryption key.
* @param res the result to write ciphertext, initialization vector and AAD authentication tag (aka digest)
* @throws SecurityException if there is an encryption problem or AAD authenticity cannot be guaranteed.
*/
void encrypt(AeadRequest req, AeadResult res) throws SecurityException;
/**
* Decrypts ciphertext and authenticates any {@link DecryptAeadRequest#getAssociatedData() associated data},
* writing the decrypted plaintext to the provided {@code out}put stream.
*
* @param request the decryption request representing the ciphertext to be decrypted, any additional
* integrity-protected data, authentication tag, initialization vector, and decryption key
* @param out the OutputStream for writing decrypted plaintext
* @throws SecurityException if there is a decryption problem or authenticity assertions fail.
*/
void decrypt(DecryptAeadRequest request, OutputStream out) throws SecurityException;
}