io.jsonwebtoken.security.KeyRequest 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.JweHeader;
/**
* A request to a {@link KeyAlgorithm} to obtain the key necessary for AEAD encryption or decryption. The exact
* {@link AeadAlgorithm} that will be used is accessible via {@link #getEncryptionAlgorithm()}.
*
* Encryption Requests
* For an encryption key request, {@link #getPayload()} will return
* the encryption key to use. Additionally, any public information specific to the called
* {@link KeyAlgorithm} implementation that is required to be transmitted in the JWE (such as an initialization vector,
* authentication tag or ephemeral key, etc) may be added to the JWE protected header, accessible via
* {@link #getHeader()}. Although the JWE header is checked for authenticity and integrity, it itself is
* not encrypted, so {@link KeyAlgorithm}s should never place any secret or private information in the
* header.
*
* Decryption Requests
* For a decryption request, the {@code KeyRequest} instance will be
* a {@link DecryptionKeyRequest} instance, {@link #getPayload()} will return the encrypted key ciphertext (a
* byte array), and the decryption key will be available via {@link DecryptionKeyRequest#getKey()}. Additionally,
* any public information necessary by the called {@link KeyAlgorithm} (such as an initialization vector,
* authentication tag, ephemeral key, etc) is expected to be available in the JWE protected header, accessible
* via {@link #getHeader()}.
*
* @param the type of object relevant during key algorithm cryptographic operations.
* @see DecryptionKeyRequest
* @since 0.12.0
*/
public interface KeyRequest extends Request {
/**
* Returns the {@link AeadAlgorithm} that will be called for encryption or decryption after processing the
* {@code KeyRequest}. {@link KeyAlgorithm} implementations that generate an ephemeral {@code SecretKey} to use
* as what the JWE specification calls a
* "Content Encryption Key (CEK)" should call the {@code AeadAlgorithm}'s
* {@link AeadAlgorithm#key() key()} builder to create a key suitable for that exact {@code AeadAlgorithm}.
*
* @return the {@link AeadAlgorithm} that will be called for encryption or decryption after processing the
* {@code KeyRequest}.
*/
AeadAlgorithm getEncryptionAlgorithm();
/**
* Returns the {@link JweHeader} that will be used to construct the final JWE header, available for
* reading or writing any {@link KeyAlgorithm}-specific information.
*
* For an encryption key request, any public information specific to the called {@code KeyAlgorithm}
* implementation that is required to be transmitted in the JWE (such as an initialization vector,
* authentication tag or ephemeral key, etc) is expected to be added to this header. Although the header is
* checked for authenticity and integrity, it itself is not encrypted, so
* {@link KeyAlgorithm}s should never place any secret or private information in the header.
*
* For a decryption request, any public information necessary by the called {@link KeyAlgorithm}
* (such as an initialization vector, authentication tag, ephemeral key, etc) is expected to be available in
* this header.
*
* @return the {@link JweHeader} that will be used to construct the final JWE header, available for
* reading or writing any {@link KeyAlgorithm}-specific information.
*/
JweHeader getHeader();
}