Skip to content

Commit c1a67f6

Browse files
authored
Merge pull request #1404 from cipherstash/feat/rust-scalar-ciphertext
feat(stack-encrypt): add owned scalar ciphertext API
2 parents b99f6f4 + 9e1227b commit c1a67f6

54 files changed

Lines changed: 1728 additions & 178 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.cargo/mutants.toml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,9 @@ exclude_re = [
8181
'stack-encrypt/src/sem/mod\.rs:\d+:\d+: replace <impl MatchConfig for DefaultMatch>::options -> MatchOptions with Default::default\(\)$',
8282
# Both unit-context conversions explicitly return Self::default().
8383
'stack-encrypt/src/target/context\.rs:\d+:\d+: replace <impl From<\(\)> for (DeclaredContext|ExpectedContext<T>)>::from -> Self with Default::default\(\)$',
84+
# A caller-free declaration adds nothing to the declared context: the
85+
# conversion returns Self::default().
86+
'stack-encrypt/src/target/input\.rs:\d+:\d+: replace <impl From<NoCallerContext> for super::DeclaredContext>::from -> Self with Default::default\(\)$',
8487
# The resolver of a build without EQL types holds none: its `targets` IS
8588
# the empty list (`dynamic::target::NoTargets`), which a test asserts on
8689
# and `resolve` turns into `TargetError::NoTargets`; `vec![]` is the body.
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
---
3+
4+
Stack Encrypt's Rust scalar API now consumes plaintext and returns an opaque
5+
`Ciphertext`, with separate methods for omitted and supplied context. Owned
6+
`EncryptInto` / `DecryptFrom` conversions use explicit context capabilities.
7+
The stored sealed-leaf format is unchanged.
8+
9+
Low-level structural encryption and decryption use `encrypt_tree` and
10+
`decrypt_tree`, returning and opening a tree of individually sealed leaves.
11+
12+
This is a Rust-only release, versioned by release-plz from the conventional
13+
commit. No npm package needs a version bump; EQL changes only adapt tests.

‎Cargo.lock‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/eql/tests/encryption/tests/text_eq.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ async fn text_round_trips_through_json_and_both_canonical_directions() {
5252
let opened: String = cipher.decrypt_as(stored, Default::default()).await.unwrap();
5353
assert_eq!(opened, value);
5454

55-
let native = keyset.encrypt(value.clone(), column()).await.unwrap();
55+
let native = keyset.encrypt_tree(value.clone(), column()).await.unwrap();
5656
let stored = TextEq {
5757
v: SchemaVersion::CURRENT,
5858
i: column().into_inner(),

‎packages/eql/tests/encryption/tests/v4_types.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ async fn sealed_from_frame(
8484
keyset: &stack_encrypt::KeysetCipher<'_, common::Observed>,
8585
value: ValueFrame,
8686
) -> Ciphertext {
87-
match keyset.encrypt(value, column()).await.unwrap() {
87+
match keyset.encrypt_tree(value, column()).await.unwrap() {
8888
CipherText::Single(leaf) => CiphertextVisitor.sealed(leaf).unwrap(),
8989
_ => panic!("a scalar seals as one leaf"),
9090
}

‎packages/stack-encrypt-derive/docs/attributes.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -72,17 +72,23 @@ building it needs a `T` that is both `IntoAad` and `IntoPrfContext`. A record
7272
made only of ciphertexts needs only the first, and the leaf it wraps
7373
(`StackCipherText`) asks for only that: its context is `AeadContext`. Such a
7474
record says so with `#[stash(context_type = AeadContext)]`, and then accepts
75-
every context the canonical `keyset.encrypt(value, context)` path accepts,
75+
every context the canonical `keyset.encrypt_tree(value, context)` path accepts,
7676
including a type that implements `IntoAad` alone:
7777

78-
```rust,ignore
78+
```rust,no_run
79+
use stack_encrypt::{DecryptInto, EncryptFrom, NonEmpty, StackCipherText};
80+
use stack_encrypt::target::{AeadContext, legacy::EncryptInto};
81+
7982
#[derive(EncryptFrom, DecryptInto)]
8083
#[stash(plaintext = String, context_type = AeadContext)]
8184
struct SealedName {
8285
c: StackCipherText,
8386
}
8487
88+
# async fn example<K: stack_encrypt::kms::DataKeySource + stack_encrypt::kms::IndexKeySource + Sync + 'static>(keyset: stack_encrypt::KeysetCipher<'_, K>, name: String, tenant: &str) -> Result<(), Box<dyn std::error::Error>> {
8589
let record: SealedName = name.encrypt_into_with_context(&keyset, NonEmpty::new(tenant)?).await?;
90+
# Ok(())
91+
# }
8692
```
8793

8894
The derive cannot pick this for you: it sees the field types' names, not
@@ -93,8 +99,8 @@ record with a `context_field`, or a `struct` derive, settles its context
9399
itself and refuses the attribute.
94100

95101
A declaration is executed by `keyset.encrypt_as(&value, context)` and
96-
`cipher.decrypt_as(record, context)`, or through the blanket `EncryptInto` and
97-
`DecryptFrom` traits for the source-side spelling (`value.encrypt_into(&keyset)`,
102+
`cipher.decrypt_as(record, context)`, or through the blanket
103+
`stack_encrypt::target::legacy::{EncryptInto, DecryptFrom}` traits for the source-side spelling (`value.encrypt_into(&keyset)`,
98104
`record.decrypt_into(&cipher, context)`). A hand-written target implements the
99105
same two declaration methods the derives emit, `EncryptFrom::encryption` and
100106
`DecryptInto::decryption`; neither receives the plaintext or a cipher.

‎packages/stack-encrypt/CHANGELOG.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
99

1010
### Breaking
1111

12+
- **`KeysetCipher::encrypt` and `decrypt` are the owned scalar API.**
13+
`keyset.encrypt(value)` consumes an `OpaqueEncode` value (`bool`, the fixed-width
14+
integers except `u8`, `f32`, `f64`, `String`), wipes it, and returns one
15+
opaque `Ciphertext`; `keyset.decrypt::<T>(ciphertext)` opens it to an `OpaqueDecode` type.
16+
`encrypt_with_context` and `decrypt_with_context` bind a context. The
17+
previous structural forms, which take any `Encrypt` value and a context and
18+
return a `StackCipherText`, are renamed `encrypt_tree` and `decrypt_tree`.
19+
`Ciphertext`'s bytes are the unchanged `SealedValue` v1 envelope, so
20+
stored values open through either API.
21+
Nullable `Option<T>` values remain on `encrypt_tree` / `decrypt_tree` in this
22+
slice, including Vitamin C's padded-null encoding for fixed-width types.
23+
- **The root `EncryptInto` and `DecryptFrom` are new owned conversion
24+
traits** over `EncryptTarget` / `DecryptSource`. The borrowed traits they
25+
replace, and that `#[derive(EncryptFrom, DecryptInto)]` types use, are
26+
`stack_encrypt::target::legacy::{EncryptInto, DecryptFrom}`; import one
27+
pair or the other, not both.
1228
- **`OpSpec`, `Operand` and the query term's wire form grow for documents**
1329
(#1350). `OpSpec` gains twelve operators and `Operand` gains `Text` and
1430
`TextList`; a binding that matches on either adds the arms. The query

‎packages/stack-encrypt/Cargo.toml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,9 @@ trybuild = "1"
143143
# stack-guest-abi takes it: `std` carries the failure persistence and the
144144
# ChaCha RNG the runs are seeded with, and nothing else is needed.
145145
proptest = { version = "1.12", default-features = false, features = ["std"] }
146+
# A binary Serde format for `Ciphertext`'s bytes form (tests/scalar.rs).
147+
# Already in the graph through vitaminc-traits.
148+
rmp-serde = "1.3"
146149

147150
# The derive diagnostics are recorded with every feature on, as `test:unit`
148151
# and CI run them. They cannot be relied on to hold under both feature sets
@@ -171,3 +174,7 @@ required-features = ["http"]
171174

172175
[package.metadata.docs.rs]
173176
all-features = true
177+
178+
[[example]]
179+
name = "scalar"
180+
required-features = ["http"]

‎packages/stack-encrypt/docs/adr/0003-declarative-targets-and-ciphertext-transcoding.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,18 @@ not close it. A concrete associated context type does not implicitly accept
6161
arbitrary context extensions; any extension facility must preserve the declared
6262
base context and be specified explicitly.
6363

64+
Amended 2026-10-31, clarified 2026-11-01: the opaque scalar operation producing
65+
`Ciphertext` accepts empty context, because it is the cipher-directed
66+
contract in owned form: `keyset.encrypt(value)` seals what
67+
`keyset.encrypt_tree(value, ())` seals. It reaches the shared core through a
68+
separate entry. Context policy belongs to the encryption operation, not the
69+
Rust type wrapping its output: `scalar_ciphertext().map(Wrapper)` retains the
70+
scalar policy and the same authenticated bytes. Mapping already-encrypted output
71+
does not derive a term or change its AAD. EQL ciphertext and term operations
72+
still require `NonEmpty`; wrapping a scalar does not bypass their constructors.
73+
Custom scalar wrappers can require caller context with `RequiredContext`, or
74+
declare a nonempty context with `under`.
75+
6476
Transcoding consumes native encryption output through a custom encrypted-data
6577
protocol. It distinguishes sealed leaves, sequences, maps, authenticated absence
6678
and empty-container markers, passthrough metadata, and typed terms. Readers expose

‎packages/stack-encrypt/examples/encrypted_record.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
//! `zerokms_auth` example for the lookup order).
2828
2929
use stack_encrypt::sem::{EqualityTerm, OreTerm};
30-
use stack_encrypt::target::{DecryptFrom, EncryptInto};
30+
use stack_encrypt::target::legacy::{DecryptFrom, EncryptInto};
3131
use stack_encrypt::{nonempty, DecryptInto, EncryptFrom, Error, StackCipher, StackCipherText};
3232

3333
// --- The shapes ----------------------------------------------------------------

0 commit comments

Comments
 (0)