#![doc(html_favicon_url = "https://cipherstash.com/favicon.ico")]
// Security lints
#![deny(unsafe_code)]
#![warn(clippy::unwrap_used)]
#![warn(clippy::expect_used)]
#![warn(clippy::panic)]
// Prevent mem::forget from bypassing ZeroizeOnDrop
#![warn(clippy::mem_forget)]
// Prevent accidental data leaks via output
#![warn(clippy::print_stdout)]
#![warn(clippy::print_stderr)]
#![warn(clippy::dbg_macro)]
// Code quality
#![warn(unreachable_pub)]
#![warn(unused_results)]
#![warn(clippy::todo)]
#![warn(clippy::unimplemented)]
// Relax in tests
#![cfg_attr(test, allow(clippy::unwrap_used))]
#![cfg_attr(test, allow(clippy::expect_used))]
#![cfg_attr(test, allow(clippy::panic))]
#![cfg_attr(test, allow(unused_results))]
//! Encrypt Rust values under per-value ZeroKMS data keys.
//!
//! A [`StackCipher`] is scoped to one ZeroKMS client, and a [`KeysetCipher`] —
//! the cipher bound to one of that client's keysets, from
//! [`default_keyset`](StackCipher::default_keyset) or
//! [`keyset`](StackCipher::keyset) — encrypts any value that implements
//! [`Encrypt`] (`String`, `Vec`, `HashMap`, `Option`,
//! `Protected`, your own types, and any nesting of them). Either cipher
//! decrypts back into any [`Decrypt`] type. Every scalar inside the value is
//! sealed under its **own** ZeroKMS data key, so each value access is an
//! individually auditable key retrieval — there is no long-lived key in your
//! process.
//!
//! # Quick start
//!
// `StackCipher::new()` builds a ZeroKMS client from the environment, so it
// only exists with `http`. Without it the entry point is
// `StackCipher::builder().kms(..)` over an explicit data-key source — the
// shape the WASI/wazero guest builds against; see "Testing without ZeroKMS"
// below for the same call over the in-memory stub.
#![cfg_attr(
feature = "http",
doc = r#"```no_run
# async fn example() -> Result<(), Box> {
use stack_encrypt::StackCipher;
// Credentials: `npx stash auth login` on a developer machine, or
// CS_CLIENT_ID / CS_CLIENT_KEY + CS_CLIENT_ACCESS_KEY / CS_WORKSPACE_CRN in CI.
let cipher = StackCipher::new().await?;
let keyset = cipher.default_keyset();
// A `&str` encrypts as it is; decryption is owned, so it comes back a
// `String` — nothing borrows from a ciphertext.
let ciphertext = keyset.encrypt("secret message", ()).await?;
let plaintext: String = cipher.decrypt(ciphertext, ()).await?;
assert_eq!(plaintext, "secret message");
# Ok(())
# }
```"#
)]
#![cfg_attr(
not(feature = "http"),
doc = "Without the `http` feature a cipher is built over an explicit\
data-key source — `StackCipher::builder().kms(..).init()` — rather than from\
the environment. Enable `http` for `StackCipher::new()`, which discovers\
ZeroKMS credentials itself."
)]
//!
//! Encrypting binds to a keyset (every data key is minted under one); decrypting
//! does not (every sealed leaf carries the id of the keyset it was sealed
//! under), so it goes through the client-scoped `cipher` — or through the
//! `keyset`, which then refuses leaves from any other keyset.
//! [`default_keyset`](StackCipher::default_keyset) is the client's own —
//! the keyset a ZeroKMS administrator set for it — and is always that one.
//! A client may use many others, one per tenant say; [`StackCipher::keyset`]
//! selects any of them by id or name, loading it on first use. The [`keyset`](crate::keyset)
//! module docs lay out the model.
//!
//! The second argument is the *associated data* (AAD): anything that implements
//! [`IntoAad`] — `()`, `&[u8]`, `&str`, a tuple, or a derived [`Context`]. It is
//! authenticated, not encrypted, and must be supplied identically on decrypt.
//! Use it to bind a ciphertext to its context (a table name, a tenant, a record
//! id) so it cannot be replayed elsewhere:
//!
//! ```no_run
//! # async fn example(cipher: stack_encrypt::StackCipher) -> Result<(), stack_encrypt::Error> {
//! # let keyset = cipher.default_keyset();
//! let ct = keyset.encrypt("4111 1111 1111 1111", "users/42/card").await?;
//! let card: String = cipher.decrypt(ct, "users/42/card").await?; // ok
//! # Ok(())
//! # }
//! ```
//!
// Credentials only exist on the `http` path: without it there is no client
// to authenticate, only the `DataKeySource` the caller supplies.
# is for: build the
[`StackKms`](crate::kms::StackKms) over the strategy you want and hand it to
the builder.
```no_run
# async fn example() -> Result<(), Box> {
use stack_auth::{AuthError, AuthStrategyFn, SecretToken, ServiceToken};
use stack_encrypt::StackCipher;
use stack_encrypt::kms::{EnvKeyProvider, StackKmsBuilder};
// Any `AuthStrategy` goes in this slot — `AccessKeyStrategy`,
// `OidcFederationStrategy`, `DeviceSessionStrategy`, or, as here,
// `AuthStrategyFn` over a closure of your own. The closure is called
// whenever ZeroKMS needs a fresh token, so refresh belongs inside it. Note
// what holds the token: `SecretToken` is zeroized on drop and prints as
// `***`, so a long-lived credential neither lingers in freed memory nor
// lands in a log line.
let token = SecretToken::new(std::env::var("MY_SERVICE_TOKEN")?);
let strategy = AuthStrategyFn::new(move || {
let token = token.clone();
async move { Ok::<_, AuthError>(ServiceToken::new(token)) }
});
// The client key is the other half, and has its own provider: `EnvKeyProvider`
// reads CS_CLIENT_ID / CS_CLIENT_KEY, or supply a `KeyProvider` of your own.
let kms = StackKmsBuilder::new(strategy)
.with_key_provider(EnvKeyProvider)
.build()
.await?;
let cipher = StackCipher::builder().kms(kms).init().await?;
# Ok(())
# }
```
The built-in strategies are constructed from a workspace CRN
(`stack_auth::Crn`) rather than read from the environment —
`OidcFederationStrategy::new(crn, provider)` — and otherwise reach the
builder through the same `kms` seam.
`examples/zerokms_auth.rs` runs this end to end against a live ZeroKMS,
alongside the default path and the errors each half fails with. The
transport knobs — timeouts, batch size, concurrency, an alternate ZeroKMS
endpoint — are `StackKmsBuilder`'s, and the two keyset-cache knobs are
[`keyset_cache_size`](StackCipherBuilder::keyset_cache_size) and
[`keyset_name_ttl`](StackCipherBuilder::keyset_name_ttl).
"#
)]
//!
//! # Testing without ZeroKMS
//!
//! `stack_encrypt::kms::FakeDataKeySource` is an in-memory stub that needs no
//! credentials or network: it hands out a fresh random data key per request and
//! remembers it in memory, so a `generate` followed by the matching `retrieve`
//! round-trips within one process (the key material itself differs run to run,
//! and nothing survives the process). It models none of ZeroKMS's
//! authorization behaviour (context, identity claims, decryption policies) —
//! those are the service's, and tests of them belong against a real ZeroKMS.
//! It lives behind this crate's `test-support` feature, so add
//! `stack-encrypt = { version = "..", features = ["test-support"] }` to your
//! `[dev-dependencies]`. stack-kms is re-exported as [`kms`], so
//! there is no separate stack-kms dependency to keep in step:
//!
//! ```
//! use stack_encrypt::StackCipher;
//! use stack_encrypt::kms::FakeDataKeySource;
//!
//! # tokio::runtime::Builder::new_current_thread().enable_all().build().unwrap().block_on(async {
//! let cipher = StackCipher::builder()
//! .kms(FakeDataKeySource::new())
//! .init()
//! .await?;
//! let keyset = cipher.default_keyset();
//! let ct = keyset.encrypt(vec!["a".to_string(), "b".to_string()], ()).await?;
//! let pt: Vec = cipher.decrypt(ct, ()).await?;
//! assert_eq!(pt, vec!["a", "b"]);
//! # Ok::<(), stack_encrypt::Error>(())
//! # }).unwrap();
//! ```
//!
//! # Storing ciphertext
//!
//! [`encrypt`](KeysetCipher::encrypt) returns a [`StackCipherText`]: a tree whose
//! shape mirrors the value (a scalar is a single leaf, a `Vec` a sequence of
//! leaves, a map a set of named leaves) and whose leaves are [`SealedValue`]s.
//! A `SealedValue` is the persistable unit: its canonical, frozen byte
//! encoding is [`to_bytes`](SealedValue::to_bytes) /
//! [`from_bytes`](SealedValue::from_bytes) — the format a database column
//! holds and every language binding reads. Each leaf carries the id of the
//! keyset it was sealed under, which is what lets a column be opened with no
//! keyset named. For callers that manage their own
//! storage format it also implements `serde` `Serialize`/`Deserialize` and
//! offers [`into_parts`](SealedValue::into_parts) /
//! [`from_parts`](SealedValue::from_parts). Map keys are stored in the clear
//! (and authenticated); nothing else about a value is visible without its
//! data keys. Index terms have their own frozen encodings — see
//! [`sem`](crate::sem#byte-encodings).
//!
//! # What is authenticated
//!
//! Besides your AAD, the *shape* of a value is authenticated: an element cannot
//! be spliced out of a sequence and passed off as a scalar, a map value cannot
//! be moved under a different key, and "absent" / "empty" are themselves
//! sealed markers rather than inferable from structure. A tampered or
//! re-homed ciphertext fails with [`Error::Aead`]; a failed or denied key
//! retrieval surfaces as [`Error::Kms`]. A ciphertext opened under the
//! *wrong context* is refused by ZeroKMS first: every data key is bound to
//! its context's [`Descriptor`], so the retrieve is denied
//! ([`Error::Kms`], a forbidden request) before the AEAD runs — as
//! `examples/encrypted_record.rs` shows against a live ZeroKMS. Only a key
//! source that ignores descriptors (`FakeDataKeySource`, in tests) lets a
//! wrong context reach the AEAD, where it is [`Error::Aead`].
//!
//! For one-row reads of a batch-encrypted collection, decrypt as
//! [`Element`](Element) under the same AAD used for the whole collection:
//! the derivation that binds an element to its position is applied by the
//! type, not by the caller. That is the general rule here — every leaf's AAD
//! is derived from the context its key was minted under, and there is no
//! entry point that lets a caller supply one of its own.
//!
//! # Relationship to vitaminc
//!
//! A `KeysetCipher` is a vitaminc [`Cipher`]; everything a vitaminc cipher can
//! encrypt, it can encrypt, and the AEAD, AAD derivations and leaf wire format
//! are vitaminc's (`vitaminc_encrypt::Aes256Cipher`, AES-256-GCM under a random
//! per-leaf nonce vitaminc generates itself). The ZeroKMS `iv` a [`SealedValue`]
//! carries is *not* that nonce: it identifies the data key, and is sent back to
//! ZeroKMS with the key `tag` to re-derive it — under the same [`Descriptor`]
//! (the leaf's context, rendered) the key was generated with, which ZeroKMS
//! binds into the tag and logs. The types a caller needs from
//! vitaminc are re-exported here. The [`cipher`] module docs describe the
//! internals (batching, AAD derivation, wire format).
/// This crate's version, for a binding to put in the `user-agent` of the
/// ZeroKMS requests it makes.
///
/// A request is identified by the library that makes it, not by whichever
/// binding shim is carrying it: a product token of `stack-encrypt/0.1.0`
/// (the `product/version` spelling a `user-agent` is made of, with the
/// host in a comment after it — the Go guest sends
/// `stack-encrypt/0.1.0 (Go)`) means the same thing from the WASI guest
/// under Go as from a native cdylib under Python. The
/// native Rust client does not go through a binding and identifies itself
/// as `stack-kms` (see `stack_kms`'s user agent) — the crate that actually
/// makes its requests.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");
pub mod cipher;
#[cfg(test)]
mod codes;
pub mod descriptor;
#[cfg(feature = "dynamic")]
pub mod dynamic;
pub mod keyset;
pub mod plan;
pub mod sem;
pub mod target;
pub use cipher::{
BoxedPassthrough, Error, FromEnv, LeafBytesError, PendingStackCipherText, SealedValue,
StackCipher, StackCipherBuilder, StackCipherText, StackDecipher,
};
pub use descriptor::{Describe, Description, Descriptor, Label, LabelError};
pub use keyset::KeysetCipher;
pub use plan::{all, Plan, PlanError};
// stack-kms is a public dependency: `StackCipher` is generic over its
// `DataKeySource`, and `StackCipherBuilder::kms` takes its `StackKms`. It is
// versioned on its own (release-plz.toml), so a caller reaches it through
// here and always gets the version this crate was built against, never a
// second copy whose types do not fit `StackCipher`'s bounds.
pub use stack_kms as kms;
/// The trait every error here implements to hand over its structured
/// fields, with the rule for what an error may contain, and the helpers that
/// go with it. Shared by `stack-profile`, `stack-auth`, `stack-kms` and this
/// crate, so a binding encodes an error from any of them the same way.
pub use stack_kms::{diagnostic, ErrorPayload};
pub use target::{
CallerContext, CipherScope, DecryptField, DecryptFrom, DecryptInto, Decryptable, Decryption,
EncryptFrom, EncryptInto, Encrypted, Encryption, Equality, Index, IndexSpec, Indexes, Match,
Ope, Ore, Pending, PendingFuture, Request, Responses, TermSet,
};
// Re-export the vitaminc AEAD surface callers need to drive the cipher, so they
// don't have to depend on `vitaminc-aead` directly for the common path. A
// context type of your own implements `IntoContext` once; `IntoAad` and
// `IntoPrfContext` are vitaminc's blankets over it, so both derivations see
// the same bytes.
pub use vitaminc_aead::{
Cipher, CipherText, Context, ContextPiece, ContextTag, Decipher, Decrypt, Element, Encrypt,
IntoAad, IntoContext, Unspecified,
};
// The vitaminc 0.4 names, deprecated there; re-exported for one transition so
// a caller that spelled them keeps compiling with a warning.
#[allow(deprecated)]
pub use vitaminc_aead::{Aad, AadPiece};
// Likewise the PRF context surface, so a caller who needs the PRF view of a
// context has no direct `vitaminc-prf` dependency for it.
pub use vitaminc_prf::IntoPrfContext;
#[allow(deprecated)]
pub use vitaminc_prf::PrfContext;
// And the proof every target-directed leaf asks for: a `NonEmpty` is what
// `encrypt_into_with_context` / `decrypt_into` take, built with `nonempty!`
// (a literal, checked at compile time) or `NonEmpty::new` (a runtime value,
// checked once); `MaybeEmpty` is what a context type of your own implements
// to be wrapped. `#[derive(EncryptFrom)]` names these through this crate.
pub use vitaminc_protected::{nonempty, nonempty_bytes, EmptyError, MaybeEmpty, NonEmpty};