Repository navigation
Description
Background
Stack Encrypt (packages/stack-encrypt) is the Rust engine that every CipherStash language SDK runs on. A target is the type a value is encrypted into. Stack Encrypt has two sets of traits that say how a target is encrypted and decrypted:
- The owned traits,
EncryptTargetandDecryptSource. They take the plaintext by value and wipe it from memory when they have used it. The plaintext type must implementZeroize, the trait that wipes a value. - The old traits,
EncryptFromandDecryptInto. stack-encrypt refactor: remove transitional traits and redundant execution APIs #1488 removes them.
The JSON targets hold an encrypted JSON document that can be searched:
| Stack Encrypt | eql-bindings (the EQL v4 type) |
What it holds |
|---|---|---|
JsonDocument |
JsonTreeDocument |
A whole document |
JsonExtracted |
JsonTreeExtracted |
One entry of a document, as the -> operator returns it |
JsonSubtree |
JsonTreeSubtree |
The rows of a read at a path |
EQL is the Encrypt Query Language: the SQL library installed in the customer's database, which stores and queries encrypted values. eql-bindings is the Rust crate with the types for those values.
Problem
The old traits on these targets use serde_json::Value as the plaintext. serde_json::Value does not implement Zeroize, so it cannot be the plaintext of an owned trait. JsonPlaintext (packages/stack-encrypt/src/json/plaintext.rs:165) wraps a Value and wipes it when it is dropped. It is the plaintext type the owned traits can use.
#1659 gives JsonTreeDocument the owned traits over JsonPlaintext. The other five targets have only the old traits:
JsonDocument:EncryptFrom<serde_json::Value>(src/target/operations.rs:1307) andDecryptInto<Value>(src/json/derive.rs:1367).JsonExtracted:DecryptInto<Value>(src/json/derive.rs:1406).JsonSubtree:DecryptInto<Vec<Value>>,DecryptInto<Option<Value>>andDecryptInto<Value>(src/json/derive.rs:1481,1498,1514).JsonTreeExtracted:DecryptInto<Value>(packages/eql/crates/eql-bindings/src/v4/json_tree.rs:633).JsonTreeSubtree:DecryptInto<Value>,DecryptInto<Option<Value>>andDecryptInto<Vec<Value>>(json_tree.rs:648,660,672).
This has three effects:
- The old traits cannot be removed. These targets would have no way to encrypt or decrypt. This blocks the rest of stack-encrypt refactor: remove transitional traits and redundant execution APIs #1488.
- A caller who uses the owned API cannot read one entry or one path of a document. They must call the old
decrypt_as. - A document or a part of one that is decrypted through the old traits comes back as a plain
Value. It is not wiped when it is dropped.
Nothing reports this today, because the old traits still compile and their tests pass.
Proposal
- In
stack-encrypt, add the owned traits overJsonPlaintext:JsonDocument:EncryptTarget<JsonPlaintext>andDecryptSource<JsonPlaintext>.JsonExtracted:DecryptSource<JsonPlaintext>.JsonSubtree:DecryptSource<JsonPlaintext>,DecryptSource<Option<JsonPlaintext>>andDecryptSource<Vec<JsonPlaintext>>.
- In
eql-bindings, add the sameDecryptSourceimplementations toJsonTreeExtractedandJsonTreeSubtree. - Check the layout for a document sealed under options other than the defaults (
Json::new(options)andJsonTree::new(options)). It is aLayout<Value>today. Give it aJsonPlaintextform if a caller of the owned API needs one. - Keep the old implementations. stack-encrypt:
EncryptFrom,DecryptInto,encrypt_asanddecrypt_asare still a second way to encrypt — remove them and their derives #1661 deletes them. - Test each new implementation against the old one: the same document, entry and path give the same answer and the same refusal. A document sealed through one trait opens through the other.
Acceptance
- Each of the five targets has the owned traits listed above.
- The stored bytes do not change. The frozen stored-bytes tests pass with no fixture change.
- Each README or rustdoc example added for these traits runs as a test.
- No test of a JSON target needs
encrypt_asordecrypt_asto reach behaviour the owned API lacks.
Evidence
Line numbers are from commit 775d37645, the head of #1659.
Relationship to other work
- Sub-issue of stack-encrypt refactor: remove transitional traits and redundant execution APIs #1488. It blocks stack-encrypt:
EncryptFrom,DecryptInto,encrypt_asanddecrypt_asare still a second way to encrypt — remove them and their derives #1661, the removal ofEncryptFromandDecryptInto. - stack-encrypt: a derived record cannot have an EQL type as a field, and
JsonTreeDocumenthas only the old traits #1658 and feat(eql-bindings): EQL types as fields of a Stack Encrypt record #1659 added the owned traits toJsonTreeDocument. This issue follows the same pattern. - eql-bindings: EQL v4 types implement only the old
EncryptFromandDecryptInto— addEncryptTargetandDecryptSource#1585 did the same for the other EQL v4 types. - stack-encrypt: element match and jsonpath match have no typed Rust API — only the binding layer, with no compile-time checks #1459 is about typed Rust queries on a JSON document. It does not cover these traits.
Activity
feat(stack-encrypt,eql-bindings): open every JSON target through the …