gossamer/crypto

Cross-runtime bindings for the Web Cryptography API. The top-level Crypto interface (random_uuid) lives here, along with types shared across gossamer/crypto/key, gossamer/crypto/subtle, and gossamer/crypto/jwk. For cryptographically strong random bytes, use gleam_crypto.strong_random_bytes.

Types

AesAlgorithm

</>

AES cipher modes supported by subtle.

pub type AesAlgorithm {
  Cbc
  Ctr
  Gcm
  Kw
}

Constructors

```
Cbc
```
AES with Cipher Block Chaining — symmetric encryption.
```
Ctr
```
AES with Counter mode — symmetric encryption.
```
Gcm
```
AES with Galois/Counter Mode — authenticated symmetric encryption.
```
Kw
```
AES Key Wrap — symmetric encryption of another key.

CryptoError

</>

Errors raised by subtle operations.

pub type CryptoError {
  KeyUsageMismatch(usage: KeyUsage)
  KeyNotExtractable
  AlgorithmNotSupported
  InvalidAccess
  OperationFailed
  DataMalformed
  QuotaExceeded
  InvalidSyntax
}

Constructors

```
KeyUsageMismatch(usage: KeyUsage)
```
The key’s usages don’t include the capability required for this operation (e.g., calling encrypt with a key whose usages don’t include Encrypt). The usage payload names the missing capability.
```
KeyNotExtractable
```
The key’s extractable flag is False, but the operation (export_key, export_key_jwk, wrap_key, wrap_key_jwk) requires it.
```
AlgorithmNotSupported
```
The runtime does not support the requested algorithm or algorithm/operation combination. Corresponds to the NotSupportedError DOMException.
```
InvalidAccess
```
The key is not appropriate for the requested operation (e.g., using an asymmetric key in a symmetric operation). Corresponds to the InvalidAccessError DOMException.
```
OperationFailed
```
The cryptographic operation failed for an operation-specific reason — authenticated decryption failed, signature verification produced an invalid result, etc. Corresponds to the OperationError DOMException.
```
DataMalformed
```
The input data is malformed for the operation (e.g., an imported key has the wrong structure). Corresponds to the DataError DOMException.
```
QuotaExceeded
```
The input exceeds runtime-imposed size limits. Corresponds to the QuotaExceededError DOMException.
```
InvalidSyntax
```
A required parameter is missing or invalid for the algorithm (e.g., an empty usages list when generating or importing a symmetric key, or an out-of-range numeric parameter). Corresponds to the SyntaxError DOMException and the TypeError rejections from invalid numeric parameters.

EcAlgorithm

</>

Elliptic curve algorithms supported by subtle.

pub type EcAlgorithm {
  Dh
  Dsa
}

Constructors

```
Dh
```
Elliptic Curve Diffie-Hellman — key agreement.
```
Dsa
```
Elliptic Curve Digital Signature Algorithm — signing.

HashAlgorithm

</>

Cryptographic hash algorithms supported by subtle.

pub type HashAlgorithm {
  Sha1
  Sha256
  Sha384
  Sha512
}

Constructors

```
Sha1
```
SHA-1 — included for legacy compatibility; avoid for new signatures.
```
Sha256
```
SHA-2 with 256-bit output.
```
Sha384
```
SHA-2 with 384-bit output.
```
Sha512
```
SHA-2 with 512-bit output.

KeyAlgorithm

</>

The algorithm and parameters bound to a CryptoKey, exposed via the algorithm field on crypto/key.Info.

pub type KeyAlgorithm {
  Aes(name: AesAlgorithm, length: Int)
  Ec(name: EcAlgorithm, named_curve: NamedCurve)
  Ed25519
  Hkdf
  Hmac(hash: HashAlgorithm, length: Int)
  Pbkdf2
  Rsa(
    name: RsaAlgorithm,
    modulus_length: Int,
    public_exponent: BitArray,
    hash: HashAlgorithm,
  )
  X25519
}

Constructors

```
Aes(name: AesAlgorithm, length: Int)
```
An AES key. length is the key size in bits (128, 192, or 256).

Ec(name: EcAlgorithm, named_curve: NamedCurve)

An elliptic-curve key bound to named_curve.

```
Ed25519
```
An Ed25519 signing key.
```
Hkdf
```
An HKDF base key for key derivation.
```
Hmac(hash: HashAlgorithm, length: Int)
```
An HMAC key bound to hash with length bits of key material.
```
Pbkdf2
```
A PBKDF2 base key for password-based derivation.
```
Rsa(
  name: RsaAlgorithm,
  modulus_length: Int,
  public_exponent: BitArray,
  hash: HashAlgorithm,
)
```
An RSA key with modulus_length bits and the given hash. public_exponent is the raw bytes of the exponent (commonly <<1, 0, 1>> for 65537).
```
X25519
```
An X25519 key-agreement key.

KeyKind

</>

Whether a CryptoKey is public, private, or secret (symmetric).

pub type KeyKind {
  Private
  Public
  Secret
}

Constructors

```
Private
```
The private half of an asymmetric key pair.
```
Public
```
The public half of an asymmetric key pair.
```
Secret
```
A symmetric key (e.g., AES, HMAC).

KeyUsage

</>

An allowed use for a CryptoKey. A key can only be used with operations matching one of its declared usages.

pub type KeyUsage {
  Decrypt
  DeriveBits
  DeriveKey
  Encrypt
  Sign
  UnwrapKey
  Verify
  WrapKey
}

Constructors

```
Decrypt
```
The key may be used to decrypt ciphertext.
```
DeriveBits
```
The key may be used to derive raw byte material.
```
DeriveKey
```
The key may be used to derive another CryptoKey.
```
Encrypt
```
The key may be used to encrypt plaintext.
```
Sign
```
The key may be used to produce a signature.
```
UnwrapKey
```
The key may be used to decrypt a wrapped key.
```
Verify
```
The key may be used to verify a signature.
```
WrapKey
```
The key may be used to encrypt another key for transport.

NamedCurve

</>

A named elliptic curve used by ECDH and ECDSA operations in subtle.

pub type NamedCurve {
  P256
  P384
  P521
}

Constructors

```
P256
```
NIST P-256 (secp256r1).
```
P384
```
NIST P-384 (secp384r1).
```
P521
```
NIST P-521 (secp521r1).

RsaAlgorithm

</>

RSA algorithms supported by subtle.

pub type RsaAlgorithm {
  Oaep
  Pss
  SsaPkcs1V15
}

Constructors

```
Oaep
```
RSA with Optimal Asymmetric Encryption Padding — asymmetric encryption.
```
Pss
```
RSA with Probabilistic Signature Scheme — asymmetric signing.
```
SsaPkcs1V15
```
RSA with PKCS #1 v1.5 padding — legacy asymmetric signing.

Values

random_uuid

</>

pub fn random_uuid() -> String

Generates a random UUID (version 4).