Skip to content

stack-encrypt: EncryptFrom, DecryptInto, encrypt_as and decrypt_as are still a second way to encrypt — remove them and their derives #1661

Open

Description

@coderdan

Background

Stack Encrypt (packages/stack-encrypt) is the Rust engine that every CipherStash language SDK runs on. It has two APIs for encrypting and decrypting a value:

  • The owned API. The traits EncryptTarget and DecryptSource, and entry points such as keyset.encrypt(..) and value.encrypt_into(&keyset). It takes the plaintext by value and wipes it from memory after use.
  • The old API. The traits EncryptFrom and DecryptInto, their derives, and the entry points encrypt_as and decrypt_as.

The Stack Encrypt API plan keeps the owned API and removes the old one. #1488 tracks that work.

Problem

The old API is still public, and most of the code still uses it. A developer who reads the crate finds two ways to encrypt a record and cannot tell which to use.

What is still there, at commit 775d37645 (the head of #1659):

  • The traits. EncryptFrom (src/target/operations.rs:40) and DecryptInto (operations.rs:73).
  • The entry points. encrypt_as (operations.rs:1482) and decrypt_as (operations.rs:1575 and 1598).
  • The derives. #[derive(EncryptFrom)] and #[derive(DecryptInto)] (packages/stack-encrypt-derive/src/lib.rs:331 and 343).
  • The owned derives emit the old traits too. #[derive(EncryptTarget)] also emits EncryptFrom (owned_encrypt.rs:634). #[derive(DecryptSource)] also emits DecryptInto and opens each field through DecryptField, which is built on DecryptInto (owned_decrypt.rs:114 to 122, 285, 323).
  • Implementations in stack-encrypt. StackCipherText, the term types, Vec, Option, tuples, Encrypted<Terms> and the JSON targets (operations.rs:1307, 1616 to 1848, tuples.rs:83 and 116, index.rs:649 and 661, json/derive.rs:1367 to 1514).
  • Implementations in eql-bindings, the Rust crate with the types for values stored by EQL (Encrypt Query Language, the SQL library in the customer's database): encryption.rs:260, 293, 342, 470, 530, and v4/json_tree.rs:522 to 672.
  • Tests. 304 calls to encrypt_as or decrypt_as in packages/stack-encrypt/tests, and 188 in packages/eql/tests. 105 derive attributes in packages/stack-encrypt/tests name an old derive.

Most of these test calls were moved to encrypt_as and decrypt_as by #1613, which removed target::legacy. They have to move once more.

Proposal

  1. Move the tests to the owned API. A test that checks behaviour both APIs share calls the owned entry point. A test that only checks the old derive is deleted, once an owned test covers the same behaviour. List each deleted test and the test that replaces it in the pull request.
  2. Change #[derive(DecryptSource)] to open a field through DecryptSource, not through DecryptField and DecryptInto. Stop both owned derives from emitting the old traits.
  3. Move eql-bindings to the owned traits only. Delete its EncryptFrom and DecryptInto implementations.
  4. Delete EncryptFrom, DecryptInto, DecryptField, encrypt_as, decrypt_as and the two old derives.
  5. Keep encrypt_tree and decrypt_tree. They are explicit structural operations and are not part of the old API.
  6. Keep an entry point for a borrowed value that stands alone, as the plan says.
  7. Add a "Breaking" entry to the CHANGELOG that says how to upgrade.

Do the work in more than one pull request if it is easier to review: tests first, then the deletion.

Acceptance

  • No file in packages/stack-encrypt, packages/stack-encrypt-derive, packages/eql or languages/golang names EncryptFrom, DecryptInto, encrypt_as or decrypt_as, except the CHANGELOG and the decision records.
  • 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.
  • The mutation test job passes on the changed lines.

Relationship to other work

Activity

  1. coderdan commented on Nov 15, 2026

    @coderdan
    ContributorAuthor

    A correction to the proposal above, found while doing the work in #1666.

    Step 4 says to delete DecryptField. It stays. A derived record uses DecryptField (with Decryptable) to find which of a field's outputs can be opened: a term cannot, a ciphertext can. Nothing else in the owned API answers that. What changes is what it is built on: it now opens through DecryptSource, and no longer through DecryptInto.

    Everything else in the proposal is done in #1666, in one pull request with #1662, because neither compiles without the other.

  2. self-assigned this
    on Nov 15, 2026
  3. added 3 commits that reference this issue on Nov 15, 2026
    5721065
    769102d
    ca46547
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

SDKrustPull requests that update Rust code

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions