Skip to main content

IKeyEncryptor<TJsonWebKey> Interface

Abblix.Jwt​

Abblix.Jwt.Encryption​

IKeyEncryptor<TJsonWebKey> Interface​

Interface for JWE (JSON Web Encryption) key encryption and decryption operations. Encrypts and decrypts the Content Encryption Key (CEK) using a specific key management algorithm. Implements RFC 7516 Section 5 (Key Encryption) and RFC 7518 Section 4 (Key Management Algorithms).

public interface IKeyEncryptor<in TJsonWebKey>
    where TJsonWebKey : Abblix.Jwt.JsonWebKey

Type parameters​

TJsonWebKey​

The specific type of JSON Web Key required by this encryptor implementation.

Remarks​

The key encryptor handles the "alg" (algorithm) parameter in the JWE header, which specifies how the CEK is encrypted using the recipient's key. This is separate from the "enc" parameter, which specifies how the actual content is encrypted using the CEK. Common key encryption algorithms include RSA-OAEP, RSA-OAEP-256, RSA1_5, ECDH-ES, and AES key wrap.

Methods​

IKeyEncryptor<TJsonWebKey>.EncryptKey(JsonWebTokenHeader, TJsonWebKey, byte[]) Method​

Encrypts a Content Encryption Key (CEK) using the configured key management algorithm. Used when creating JWE tokens to protect the CEK with the recipient's public key.

byte[] EncryptKey(Abblix.Jwt.JsonWebTokenHeader header, TJsonWebKey encryptionKey, byte[] keyToEncrypt);

Parameters​

header JsonWebTokenHeader​

The JWE header that can be modified to add algorithm-specific parameters (e.g., "epk" for ECDH-ES).

encryptionKey TJsonWebKey​

The JSON Web Key containing the public key material for encryption.

keyToEncrypt System.Byte[]​

The randomly generated Content Encryption Key bytes to protect.

Returns​

System.Byte[]
The encrypted CEK bytes that will be placed in the JWE "encrypted_key" field. For RSA algorithms, output size equals the RSA key size in bytes. For direct key agreement (ECDH-ES), returns empty array per RFC 7518.

Exceptions​

System.InvalidOperationException
Thrown when the key type is not supported for the configured algorithm.

System.Security.Cryptography.CryptographicException
Thrown when encryption fails (e.g., CEK too large for RSA key size).

IKeyEncryptor<TJsonWebKey>.TryDecryptKey(JsonWebTokenHeader, TJsonWebKey, byte[], byte[]) Method​

Attempts to decrypt an encrypted Content Encryption Key (CEK) using the configured key management algorithm. Used when validating JWE tokens where multiple decryption keys may be tried sequentially.

bool TryDecryptKey(Abblix.Jwt.JsonWebTokenHeader header, TJsonWebKey decryptingKey, byte[] encryptedKey, out byte[]? decryptedKey);

Parameters​

header JsonWebTokenHeader​

The JWE header containing algorithm-specific parameters (e.g., "epk" for ECDH-ES).

decryptingKey TJsonWebKey​

The JSON Web Key containing the private key material for decryption.

encryptedKey System.Byte[]​

The encrypted CEK bytes from the JWE "encrypted_key" field.

decryptedKey System.Byte[]​

When this method returns true, contains the decrypted Content Encryption Key. When this method returns false, this parameter is null.

Returns​

System.Boolean
True if decryption succeeded with the provided key; otherwise, false. False typically indicates the wrong private key was used or the data is corrupted.

Remarks​

This method does not throw exceptions for decryption failures to support trying multiple keys. Only cryptographic operation errors (not authentication failures) should throw exceptions.