Skip to content

Commit 32519a5

Browse files
committed
docs(stack-encrypt): rewrite the CipherRef docs in plain language
The CipherRef docs now have a section for each question a caller has: how to pass one, what each kind of reference can do, and how long one is valid. The docs say that a reference limits an operation to a keyset, where they said confined.
1 parent 1b0952a commit 32519a5

3 files changed

Lines changed: 49 additions & 31 deletions

File tree

‎languages/golang/encrypt/guest/src/options.rs‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -239,10 +239,13 @@ impl KeysetSelector {
239239
}
240240
}
241241

242-
/// The [`CipherRef`] a decrypt-side selector names: the client for
243-
/// `{"any"}`, which opens a leaf sealed under any of its keysets, or one
244-
/// keyset's cipher, which opens only its own and refuses the rest before
245-
/// any key is retrieved.
242+
/// Returns the [`CipherRef`] for the keyset selector of a decrypt call.
243+
///
244+
/// - For `{"any"}`, the result is the client. The client opens a leaf
245+
/// sealed under any of its keysets.
246+
/// - For one keyset, the result is that keyset's cipher. That cipher only
247+
/// opens leaves from its own keyset. The cipher refuses any other leaf
248+
/// before it retrieves any key.
246249
pub async fn scope_for<'c, K>(
247250
cipher: &'c StackCipher<K>,
248251
selector: &KeysetSelector,

‎packages/stack-encrypt/src/dynamic/mod.rs‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,9 @@
5252
//! (ADR-0009; ADR-0007, amended 2026-10-16), and [`field_operators`], the
5353
//! operators a plan field answers, for a generator to ask before the
5454
//! program runs.
55-
//! * [`CipherRef`](crate::CipherRef) — which cipher an opening operation
56-
//! decrypts through: `&cipher`, or `&keyset` for one keyset alone.
55+
//! * [`CipherRef`](crate::CipherRef) — the cipher that a decrypt
56+
//! operation runs through. Pass `&cipher`, or pass `&keyset` to limit
57+
//! the operation to one keyset.
5758
//!
5859
//! # What is not here
5960
//!

‎packages/stack-encrypt/src/target/pending.rs‎

Lines changed: 39 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -87,32 +87,45 @@ pub struct Pending<'a, T, K> {
8787
fulfil: FulfilBox<'a, T>,
8888
}
8989

90-
/// What a [`Pending`] is built through: a borrowed connection, and the
91-
/// keyset it is confined to, if any.
90+
/// The cipher that a [`Pending`] operation runs through: a borrowed
91+
/// client, and the ID of one keyset if the operation is limited to it.
9292
///
93-
/// Build one from a reference to a [`StackCipher`], or from a
94-
/// [`KeysetCipher`], borrowed or owned. The entry points that can run
95-
/// through either cipher take `impl Into<CipherRef>`. These are the decrypt
96-
/// entry points, such as [`DecryptFrom::decrypt_from`](super::DecryptFrom::decrypt_from)
97-
/// and `dynamic::record::decrypt`, and the [`Pending`] constructors. So a
98-
/// caller passes `&cipher` or `&keyset` and does not name this type. An
99-
/// entry point that encrypts needs a keyset to generate keys under, so it
100-
/// takes a [`KeysetCipher`] and not a `CipherRef`.
93+
/// # How to pass one
10194
///
102-
/// A `CipherRef` built from a [`KeysetCipher`] keeps the keyset's ID and
103-
/// the connection, not the handle. So it lives as long as the connection,
104-
/// even when the handle is a temporary value.
95+
/// You do not need to name this type. Each entry point that can run
96+
/// through either cipher accepts `impl Into<CipherRef>`, so pass `&cipher`
97+
/// or `&keyset`. These entry points are:
10598
///
106-
/// - A reference to a [`StackCipher`] is confined to no keyset. It opens a
107-
/// leaf sealed under any keyset the client can use. It cannot generate a
108-
/// key ([`Error::NoKeyset`]).
109-
/// - A reference to a [`KeysetCipher`] is confined to that keyset. It
110-
/// refuses a leaf from another keyset before any key is retrieved
111-
/// ([`Error::ForeignKeyset`]).
99+
/// - the decrypt entry points, such as
100+
/// [`DecryptFrom::decrypt_from`](super::DecryptFrom::decrypt_from) and
101+
/// `dynamic::record::decrypt`
102+
/// - the [`Pending`] constructors
112103
///
113-
/// There is no other way to build one. So the keyset a `CipherRef` names
114-
/// is one the cipher loaded from ZeroKMS, and the two refusals above hold
115-
/// for every pending.
104+
/// An entry point that encrypts needs a keyset to generate keys under.
105+
/// That entry point accepts a [`KeysetCipher`], and not a `CipherRef`.
106+
///
107+
/// # What each reference can do
108+
///
109+
/// A `CipherRef` comes from a reference to a [`StackCipher`], or from a
110+
/// [`KeysetCipher`], borrowed or owned:
111+
///
112+
/// - A reference to a [`StackCipher`] is limited to no keyset. The
113+
/// operation opens a leaf sealed under any keyset the client can use.
114+
/// The operation cannot generate a key ([`Error::NoKeyset`]).
115+
/// - A [`KeysetCipher`] limits the operation to that keyset. The
116+
/// operation refuses a leaf from another keyset before it retrieves any
117+
/// key ([`Error::ForeignKeyset`]).
118+
///
119+
/// No other conversion makes a `CipherRef`. The keyset in a `CipherRef`
120+
/// is therefore one that the cipher loaded from ZeroKMS, and both rules
121+
/// above apply to every [`Pending`].
122+
///
123+
/// # Lifetime
124+
///
125+
/// A `CipherRef` made from a [`KeysetCipher`] keeps the keyset's ID and
126+
/// the borrowed client, and does not keep the `KeysetCipher`. The
127+
/// `CipherRef` is valid for as long as the client is, even when the
128+
/// `KeysetCipher` is a temporary value.
116129
///
117130
/// ```
118131
/// use stack_encrypt::kms::FakeDataKeySource;
@@ -135,13 +148,14 @@ pub struct CipherRef<'c, K> {
135148
}
136149

137150
impl<'c, K> CipherRef<'c, K> {
138-
/// The connection the pending settles through.
151+
/// The client that the pending operation runs through.
139152
pub(crate) fn cipher(&self) -> &'c StackCipher<K> {
140153
self.cipher
141154
}
142155

143-
/// The ID of the keyset this reference is confined to. `None` for a
144-
/// reference to a [`StackCipher`], which is confined to no keyset.
156+
/// Returns the ID of the keyset that this reference is limited to.
157+
/// Returns `None` for a reference to a [`StackCipher`]. That
158+
/// reference is limited to no keyset.
145159
pub fn keyset_id(&self) -> Option<Uuid> {
146160
self.keyset
147161
}

0 commit comments

Comments
 (0)