gossamer - v10.0.0

gossamer/crypto/subtle

The SubtleCrypto interface from the Web Cryptography API — the low-level cryptographic primitives. Operations include hashing (digest), symmetric and asymmetric encryption (encrypt, decrypt), signing and verification (sign, verify), key generation (generate_key, generate_key_pair), key derivation (derive_bits, derive_key), and key serialization (import_key, export_key, wrap_key, unwrap_key).

Every fallible operation returns Promise(Result(_, CryptoError)); digest cannot fail and returns Promise(BitArray) directly. Key-usage and extractability constraints are checked before dispatch and surface as typed CryptoError variants.

See SubtleCrypto on MDN.

Types

CryptoKeyPair

</>

A public/private key pair produced by generate_key_pair.

pub type CryptoKeyPair {
  CryptoKeyPair(
    public_key: key.CryptoKey,
    private_key: key.CryptoKey,
  )
}

Constructors

DeriveAlgorithm

</>

Algorithm parameters for derive_bits and derive_key.

pub type DeriveAlgorithm {
  DeriveHkdf(
    hash: crypto.HashAlgorithm,
    info: BitArray,
    salt: BitArray,
  )
  DerivePbkdf2(
    hash: crypto.HashAlgorithm,
    iterations: Int,
    salt: BitArray,
  )
  DeriveEcDh(public: key.CryptoKey)
  DeriveX25519(public: key.CryptoKey)
}

Constructors 

  • DeriveHkdf(
  hash: crypto.HashAlgorithm,
  info: BitArray,
  salt: BitArray,
)

    HMAC-based Key Derivation Function with the given hash, context-binding info, and salt.

  • DerivePbkdf2(
  hash: crypto.HashAlgorithm,
  iterations: Int,
  salt: BitArray,
)

    Password-Based Key Derivation Function 2 with the given hash, iterations, and salt.

  • DeriveEcDh(public: key.CryptoKey)

    Elliptic Curve Diffie-Hellman key agreement with the given peer public key.

  • DeriveX25519(public: key.CryptoKey)

    X25519 key agreement with the given peer public key.

EncryptAlgorithm

</>

Algorithm parameters for encrypt and decrypt.

pub type EncryptAlgorithm {
  EncryptAesCbc(iv: BitArray)
  EncryptAesGcm(
    iv: BitArray,
    additional_data: BitArray,
    tag_length: option.Option(Int),
  )
  EncryptAesCtr(counter: BitArray, length: Int)
  EncryptRsaOaep(label: BitArray)
}

Constructors 

  • EncryptAesCbc(iv: BitArray)

    AES-CBC with the given initialization vector.

  • EncryptAesGcm(
  iv: BitArray,
  additional_data: BitArray,
  tag_length: option.Option(Int),
)

    AES-GCM with the given initialization vector, additional authenticated data, and authentication tag_length in bits. Pass <<>> for additional_data for no additional authenticated data; pass None for tag_length for the spec default (128 bits).

  • EncryptAesCtr(counter: BitArray, length: Int)

    AES-CTR with the given counter block and counter length in bits.

  • EncryptRsaOaep(label: BitArray)

    RSA-OAEP with the given label. Pass <<>> for the spec default (no label).

ImportAlgorithm

</>

Algorithm parameters for import_key and import_key_jwk.

pub type ImportAlgorithm {
  ImportAes(name: crypto.AesAlgorithm)
  ImportHmac(hash: crypto.HashAlgorithm)
  ImportRsaHashed(
    name: crypto.RsaAlgorithm,
    hash: crypto.HashAlgorithm,
  )
  ImportEc(
    name: crypto.EcAlgorithm,
    named_curve: crypto.NamedCurve,
  )
  ImportEd25519
  ImportX25519
  ImportHkdf
  ImportPbkdf2
}

Constructors 

  • ImportAes(name: crypto.AesAlgorithm)

    Import a raw AES key for the given AES mode.

  • ImportHmac(hash: crypto.HashAlgorithm)

    Import an HMAC key with the given hash.

  • ImportRsaHashed(
  name: crypto.RsaAlgorithm,
  hash: crypto.HashAlgorithm,
)

    Import an RSA key with the given algorithm and hash.

  • ImportEc(
  name: crypto.EcAlgorithm,
  named_curve: crypto.NamedCurve,
)

    Import an elliptic-curve key with the given algorithm and named_curve.

  • ImportEd25519

    Import an Ed25519 signing key.

  • ImportX25519

    Import an X25519 key-agreement key.

  • ImportHkdf

    Import an HKDF base key for key derivation.

  • ImportPbkdf2

    Import a PBKDF2 base key for password-based derivation.

KeyFormat

</>

The serialization format of a key imported or exported via subtle.

pub type KeyFormat {
  Pkcs8
  Raw
  Spki
}

Constructors 

  • Pkcs8

    PKCS #8 — encoded private-key format.

  • Raw

    Raw byte material — used for symmetric keys.

  • Spki

    SubjectPublicKeyInfo — encoded public-key format.

KeyPairGenAlgorithm

</>

Algorithm parameters for generate_key_pair (asymmetric keys).

pub type KeyPairGenAlgorithm {
  KeyPairGenRsa(
    name: crypto.RsaAlgorithm,
    modulus_length: Int,
    public_exponent: BitArray,
    hash: crypto.HashAlgorithm,
  )
  KeyPairGenEc(
    name: crypto.EcAlgorithm,
    named_curve: crypto.NamedCurve,
  )
  KeyPairGenEd25519
  KeyPairGenX25519
}

Constructors 

  • KeyPairGenRsa(
  name: crypto.RsaAlgorithm,
  modulus_length: Int,
  public_exponent: BitArray,
  hash: crypto.HashAlgorithm,
)

    Generate an RSA key pair with modulus_length bits, the given public_exponent bytes, and hash.

  • KeyPairGenEc(
  name: crypto.EcAlgorithm,
  named_curve: crypto.NamedCurve,
)

    Generate an elliptic-curve key pair on named_curve.

  • KeyPairGenEd25519

    Generate an Ed25519 signing key pair.

  • KeyPairGenX25519

    Generate an X25519 key-agreement key pair.

SignAlgorithm

</>

Algorithm parameters for sign and verify.

pub type SignAlgorithm {
  SignHmac
  SignRsaSsaPkcs1V15
  SignRsaPss(salt_length: Int)
  SignEcDsa(hash: crypto.HashAlgorithm)
  SignEd25519
}

Constructors 

  • SignHmac

    Sign or verify with an HMAC key.

  • SignRsaSsaPkcs1V15

    Sign or verify with RSA-SSA-PKCS1-v1_5.

  • SignRsaPss(salt_length: Int)

    Sign or verify with RSA-PSS using salt_length bytes of salt.

  • SignEcDsa(hash: crypto.HashAlgorithm)

    Sign or verify with ECDSA using the given hash.

  • SignEd25519

    Sign or verify with Ed25519.

SymmetricKeyParams

</>

Symmetric-key parameters shared by generate_key and derive_key to describe the key to produce.

pub type SymmetricKeyParams {
  Aes(name: crypto.AesAlgorithm, length: Int)
  Hmac(hash: crypto.HashAlgorithm)
}

Constructors

WrapAlgorithm

</>

Algorithm parameters for wrap_key and unwrap_key.

pub type WrapAlgorithm {
  WrapAesCbc(iv: BitArray)
  WrapAesCtr(counter: BitArray, length: Int)
  WrapAesGcm(
    iv: BitArray,
    additional_data: BitArray,
    tag_length: option.Option(Int),
  )
  WrapAesKw
  WrapRsaOaep(label: BitArray)
}

Constructors 

  • WrapAesCbc(iv: BitArray)

    Wrap or unwrap with AES-CBC and the given initialization vector.

  • WrapAesCtr(counter: BitArray, length: Int)

    Wrap or unwrap with AES-CTR using the given counter block and counter length in bits.

  • WrapAesGcm(
  iv: BitArray,
  additional_data: BitArray,
  tag_length: option.Option(Int),
)

    Wrap or unwrap with AES-GCM, the given initialization vector, additional authenticated data, and authentication tag_length in bits. Pass <<>> for additional_data for no additional authenticated data; pass None for tag_length for the spec default (128 bits).

  • WrapAesKw

    Wrap or unwrap with AES Key Wrap (RFC 3394). The wrapping key must be an AES-KW CryptoKey.

  • WrapRsaOaep(label: BitArray)

    Wrap or unwrap with RSA-OAEP and the given label. Pass <<>> for the spec default (no label).

Values

decrypt

</> 
pub fn decrypt(
  algorithm algorithm: EncryptAlgorithm,
  key key: key.CryptoKey,
  data data: BitArray,
) -> promise.Promise(Result(BitArray, crypto.CryptoError))

Decrypts data with key using algorithm. Returns Error(KeyUsageMismatch(Decrypt)) if key.usages doesn’t include Decrypt, Error(AlgorithmNotSupported) if the runtime doesn’t support the algorithm, Error(InvalidAccess) if the algorithm doesn’t match the key, or Error(OperationFailed) if data isn’t valid ciphertext for the algorithm.

derive_bits

</> 
pub fn derive_bits(
  algorithm algorithm: DeriveAlgorithm,
  base_key key: key.CryptoKey,
  length length: Int,
) -> promise.Promise(Result(BitArray, crypto.CryptoError))

Derives bits of shared secret from a base key. Returns Error(KeyUsageMismatch(DeriveBits)) if base_key.usages doesn’t include DeriveBits, Error(InvalidAccess) if algorithm doesn’t match base_key, Error(AlgorithmNotSupported) if the runtime doesn’t support the algorithm, or Error(OperationFailed) if length isn’t a multiple of 8 or exceeds what the algorithm can derive. On Bun, length: 0 resolves with the full shared secret instead of an empty BitArray.

derive_key

</> 
pub fn derive_key(
  algorithm algorithm: DeriveAlgorithm,
  base_key key: key.CryptoKey,
  derived_key_type type_: SymmetricKeyParams,
  extractable extractable: Bool,
  usages usages: List(crypto.KeyUsage),
) -> promise.Promise(Result(key.CryptoKey, crypto.CryptoError))

Derives a new CryptoKey from a base key. Returns Error(KeyUsageMismatch(DeriveKey)) if base_key.usages doesn’t include DeriveKey, Error(InvalidAccess) if algorithm doesn’t match base_key, Error(AlgorithmNotSupported) if the runtime doesn’t support the algorithm, or Error(InvalidSyntax) if usages is empty for a derived-key type that requires it.

digest

</> 
pub fn digest(
  algorithm algorithm: crypto.HashAlgorithm,
  data data: BitArray,
) -> promise.Promise(BitArray)

Computes a cryptographic hash of data.

encrypt

</> 
pub fn encrypt(
  algorithm algorithm: EncryptAlgorithm,
  key key: key.CryptoKey,
  data data: BitArray,
) -> promise.Promise(Result(BitArray, crypto.CryptoError))

Encrypts data with key using algorithm. Returns Error(KeyUsageMismatch(Encrypt)) if key.usages doesn’t include Encrypt, Error(AlgorithmNotSupported) if the runtime doesn’t support the algorithm, Error(InvalidAccess) if the algorithm doesn’t match the key, or Error(OperationFailed) if the data is invalid for the algorithm.

export_key

</> 
pub fn export_key(
  format format: KeyFormat,
  key key: key.CryptoKey,
) -> promise.Promise(Result(BitArray, crypto.CryptoError))

Exports key in the given format. Returns Error(KeyNotExtractable) if key.extractable is False, or Error(AlgorithmNotSupported) if format isn’t supported for the key’s algorithm.

export_key_jwk

</> 
pub fn export_key_jwk(
  key: key.CryptoKey,
) -> promise.Promise(Result(jwk.JsonWebKey, crypto.CryptoError))

Exports key as a JSON Web Key. Returns Error(KeyNotExtractable) if key.extractable is False, or Error(AlgorithmNotSupported) if the key’s algorithm can’t be exported in JWK format. Equivalent to JavaScript’s SubtleCrypto.exportKey with format "jwk".

generate_key

</> 
pub fn generate_key(
  algorithm algorithm: SymmetricKeyParams,
  extractable extractable: Bool,
  usages usages: List(crypto.KeyUsage),
) -> promise.Promise(Result(key.CryptoKey, crypto.CryptoError))

Generates a new symmetric CryptoKey. Returns Error(AlgorithmNotSupported) if the runtime doesn’t support the algorithm, Error(InvalidSyntax) if usages is empty, or Error(OperationFailed) if the AES length isn’t 128, 192, or 256.

generate_key_pair

</> 
pub fn generate_key_pair(
  algorithm algorithm: KeyPairGenAlgorithm,
  extractable extractable: Bool,
  usages usages: List(crypto.KeyUsage),
) -> promise.Promise(Result(CryptoKeyPair, crypto.CryptoError))

Generates a new public/private key pair. Returns Error(AlgorithmNotSupported) if the runtime doesn’t support the algorithm, Error(InvalidSyntax) if usages is empty for an algorithm that requires it, or Error(OperationFailed) if the RSA parameters are unusable (e.g. an empty or invalid public_exponent). Equivalent to JavaScript’s SubtleCrypto.generateKey with an asymmetric-key algorithm.

import_key

</> 
pub fn import_key(
  format format: KeyFormat,
  key_data data: BitArray,
  algorithm algorithm: ImportAlgorithm,
  extractable extractable: Bool,
  usages usages: List(crypto.KeyUsage),
) -> promise.Promise(Result(key.CryptoKey, crypto.CryptoError))

Imports a raw key from data. Returns Error(AlgorithmNotSupported) if the runtime doesn’t support the algorithm, Error(DataMalformed) if data doesn’t match format, or Error(InvalidSyntax) if usages is empty for an algorithm that requires it.

import_key_jwk

</> 
pub fn import_key_jwk(
  key_data data: jwk.JsonWebKey,
  algorithm algorithm: ImportAlgorithm,
  extractable extractable: Bool,
  usages usages: List(crypto.KeyUsage),
) -> promise.Promise(Result(key.CryptoKey, crypto.CryptoError))

Imports a key from a JSON Web Key. Returns Error(AlgorithmNotSupported) if the runtime doesn’t support the algorithm, Error(DataMalformed) if data is malformed, or Error(InvalidSyntax) if usages is empty for an algorithm that requires it. Equivalent to JavaScript’s SubtleCrypto.importKey with format "jwk".

sign

</> 
pub fn sign(
  algorithm algorithm: SignAlgorithm,
  key key: key.CryptoKey,
  data data: BitArray,
) -> promise.Promise(Result(BitArray, crypto.CryptoError))

Produces a digital signature of data with key. Returns Error(KeyUsageMismatch(Sign)) if key.usages doesn’t include Sign, Error(AlgorithmNotSupported) if the runtime doesn’t support the algorithm, or Error(InvalidAccess) if the algorithm doesn’t match the key.

unwrap_key

</> 
pub fn unwrap_key(
  format format: KeyFormat,
  wrapped_key wrapped_key: BitArray,
  unwrapping_key unwrapping_key: key.CryptoKey,
  unwrap_algorithm algorithm: WrapAlgorithm,
  unwrapped_key_algorithm key_algorithm: ImportAlgorithm,
  extractable extractable: Bool,
  usages usages: List(crypto.KeyUsage),
) -> promise.Promise(Result(key.CryptoKey, crypto.CryptoError))

Decrypts wrapped_key with unwrapping_key and imports the result. Returns Error(KeyUsageMismatch(UnwrapKey)) if unwrapping_key.usages doesn’t include UnwrapKey, Error(AlgorithmNotSupported) if the runtime doesn’t support the unwrap or import algorithm, Error(OperationFailed) if the unwrapping fails, Error(DataMalformed) if the decrypted bytes aren’t a valid key, or Error(InvalidSyntax) if usages is empty for an unwrapped-key algorithm that requires it.

unwrap_key_jwk

</> 
pub fn unwrap_key_jwk(
  wrapped_key wrapped_key: BitArray,
  unwrapping_key unwrapping_key: key.CryptoKey,
  unwrap_algorithm algorithm: WrapAlgorithm,
  unwrapped_key_algorithm key_algorithm: ImportAlgorithm,
  extractable extractable: Bool,
  usages usages: List(crypto.KeyUsage),
) -> promise.Promise(Result(key.CryptoKey, crypto.CryptoError))

Like unwrap_key, but imports the decrypted key as a JSON Web Key. Equivalent to JavaScript’s SubtleCrypto.unwrapKey with format "jwk".

verify

</> 
pub fn verify(
  algorithm algorithm: SignAlgorithm,
  key key: key.CryptoKey,
  signature signature: BitArray,
  data data: BitArray,
) -> promise.Promise(Result(Bool, crypto.CryptoError))

Verifies signature against data using key. Returns Error(KeyUsageMismatch(Verify)) if key.usages doesn’t include Verify, Error(AlgorithmNotSupported) if the runtime doesn’t support the algorithm, or Error(InvalidAccess) if the algorithm doesn’t match the key. Ok(False) means the signature is well-formed but invalid for the data.

wrap_key

</> 
pub fn wrap_key(
  format format: KeyFormat,
  key key: key.CryptoKey,
  wrapping_key wrapping_key: key.CryptoKey,
  algorithm algorithm: WrapAlgorithm,
) -> promise.Promise(Result(BitArray, crypto.CryptoError))

Exports key in raw form and encrypts it with wrapping_key. Returns Error(KeyNotExtractable) if key.extractable is False, Error(KeyUsageMismatch(WrapKey)) if wrapping_key.usages doesn’t include WrapKey, Error(InvalidAccess) if algorithm doesn’t match wrapping_key, or Error(AlgorithmNotSupported) if the runtime doesn’t support the wrapping algorithm.

wrap_key_jwk

</> 
pub fn wrap_key_jwk(
  key key: key.CryptoKey,
  wrapping_key wrapping_key: key.CryptoKey,
  algorithm algorithm: WrapAlgorithm,
) -> promise.Promise(Result(BitArray, crypto.CryptoError))

Like wrap_key, but exports key as a JSON Web Key before wrapping. Equivalent to JavaScript’s SubtleCrypto.wrapKey with format "jwk".

✨ Search Document