module JOSE::JWE

Overview

JWE (JSON Web Encryption) compact serialization (RFC 7516).

The two header parameters that control how a JWE token is produced are defined in RFC 7516 §4.1:

alg — Key Management Algorithm (how the Content Encryption Key is protected):

enc — Content Encryption Algorithm (authenticated encryption of the plaintext using the CEK):

Defined in:

jose/jwe.cr

Class Method Summary

Class Method Detail

def self.block_decrypt(jwk : JWK, encrypted : String | EncryptedBinary) : String #

Decrypts a compact JWE using jwk, which must contain the private key (or the symmetric key for "dir" / AES Key Wrap algorithms).

encrypted may be either a raw compact serialization String or an EncryptedBinary returned by #block_encrypt. Raises ArgumentError if the string does not contain exactly five dot-separated parts.


[View source]
def self.block_decrypt(password : String, encrypted : String | EncryptedBinary) : String #

Decrypts a compact PBES2 JWE token using the given password. Reads alg, p2s, and p2c from the protected header to reconstruct the key-encryption key via PBKDF2, then unwraps the CEK and decrypts.


[View source]
def self.block_encrypt(jwk : JWK, plain_text : String, header_overrides : Hash(String, JSON::Any) | Nil = nil) : EncryptedBinary #

Encrypts plain_text for jwk and returns a compact EncryptedBinary.

header_overrides is an optional map that may contain:

  • "alg" — override the key-wrap algorithm (default is inferred from key type: EC → "ECDH-ES+A256KW", RSA → "RSA-OAEP", oct 16/24/32 bytes → "A128KW"/"A192KW"/"A256KW", other oct → "dir")
  • "enc" — override the content-encryption algorithm (default: "A256GCM")
  • "kid" — included verbatim in the protected header
  • Any other key — included in the protected header as-is
jwk = JOSE::JWK.generate_key({"kty" => JSON::Any.new("EC"), "crv" => JSON::Any.new("P-256")})
enc = JOSE::JWE.block_encrypt(jwk, "hello world")
plain = JOSE::JWE.block_decrypt(jwk, enc)

[View source]
def self.block_encrypt(password : String, plain_text : String, header_overrides : Hash(String, JSON::Any) | Nil = nil) : EncryptedBinary #

Encrypts plain_text using a PBES2 password-based key-wrap algorithm.

header_overrides may include:

  • "alg" — PBES2 variant; default is "PBES2-HS512+A256KW"
  • "enc" — content-encryption algorithm; default is "A256GCM"
  • "p2c" — PBKDF2 iteration count (integer); default is 310000
  • Any other key — included verbatim in the protected header

A random 16-byte salt input (p2s) is always generated and stored in the protected header alongside p2c.


[View source]
def self.json_decrypt(jwk : JWK, json : String) : String #

Decrypts a JWE JSON Serialization (RFC 7516 §7.2), either the Flattened or General form. For the general form with multiple recipients, iterates until a recipient whose encrypted_key can be unwrapped with jwk is found. Raises ArgumentError if no matching recipient exists.


[View source]
def self.json_encrypt(jwk : JWK, plain_text : String, header_overrides : Hash(String, JSON::Any) | Nil = nil, aad : Bytes | Nil = nil) : String #

Encrypts plain_text for jwk and returns a JWE Flattened JSON Serialization string (RFC 7516 §7.2.2).

All key-management parameters go into the protected header. An optional aad byte slice is base64url-encoded and stored as the "aad" member; it is also included in the AEAD computation.


[View source]
def self.peek_ciphertext(compact : String) : Bytes #

Returns the ciphertext bytes from compact.


[View source]
def self.peek_encrypted_key(compact : String) : Bytes #

Returns the wrapped CEK bytes from compact.


[View source]
def self.peek_iv(compact : String) : Bytes #

Returns the IV bytes from compact.


[View source]
def self.peek_protected(compact : String) : Hash(String, JSON::Any) #

Returns the decoded protected header from compact without decrypting.


[View source]
def self.peek_tag(compact : String) : Bytes #

Returns the authentication tag bytes from compact.


[View source]