Repository navigation
Open
Labels
Milestone
Description
Background
Stack Encrypt (packages/stack-encrypt) is the Rust engine that every CipherStash language SDK runs on. A plan says how each field of a record is encrypted. Stack Encrypt has two ways to write a plan and run it:
Planned. A value under a plan that is data:Planned::new(&plan, value). It is a target, so it runs through the same entry points as every other value:encrypt,encrypt_with_context,decryptanddecrypt_with_context. refactor(stack-encrypt): lower a data plan to the combinators in dynamic::planned #1597 added it.- The chain and the builder. A plan built in Rust code with
Plan::context(..).fields(..), and run with a chain of calls:cipher.encrypt(..).using(&plan), with.context(..),.extend(..)and.keyset(..)steps.
The Stack Encrypt API plan keeps Planned and removes the chain and the builder. #1488 tracks that work.
Problem
The chain and the builder are still public. They are about 5,300 lines in packages/stack-encrypt/src/plan/. Three things follow.
- Two ways to do one job. A developer cannot tell which to use. The chain also let a context part added late replace an earlier one (stack-encrypt: a second
.extend()replaces the first, so Rust builds a different context than Go and a query silently misses #1120, fixed), which made Rust build a different context from Go, so a query found nothing. - The dynamic entry points do not use
Planned.dynamic::record::encrypt_with(src/dynamic/record.rs:1798) anddecrypt_with(record.rs:2097) run the lowering themselves.Plannedshould be the one place a data plan is run. - Tests still depend on the chain. 16 test files in
packages/stack-encrypt/tests, 13 compile-fail and compile-pass cases intests/ui, and 4 files inpackages/eql/testsuse the chain or the builder.
What is still there, at commit 775d37645 (the head of #1659):
src/plan/chain.rs(1,270 lines), with threeusingmethods (chain.rs:349,373,1019).src/plan/build.rs(1,840 lines), withIntoLabel(build.rs:27) and the builder's output methodbuild()(build.rs:1118).src/plan/value.rs(922 lines) andsrc/plan/field_ref.rs(139 lines), withpickandFieldRef.#[derive(EncryptFrom)]emits the builder's types (packages/stack-encrypt-derive/src/encrypt.rs:88and176).
Proposal
- Make
dynamic::record::encrypt_withanddecrypt_withbuild aPlannedand run it. The lowering indynamic::plannedstays the only one. - Move
Plan::encryptionintoPlanned, as the amended decision record ADR-0007 says. - Move each test that uses the chain to
Plannedor to the typed API (field markers and the owned record derives).Plannedmust run every case the chain ran. List each test that is deleted, and the test that covers the same behaviour, in the pull request. - Delete
plan/chain.rs,plan/build.rs,plan/value.rsandplan/field_ref.rs, withpick,FieldRef,Runs,Opensand theusingmethods. - The parent issue asks to rename the builder's output method from
build()totarget. Everybuild()in the crate is in the files this issue deletes, so there is nothing left to rename. Say so when this closes. - Keep
plan/error.rsandplan/values.rsif the dynamic path still uses them (dynamic/record.rs:163importsplan::FieldValues). Move them out ofplan/if nothing else is left there. - Add a "Breaking" entry to the CHANGELOG that says how to upgrade.
Acceptance
-
plan/chain.rs,plan/build.rs,plan/value.rsandplan/field_ref.rsare gone. - No public method is named
using. - Every behaviour a chain test checked has a test that runs through
Plannedor the typed API. - The compile-fail cases in
tests/uistill cover a binding in a query and a scope after a bind. - The stored bytes do not change. The frozen stored-bytes tests pass with no fixture change.
- The Go module's tests and the cross-language conformance checks pass.
Relationship to other work
- Sub-issue of stack-encrypt refactor: remove transitional traits and redundant execution APIs #1488.
- The chain is bounded on the old trait
EncryptFrom(src/plan/chain.rs:532,src/plan/build.rs:946), and#[derive(EncryptFrom)]emits the builder's types. So this issue and stack-encrypt:EncryptFrom,DecryptInto,encrypt_asanddecrypt_asare still a second way to encrypt — remove them and their derives #1661, which removesEncryptFromandDecryptInto, depend on each other. Move the tests off both first. Then delete the chain, the builder and the old derives in one pull request, or the derive and the chain first and the traits second. - stack-encrypt: bindings send a serialised
Planned, and the conformance corpus is written as one #1594 makes the language SDKs send a serialisedPlanned. It does not remove the chain. - stack-encrypt: a field marker has no operator method for a field of several indexes, a nullable field, or a record field #1596, stack-encrypt: a record field with its own scope, or an
Optionof a record, has no typed query once the chain goes #1600 and feat(stack-encrypt): typed queries for a nullable record field and an inner record with its own scope #1608 added the typed queries that the chain was the only way to write. They are closed.
Activity
fix(stack-encrypt,eql-bindings): address the review of the removal
docs(stack-encrypt): drop two more mentions of the plan builder and t…
refactor(stack-encrypt,eql-bindings)!: remove the plan chain, the bui…
fix(stack-encrypt,eql-bindings): address the review of the removal
docs(stack-encrypt): drop two more mentions of the plan builder and t…