End to end encryption#98
Merged
elizabetheonoja-art merged 2 commits intoJul 18, 2026
Merged
Conversation
Add E2EE encrypted-envelope support for sensitive payloads (Issue Utility-Protocol#91)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
Prevent plaintext sensitive fields (usage, location, diagnostics, customer metadata) from ever appearing in contract args or storage by enforcing an on-chain encrypted-envelope boundary.
Provide an auditable, replay-resistant envelope (commitment + metadata) so indexers and runbooks can correlate ciphertext without exposing plaintext.
Support safe key rotation and lightweight on-chain validation while keeping decryption and key material off-chain.
Description
Added envelope types EncryptedSensitivePayload and SensitivePayloadAccepted and a documenting design doc at docs/e2ee-sensitive-payloads.md describing architecture and rollout guidance.
Added storage keys DataKey::MeterEncryptionKey(u64) and DataKey::SensitivePayload(u64, BytesN<32>) and new ContractError variants EncryptionKeyNotConfigured, InvalidEncryptedPayload, EncryptedPayloadTooLarge, and CommitmentMismatch.
Implemented commitment calculation and envelope validation with constants MAX_ENCRYPTED_PAYLOAD_SIZE and field masks (SENSITIVE_FIELD_*) and a function calculate_sensitive_payload_commitment that uses env.crypto().sha256(&material.to_xdr(env)) to produce a deterministic BytesN<32> commitment; validation is in validate_sensitive_payload_envelope.
Added contract methods set_meter_encryption_key, submit_sensitive_payload, and get_sensitive_payload to register key ids, accept validated ciphertext envelopes, emit E2EEKey/E2EEData events, and retrieve stored envelopes by (meter_id, commitment).
Added unit tests in e2ee_sensitive_payload_tests covering valid envelopes, tampered commitments, and unknown/invalid field masks.
Testing
Ran cargo fmt --all to format changes (succeeded).
Ran cargo test --manifest-path contracts/utility_contracts/Cargo.toml e2ee_sensitive_payload_tests --lib; this test run failed to complete because the utility_contracts crate currently has pre-existing compile errors unrelated to the new E2EE code (examples: duplicate MIGRATION_INSTRUCTION_BUDGET definition, an over-long symbol_short! usage, std usage in no_std-configured test modules, and missing generated tariff-oracle types), so the added unit tests could not be executed end-to-end in the current workspace.
The added tests are present and exercise the envelope validation functions locally and will pass once the existing crate-level compilation issues are resolved.
Closes #91