gose/jwa

JSON Web Algorithms (JWA) - RFC 7518

This module defines the cryptographic algorithms used for signing (JWS) and encryption (JWE) operations.

Types

AesKeySize

AES key sizes.

pub type AesKeySize {
  Aes128
  Aes192
  Aes256
}

Constructors

```
Aes128
```
128-bit AES key
```
Aes192
```
192-bit AES key
```
Aes256
```
256-bit AES key

AesKwMode

</>

AES key wrapping modes.

pub type AesKwMode {
  AesKw
  AesGcmKw
}

Constructors

```
AesKw
```
AES Key Wrap (RFC 3394)
```
AesGcmKw
```
AES-GCM Key Wrap

ChaCha20Kw

</>

ChaCha20-Poly1305 key wrapping variants.

pub type ChaCha20Kw {
  C20PKw
  XC20PKw
}

Constructors

```
C20PKw
```
ChaCha20-Poly1305 Key Wrap (12-byte nonce)
```
XC20PKw
```
XChaCha20-Poly1305 Key Wrap (24-byte nonce)

EcdhEsAlg

</>

ECDH-ES key agreement algorithm variants.

pub type EcdhEsAlg {
  EcdhEsDirect
  EcdhEsAesKw(AesKeySize)
  EcdhEsChaCha20Kw(ChaCha20Kw)
}

Constructors

```
EcdhEsDirect
```
ECDH-ES using Concat KDF (direct key agreement)
```
EcdhEsAesKw(AesKeySize)
```
ECDH-ES using Concat KDF and AES Key Wrap
```
EcdhEsChaCha20Kw(ChaCha20Kw)
```
ECDH-ES using Concat KDF and ChaCha20-Poly1305 Key Wrap

EcdsaAlg

</>

ECDSA signing algorithm variants.

pub type EcdsaAlg {
  EcdsaP256
  EcdsaP384
  EcdsaP521
  EcdsaSecp256k1
}

Constructors

```
EcdsaP256
```
ECDSA using P-256 and SHA-256
```
EcdsaP384
```
ECDSA using P-384 and SHA-384
```
EcdsaP521
```
ECDSA using P-521 and SHA-512
```
EcdsaSecp256k1
```
ECDSA using secp256k1 and SHA-256 (RFC 8812)

Enc

</>

JWE content encryption algorithms.

pub type Enc {
  AesGcm(AesKeySize)
  AesCbcHmac(AesKeySize)
  ChaCha20Poly1305
  XChaCha20Poly1305
}

Constructors

```
AesGcm(AesKeySize)
```
AES-GCM content encryption
```
AesCbcHmac(AesKeySize)
```
AES-CBC with HMAC composite AEAD (CEK is double the AES key size)
```
ChaCha20Poly1305
```
ChaCha20-Poly1305
```
XChaCha20Poly1305
```
XChaCha20-Poly1305

HmacAlg

</>

HMAC signing algorithm variants.

pub type HmacAlg {
  HmacSha256
  HmacSha384
  HmacSha512
}

Constructors

```
HmacSha256
```
HMAC using SHA-256
```
HmacSha384
```
HMAC using SHA-384
```
HmacSha512
```
HMAC using SHA-512

JweAlg

</>

JWE key encryption algorithms.

pub type JweAlg {
  JweDirect
  JweAesKeyWrap(AesKwMode, AesKeySize)
  JweChaCha20KeyWrap(ChaCha20Kw)
  JweRsa(RsaJweAlg)
  JweEcdhEs(EcdhEsAlg)
  JwePbes2(Pbes2Alg)
}

Constructors

```
JweDirect
```
Direct use of a shared symmetric key
```
JweAesKeyWrap(AesKwMode, AesKeySize)
```
AES Key Wrap (standard or GCM mode)
```
JweChaCha20KeyWrap(ChaCha20Kw)
```
ChaCha20-Poly1305 Key Wrap
```
JweRsa(RsaJweAlg)
```
RSA key encryption
```
JweEcdhEs(EcdhEsAlg)
```
ECDH-ES key agreement
```
JwePbes2(Pbes2Alg)
```
PBES2 password-based encryption

JwsAlg

</>

JWS signing algorithms.

pub type JwsAlg {
  JwsHmac(HmacAlg)
  JwsRsaPkcs1(RsaPkcs1Alg)
  JwsRsaPss(RsaPssAlg)
  JwsEcdsa(EcdsaAlg)
  JwsEddsa
}

Constructors

```
JwsHmac(HmacAlg)
```
HMAC-based signing
```
JwsRsaPkcs1(RsaPkcs1Alg)
```
RSA PKCS#1 v1.5 signing
```
JwsRsaPss(RsaPssAlg)
```
RSA-PSS signing
```
JwsEcdsa(EcdsaAlg)
```
ECDSA signing
```
JwsEddsa
```
EdDSA (Ed25519 or Ed448, curve determined by key)

Pbes2Alg

</>

PBES2 key encryption algorithm variants.

pub type Pbes2Alg {
  Pbes2Sha256Aes128Kw
  Pbes2Sha384Aes192Kw
  Pbes2Sha512Aes256Kw
}

Constructors

```
Pbes2Sha256Aes128Kw
```
PBES2 with HMAC-SHA-256 and A128KW wrapping
```
Pbes2Sha384Aes192Kw
```
PBES2 with HMAC-SHA-384 and A192KW wrapping
```
Pbes2Sha512Aes256Kw
```
PBES2 with HMAC-SHA-512 and A256KW wrapping

RsaJweAlg

</>

RSA JWE key encryption algorithm variants.

pub type RsaJweAlg {
  RsaPkcs1v15
  RsaOaepSha1
  RsaOaepSha256
}

Constructors

```
RsaPkcs1v15
```
RSAES PKCS1 v1.5 key encryption.

Security Warning: Vulnerable to padding oracle attacks (Bleichenbacher). Use only for interoperability with legacy systems that require RSA1_5. Prefer RsaOaepSha1 or RsaOaepSha256 for new applications.

Note: Decryption may fail on Node.js 20.x (CVE-2023-46809).
```
RsaOaepSha1
```
RSAES OAEP using default parameters
```
RsaOaepSha256
```
RSAES OAEP using SHA-256 and MGF1 with SHA-256

RsaPkcs1Alg

</>

RSA PKCS#1 v1.5 signing algorithm variants.

pub type RsaPkcs1Alg {
  RsaPkcs1Sha256
  RsaPkcs1Sha384
  RsaPkcs1Sha512
}

Constructors

```
RsaPkcs1Sha256
```
RSA PKCSv1.5 using SHA-256
```
RsaPkcs1Sha384
```
RSA PKCSv1.5 using SHA-384
```
RsaPkcs1Sha512
```
RSA PKCSv1.5 using SHA-512

RsaPssAlg

</>

RSA-PSS signing algorithm variants.

pub type RsaPssAlg {
  RsaPssSha256
  RsaPssSha384
  RsaPssSha512
}

Constructors

```
RsaPssSha256
```
RSA-PSS using SHA-256 (RSASSA-PSS)
```
RsaPssSha384
```
RSA-PSS using SHA-384 (RSASSA-PSS)
```
RsaPssSha512
```
RSA-PSS using SHA-512 (RSASSA-PSS)

Values

aes_key_size_in_bytes

</>

pub fn aes_key_size_in_bytes(size: AesKeySize) -> Int

Returns the key size in bytes for an AES key size variant.

Parameters

size - The AES key size variant to query.

Returns

The key size in bytes (16, 24, or 32).

chacha20_kw_nonce_size

</>

pub fn chacha20_kw_nonce_size(variant: ChaCha20Kw) -> Int

Returns the nonce size in bytes for a ChaCha20 key wrapping variant.

Parameters

variant - The ChaCha20 key wrapping variant (C20PKw or XC20PKw).

Returns

The nonce size in bytes (12 for C20PKW, 24 for XC20PKW).

enc_from_string

</>

pub fn enc_from_string(
  alg: String,
) -> Result(Enc, gose.GoseError)

Parse a content encryption algorithm from its RFC string representation.

Parameters

alg - The RFC 7518 string identifier (e.g. "A256GCM", "C20P").

Returns

Ok(Enc) with the parsed encryption algorithm variant, or Error(ParseError) if the string is not a recognized encryption algorithm.

enc_octet_key_size

</>

pub fn enc_octet_key_size(enc: Enc) -> Int

Returns the content encryption key (CEK) size in bytes for a content encryption algorithm.

Parameters

enc - The content encryption algorithm to query.

Returns

The key size in bytes. Every Enc variant has a defined key size. For AesCbcHmac, the CEK is double the AES key size because it is split into separate HMAC and AES-CBC keys.

enc_to_string

</>

pub fn enc_to_string(alg: Enc) -> String

Convert a content encryption algorithm to its RFC string representation.

Parameters

alg - The content encryption algorithm variant to convert.

Returns

The RFC 7518 string identifier (e.g. "A256GCM", "C20P").

hmac_alg_octet_key_size

</>

pub fn hmac_alg_octet_key_size(alg: HmacAlg) -> Int

Returns the recommended symmetric key size in bytes for an HMAC algorithm.

Parameters

alg - The HMAC algorithm variant to query.

Returns

The key size in bytes (32, 48, or 64).

jwe_alg_from_string

</>

pub fn jwe_alg_from_string(
  alg: String,
) -> Result(JweAlg, gose.GoseError)

Parse a JWE key encryption algorithm from its RFC string representation.

Parameters

alg - The RFC 7518 string identifier (e.g. "dir", "RSA-OAEP").

Returns

Ok(JweAlg) with the parsed algorithm variant, or Error(ParseError) if the string is not a recognized JWE algorithm.

jwe_alg_to_string

</>

pub fn jwe_alg_to_string(alg: JweAlg) -> String

Convert a JWE key encryption algorithm to its RFC string representation.

Parameters

alg - The JWE key encryption algorithm variant to convert.

Returns

The RFC 7518 string identifier (e.g. "dir", "RSA-OAEP-256").

jws_alg_from_string

</>

pub fn jws_alg_from_string(
  alg: String,
) -> Result(JwsAlg, gose.GoseError)

Parse a JWS algorithm from its RFC string representation.

Parameters

alg - The RFC 7518 string identifier (e.g. "HS256", "EdDSA").

Returns

Ok(JwsAlg) with the parsed algorithm variant, or Error(ParseError) if the string is not a recognized JWS algorithm.

jws_alg_to_string

</>

pub fn jws_alg_to_string(alg: JwsAlg) -> String

Convert a JWS algorithm to its RFC string representation.

Parameters

alg - The JWS algorithm variant to convert.

Returns

The RFC 7518 string identifier (e.g. "HS256", "EdDSA").