io.jsonwebtoken.security

Interface AeadAlgorithm

All Superinterfaces:

Identifiable, KeyBuilderSupplier<SecretKey,SecretKeyBuilder>, KeyLengthSupplier

public interface AeadAlgorithm
extends Identifiable, KeyLengthSupplier, KeyBuilderSupplier<SecretKey,SecretKeyBuilder>

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 Jwts.ENC.

"enc" identifier

AeadAlgorithm extends Identifiable: the value returned from 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 AeadAlgorithm interface extends the 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

AeadAlgorithm extends KeyBuilderSupplier to enable SecretKey generation. Each AEAD algorithm instance will return a 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 key is guaranteed to have the correct algorithm parameters and strength/length necessary for that exact aeadAlgorithm instance.

Since:

0.12.0

See Also:

Jwts.ENC, Identifiable.getId(), KeyLengthSupplier, KeyBuilderSupplier, KeyBuilder

Method Summary

Methods

Modifier and Type	Method and Description
void	decrypt(DecryptAeadRequest request, OutputStream out) Decrypts ciphertext and authenticates any associated data, writing the decrypted plaintext to the provided output stream.
void	encrypt(AeadRequest req, AeadResult res) Encrypts plaintext and signs any associated data, placing the resulting ciphertext, initialization vector and authentication tag in the provided result.

Methods inherited from interface io.jsonwebtoken.Identifiable

getId

Methods inherited from interface io.jsonwebtoken.security.KeyLengthSupplier

getKeyBitLength

Methods inherited from interface io.jsonwebtoken.security.KeyBuilderSupplier

key

Method Detail

encrypt

void encrypt(AeadRequest req,
           AeadResult res)
             throws SecurityException

Encrypts plaintext and signs any associated data, placing the resulting ciphertext, initialization vector and authentication tag in the provided result.

Parameters:

req - the encryption request representing the plaintext to be encrypted, any additional integrity-protected data and the encryption key.

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.

decrypt

void decrypt(DecryptAeadRequest request,
           OutputStream out)
             throws SecurityException

Decrypts ciphertext and authenticates any associated data, writing the decrypted plaintext to the provided output stream.

Parameters:

request - the decryption request representing the ciphertext to be decrypted, any additional integrity-protected data, authentication tag, initialization vector, and decryption key

out - the OutputStream for writing decrypted plaintext

Throws:

SecurityException - if there is a decryption problem or authenticity assertions fail.