Crate polymorph_webcrypto_guest

Expand description

Guest-side bindings and ergonomic helpers for the polymorph:webcrypto interfaces.

This crate is the intended way for Rust guest components to consume polymorph:webcrypto: it binds the whole import surface once (the bindings module) and wraps the key resources in newtypes whose operations take a DataSource — a byte slice, an owned buffer, or a component-model stream — so callers need none of the stream plumbing the interfaces are defined in terms of.

Most consumers need no polymorph:webcrypto WIT at all: link this crate and call it, and the componentized binary imports exactly the interfaces it uses (unused imports are stripped). Only list the imports in your own world — remapping them onto this crate’s bindings modules with wit-bindgen’s with: option — if your own interfaces name these types or external tooling validates your world’s shape. Do not bind the same interfaces with a second generate! without that remapping: the two expansions would produce distinct, unconvertible resource types, and the newtypes here wrap only this crate’s generation.

§Cargo features

bytes: DataSource::from_buf feeds an operation from any bytes::Buf, chunk by chunk.
futures-io: DataSource::from_reader feeds an operation from any futures_io::AsyncRead; read failures surface as Error::Read.

§Contract notes carried over from the WIT

The wrappers hide streams, not the closure rule. An operation’s input stream ends no later than the operation completes, and only a failing operation may end it early; these helpers feed the source and await the result concurrently, reporting the operation’s error over the feed’s fate, so that contract is invisible here. Callers with needs beyond DataSource use the bindings resources directly with wit-bindgen’s own stream primitives (wit_stream::new, StreamWriter::write_all, [StreamReader::collect]).
Writer drop ends the message. A stream’s producer failing midway is indistinguishable from it finishing (the ABI carries no verdict at end-of-stream). Buffer-backed DataSources own their whole input, so this only concerns stream-backed sources; see DataSource’s truncating-producer warning.
Implementations may bound input sizes. Hosts enforce buffering limits as recoverable Error::Other values (see the WIT types.error docs); nothing here retries or special-cases them.
Nonces are the caller’s problem on aead. Aead::seal leaves nonce uniqueness per key entirely to you, and nonce reuse under one key defeats the algorithm’s guarantees.

Re-exports§

pub use wit_bindgen;

Modules§

aes_cbc: aes-cbc key creation (the unauthenticated AES-CBC mode; prefer aes_gcm — see CipherKey’s warning).
aes_ctr: aes-ctr key creation (the unauthenticated AES-CTR mode; prefer aes_gcm — see CipherKey’s warning).
aes_gcm: aes-gcm key creation (caller-nonce — see Aead’s nonce warning).
aes_kw: aes-kw key creation (RFC 3394 / NIST SP 800-38F KW): dedicated key-wrapping keys for the key-wrap kind.
bindings: The generated bindings for the full polymorph:webcrypto import surface.
ecdh: ecdh key creation (SP 800-56A ECDH over the NIST prime-order curves).
ecdsa: ecdsa-verify / ecdsa-sign key creation.
ed25519: ed25519-verify / ed25519-sign key creation.
extension: The known extension-error conditions, as (origin, name) constants for matching against Error::Extension.
hkdf: hkdf base-secret import (RFC 5869).
hkdf_sha1: hkdf-sha1 derivation parameterization: HKDF over SHA-1, for compatibility with existing protocols that fix it. The construction is not affected by SHA-1’s collision attacks (HKDF relies on HMAC’s PRF property), but prefer hkdf_sha2 where the protocol is yours to choose.
hkdf_sha2: hkdf-sha2 derivation parameterization (RFC 5869 over the SHA-2 family).
hmac_sha1: hmac-sha1 key creation: HMAC over SHA-1, for interoperability with SHA-1-committed constructions (TOTP, WPA2). HMAC’s security rests on the PRF property, which SHA-1’s collision breaks do not reach; prefer hmac_sha2 in new designs.
hmac_sha2: hmac-sha2 key creation.
pbkdf2: pbkdf2 base-secret import (RFC 8018).
pbkdf2_sha1: pbkdf2-sha1 derivation parameterization: PBKDF2 over HMAC-SHA-1, for compatibility with existing password databases that fix it. The construction is not affected by SHA-1’s collision attacks (PBKDF2 relies on HMAC’s PRF property), but prefer pbkdf2_sha2 where the parameters are yours to choose.
pbkdf2_sha2: pbkdf2-sha2 derivation parameterization (RFC 8018 over HMAC-SHA-2).
rsa_oaep: rsa-oaep-encrypt key creation (RFC 8017 §7.1) — the public half of key transport — plus, behind the rsa-oaep-decrypt cargo feature, rsa-oaep-decrypt.
rsa_pss: rsa-pss-verify key creation (RFC 8017 §8.1), plus — behind the rsa-sign cargo feature — rsa-pss-sign.
rsassa_pkcs1_v15: rsassa-pkcs1-v15-verify key creation (RFC 8017 §8.2), plus — behind the rsa-sign cargo feature — rsassa-pkcs1-v15-sign.
sha2: sha2 digest creation.
wit_stream
x25519: x25519 key creation (RFC 7748 §5, the X25519 function).

Structs§

Aead: An aead.aead-key: caller-nonce authenticated encryption with associated data.
AeadKeyOptions: Mint-time policy for an Aead key. See MacKeyOptions for the options contract.
AgreementKeyOptions: Mint-time policy for an AgreementSecretKey. See MacKeyOptions for the options contract; the derive grants are copied onto every DeriveInput the key agrees (WebCrypto’s model: derive usages live on the secret key).
AgreementPublicKey: A key-agreement.public-key: the exchangeable half of an agreement keypair, minted by x25519’s imports and generate_key. Secret-free.
AgreementSecretKey: A key-agreement.secret-key: the private half of an agreement keypair. agree is one-shot on the immutable key; the derivation state lives in the DeriveInput it returns.
CipherKey: An unauthenticated-cipher key (AES-CBC or AES-CTR), minted by aes_cbc / aes_ctr. Nothing this key does authenticates: ciphertext is malleable and a successful decrypt is not evidence the input is untampered. Default to Aead; use this kind only where an existing format fixes the mode. See the WIT cipher interface for the full contract.
CipherKeyOptions: Mint-time policy for a CipherKey key. See MacKeyOptions for the options contract.
DataSource: The input to a wrapped operation: anything this crate knows how to feed into a WIT stream<u8>.
DecryptionKey: A public-encryption.decryption-key: the private half of asymmetric encryption. decrypt and unwrap are one-shot calls on the immutable key, over whole byte buffers (see EncryptionKey for why nothing streams here).
DecryptionKeyOptions: Mint-time policy for a DecryptionKey. See MacKeyOptions for the options contract. The two grants separate disclosure from minting: decrypt returns plaintext to the caller, while unwrap mints keys whose material the caller never sees, so a key granted only unwrap cannot leak what it transports.
DeriveInput: A derivation.derive-input: a fully parameterized derivation — base secret plus every parameter, minted by the prepare functions (hkdf_sha2::prepare, pbkdf2_sha2::prepare, …) and by AgreementSecretKey::agree.
DeriveOptions: Mint-time policy for a derivation base secret (Ikm or Password). See MacKeyOptions for the options contract. The grants are copied onto every DeriveInput built on the secret; parameterization neither grants nor revokes.
Digest: A digest.digest: a reusable, algorithm-bound hash.
EncryptionKey: A public-encryption.encryption-key: the public half of asymmetric encryption — encryption and wrapping, secret-free to hold.
Ikm: An hkdf.ikm: imported input keying material for HKDF, minted by hkdf::import_ikm. Never readable back through the API under any grant; the grants recorded at import are copied onto every DeriveInput built on it (via hkdf_sha2::prepare and friends).
KwKey: A key-wrap.kw-key: a dedicated key-wrapping key (AES-KW), bound to its algorithm at creation.
KwKeyOptions: Mint-time policy for a KwKey. See MacKeyOptions for the options contract.
Mac: A mac.mac-key: a message-authentication-code key, bound to one algorithm at creation.
MacKeyOptions: Mint-time policy for a Mac key: the plain-data counterpart of the WIT mac.mac-key-options resource, which the minting functions construct from it per call.
Password: A pbkdf2.password: an imported password, minted by pbkdf2::import_password. Never readable back through the API under any grant; the grants recorded at import are copied onto every DeriveInput built on it (via pbkdf2_sha2::prepare and friends).
Seal: A pending seal, returned by Aead::seal and CipherKey::encrypt.
SigningKey: A signature.signing-key: private-key signing.
SigningKeyOptions: Mint-time policy for a SigningKey. See MacKeyOptions for the options contract; sign is the sole usage, so it must be enabled for a mint to succeed.
UnwrapInput: A wrapping.unwrap-input: decrypted key material awaiting a typed unwrap mint. Single-use, like WrapInput.
VerifyingKey: A signature.verifying-key: public-key signature verification. Secret-free — a component holding only this key provably cannot sign.
WrapInput: A wrapping.wrap-input: one key’s serialized material awaiting encryption under a wrapping key. Single-use — the consuming wrap operation takes it by value, on failure as on success.

Enums§

Error: Errors surfaced by key creation and cryptographic operations.

Type Aliases§

StreamReader: The component-model byte-stream reader, as returned by Aead::seal and friends and accepted by DataSource. Represents the readable end of a Component Model stream.