@@ -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
137150impl < ' 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