From fd216b747580416aba28c8e18f76e5b19c05f188 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Sun, 8 Nov 2026 00:37:10 +0700 Subject: [PATCH 01/11] feat(sdk): refuse a private document type too small for its payload Platform holds a private document type's entrySize only to 1 to 4096: it never reads an entry, so it registers a type whose entries cannot hold its own properties, and that size can never change. The SDK now refuses such a type before signing. dpp: - DocumentPropertyType::max_encoded_value_size, next to the encoder it follows: the most bytes a value's encoding takes, None when nothing bounds it (a string without maxLength or maxBytes, a byte array without maxItems, an untyped array). - largest_private_document_payload_size: a type's properties at their largest, with the presence byte of each optional one, as a document writes them after its system fields; refused with UnboundedPrivateDocumentProperty when a property has no bound. - minimum_private_document_entry_size: that plus the 299 bytes of the standard private document envelope (version 1), whose sizes are now named constants. - validate_private_document_entry_size: refuses a private type whose entrySize is below it (PrivateDocumentEntrySizeTooSmall). rs-sdk: ensure_private_document_entries_fit runs it on every type of a contract; PutContract calls it before fetching the nonce, and wasm-sdk's contract update calls it too. Tests check the largest payload against a document of a type holding every bounded property kind, serialized. Co-Authored-By: Claude Opus 5.5 --- book/src/contract-keywords.md | 2 +- .../src/data_contract/document_type/mod.rs | 7 +- .../document_type/private_document.rs | 342 +++++++++++++++++- .../document_type/property/mod.rs | 74 ++++ packages/rs-dpp/src/errors/protocol_error.rs | 23 ++ .../src/platform/transition/put_contract.rs | 82 +++++ .../src/state_transitions/contract.rs | 8 +- 7 files changed, 534 insertions(+), 4 deletions(-) diff --git a/book/src/contract-keywords.md b/book/src/contract-keywords.md index 0483204e46f..d25620aee1d 100644 --- a/book/src/contract-keywords.md +++ b/book/src/contract-keywords.md @@ -146,7 +146,7 @@ Every key a contract can write, grouped by where it goes. **Since** is the proto | `rangeCountable`, `rangeSummable`, `rangeAverageable` | boolean | Provable counts, sums or averages over ranges of document ids. | 12 | [Document type range keys](contract-keywords/aggregates.md#document-type-rangecountable-rangesummable-rangeaverageable) | | `indexOnly` | boolean | Documents are never stored whole: the index entries are the rows. | 14 | [indexOnly](contract-keywords/index-only.md#indexonly) ยท [internals](drive/index-only-document-types.md) | | `entryPayload` | array of 1 to 16 names | On an index-only type, properties carried in each entry's value instead of a key. | 14 | [entryPayload](contract-keywords/index-only.md#entrypayload) | -| `private` | object: `entrySize`, 1 to 4096 | A private type: its documents are encrypted entries of `entrySize` bytes, which the chain never reads. Its `properties` describe the plaintext. It declares only `type`, `properties`, `required`, `additionalProperties`, `minProperties`, `maxProperties`, `dependentRequired`, `$comment`, `description`, the two bounded key keys, and `documentsMutable`, `canBeDeleted` and `documentsKeepHistory` as `false`, each at most once; neither its properties nor `required` nor `dependentRequired` name a system field, no property at any depth declares `refersTo`, `distinctFrom`, `generatedFrom`, `encryptedFor` or `requiredSince`, and the contract's elected moderators may not moderate it. No reference, `countOf` or `sumOf` may name it, an update cannot change it, and a Batch refuses every document transition on it (`DocumentTypePrivateError`, 10425). Entries are appended only by `PrivateDocumentCreateFromShieldedPool` (type 29), from 1 to 16 distinct entries of exactly `entrySize` bytes, paid from the credit shielded pool. | 15 | | +| `private` | object: `entrySize`, 1 to 4096 | A private type: its documents are encrypted entries of `entrySize` bytes, which the chain never reads. Its `properties` describe the plaintext. It declares only `type`, `properties`, `required`, `additionalProperties`, `minProperties`, `maxProperties`, `dependentRequired`, `$comment`, `description`, the two bounded key keys, and `documentsMutable`, `canBeDeleted` and `documentsKeepHistory` as `false`, each at most once; neither its properties nor `required` nor `dependentRequired` name a system field, no property at any depth declares `refersTo`, `distinctFrom`, `generatedFrom`, `encryptedFor` or `requiredSince`, and the contract's elected moderators may not moderate it. No reference, `countOf` or `sumOf` may name it, an update cannot change it, and a Batch refuses every document transition on it (`DocumentTypePrivateError`, 10425). Entries are appended only by `PrivateDocumentCreateFromShieldedPool` (type 29), from 1 to 16 distinct entries of exactly `entrySize` bytes, paid from the credit shielded pool. The chain does not compare `entrySize` with the properties; the SDK refuses to register a private type whose `entrySize` is below its largest payload plus the private document envelope's 299 bytes, or whose properties are not all bounded (`minimum_private_document_entry_size` in dpp). | 15 | | ### Property diff --git a/packages/rs-dpp/src/data_contract/document_type/mod.rs b/packages/rs-dpp/src/data_contract/document_type/mod.rs index 2669afc319a..cf279a48e93 100644 --- a/packages/rs-dpp/src/data_contract/document_type/mod.rs +++ b/packages/rs-dpp/src/data_contract/document_type/mod.rs @@ -14,8 +14,13 @@ pub mod property_constraints; pub use index_level::IndexLevel; pub use index_level::IndexLevelTypeInfo; pub use index_level::IndexType; -pub use private_document::PrivateDocumentConfig; pub(crate) use private_document::PRIVATE_DOCUMENT_TYPE_KEYWORDS; +pub use private_document::{ + largest_private_document_payload_size, minimum_private_document_entry_size, + validate_private_document_entry_size, PrivateDocumentConfig, + PRIVATE_DOCUMENT_ENVELOPE_V1_BODY_HEADER_BYTES, PRIVATE_DOCUMENT_ENVELOPE_V1_OVERHEAD_BYTES, + PRIVATE_DOCUMENT_ENVELOPE_V1_WRAPPER_BYTES, +}; #[cfg(feature = "random-documents")] pub mod random_document; diff --git a/packages/rs-dpp/src/data_contract/document_type/private_document.rs b/packages/rs-dpp/src/data_contract/document_type/private_document.rs index 324adfe5d6d..b22f0fcb6de 100644 --- a/packages/rs-dpp/src/data_contract/document_type/private_document.rs +++ b/packages/rs-dpp/src/data_contract/document_type/private_document.rs @@ -8,7 +8,12 @@ //! The type's `properties` describe the plaintext, so that clients can decode it with types. //! The chain checks them at registration like any schema, and never against an entry. -use crate::data_contract::document_type::property_names; +use crate::data_contract::document_type::accessors::{ + DocumentTypeV0Getters, DocumentTypeV2Getters, +}; +use crate::data_contract::document_type::{property_names, DocumentTypeRef}; +use crate::ProtocolError; +use platform_version::version::PlatformVersion; use std::num::NonZeroU32; /// What a document type's `private` keyword declares (`{ "entrySize": n }`). Built only by the @@ -59,3 +64,338 @@ pub(crate) const PRIVATE_DOCUMENT_TYPE_KEYWORDS: [&str; 15] = [ property_names::REQUIRES_IDENTITY_ENCRYPTION_BOUNDED_KEY, property_names::REQUIRES_IDENTITY_DECRYPTION_BOUNDED_KEY, ]; + +/// The bytes the standard private document envelope (version 1) wraps the encrypted body in: the +/// commitment (32), the ephemeral public key (33), the body's AEAD tag (16) and the sender-recovery +/// ciphertext (81). +pub const PRIVATE_DOCUMENT_ENVELOPE_V1_WRAPPER_BYTES: u32 = 32 + 33 + 16 + 81; + +/// The bytes the standard private document envelope (version 1) puts in the body before the +/// payload: the envelope version (1), the authentication mode (1), the sender's identity id (32) +/// and key id (4), the authentication (65), the recipient's identity id (32) and the payload's +/// length (2). +pub const PRIVATE_DOCUMENT_ENVELOPE_V1_BODY_HEADER_BYTES: u32 = 1 + 1 + 32 + 4 + 65 + 32 + 2; + +/// Every byte of an entry the standard private document envelope (version 1) takes besides the +/// payload: 299. +pub const PRIVATE_DOCUMENT_ENVELOPE_V1_OVERHEAD_BYTES: u32 = + PRIVATE_DOCUMENT_ENVELOPE_V1_WRAPPER_BYTES + PRIVATE_DOCUMENT_ENVELOPE_V1_BODY_HEADER_BYTES; + +/// The most bytes a payload of `document_type` takes: its properties in the document property +/// encoding, as a document writes them after its system fields, each one present at its largest +/// and one written with a presence byte (optional or transient) counting that byte. A private +/// type's entries carry their plaintext in this encoding. +/// +/// Refused with `UnboundedPrivateDocumentProperty` when a property sets no largest value, since +/// then no entry size holds every payload. +pub fn largest_private_document_payload_size( + document_type: DocumentTypeRef, + platform_version: &PlatformVersion, +) -> Result { + let mut size = 0u32; + for (property_name, property) in document_type.properties() { + // A private type refuses `requiredSince`, so a property is required at every contract + // version an entry is written under. + let presence_byte = !property.required || property.transient; + let Some(value_size) = property + .property_type + .max_encoded_value_size(property.required, platform_version)? + else { + return Err(ProtocolError::UnboundedPrivateDocumentProperty { + document_type_name: document_type.name().clone(), + property_name: property_name.clone(), + }); + }; + size = size + .saturating_add(value_size) + .saturating_add(u32::from(presence_byte)); + } + Ok(size) +} + +/// The smallest `entrySize` that holds every payload of `document_type` in the standard private +/// document envelope (version 1): its largest payload plus +/// [`PRIVATE_DOCUMENT_ENVELOPE_V1_OVERHEAD_BYTES`]. +pub fn minimum_private_document_entry_size( + document_type: DocumentTypeRef, + platform_version: &PlatformVersion, +) -> Result { + Ok( + largest_private_document_payload_size(document_type, platform_version)? + .saturating_add(PRIVATE_DOCUMENT_ENVELOPE_V1_OVERHEAD_BYTES), + ) +} + +/// Refuses a private document type whose `entrySize` cannot hold its largest payload in the +/// standard private document envelope (version 1), which clients check before registering one. +/// The chain does not: it never reads an entry, so it only holds `entrySize` to +/// `max_private_document_entry_size`, and such a type registers but takes no full payload. A type +/// that is not private passes. +pub fn validate_private_document_entry_size( + document_type: DocumentTypeRef, + platform_version: &PlatformVersion, +) -> Result<(), ProtocolError> { + let Some(private_document) = document_type.private_document() else { + return Ok(()); + }; + let minimum_entry_size = minimum_private_document_entry_size(document_type, platform_version)?; + if private_document.entry_size() < minimum_entry_size { + return Err(ProtocolError::PrivateDocumentEntrySizeTooSmall { + document_type_name: document_type.name().clone(), + entry_size: private_document.entry_size(), + minimum_entry_size, + }); + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::data_contract::accessors::v0::DataContractV0Getters; + use crate::data_contract::conversion::value::v0::DataContractValueConversionMethodsV0; + use crate::data_contract::document_type::DocumentPropertyType; + use crate::data_contract::DataContract; + use crate::document::serialization_traits::DocumentPlatformConversionMethodsV0; + use crate::document::DocumentV0; + use platform_value::string_encoding::Encoding; + use platform_value::{Identifier, Value}; + use serde_json::json; + use std::collections::BTreeMap; + + /// A contract holding the private `secret` type of `entry_size`-byte entries with + /// `properties`, of which `required` are required, and the public `note` type. + fn contract( + entry_size: u32, + properties: serde_json::Value, + required: serde_json::Value, + ) -> DataContract { + DataContract::from_value( + platform_value::to_value(json!({ + "$formatVersion": "1", + "id": Identifier::from([7; 32]).to_string(Encoding::Base58), + "ownerId": Identifier::from([8; 32]).to_string(Encoding::Base58), + "version": 1, + "documentSchemas": { + "secret": { + "type": "object", + "private": { "entrySize": entry_size }, + "documentsMutable": false, + "canBeDeleted": false, + "properties": properties, + "required": required, + "additionalProperties": false + }, + "note": { + "type": "object", + "properties": { + "text": { "type": "string", "maxLength": 63, "position": 0 } + }, + "additionalProperties": false + } + } + })) + .expect("the contract converts"), + true, + PlatformVersion::latest(), + ) + .expect("the contract registers") + } + + /// One property of every kind a largest size bounds, optional ones among them. + fn every_bounded_kind() -> serde_json::Value { + json!({ + "small": { "type": "integer", "minimum": 0, "maximum": 255, "position": 0 }, + "large": { "type": "integer", "position": 1 }, + "label": { "type": "string", "maxLength": 10, "position": 2 }, + "short": { "type": "string", "maxBytes": 20, "position": 3 }, + "both": { "type": "string", "maxLength": 4, "maxBytes": 10, "position": 4 }, + "key": { + "type": "array", "byteArray": true, "minItems": 33, "maxItems": 33, + "position": 5 + }, + "blob": { "type": "array", "byteArray": true, "maxItems": 300, "position": 6 }, + "flag": { "type": "boolean", "position": 7 }, + "who": { + "type": "array", "byteArray": true, "minItems": 32, "maxItems": 32, + "contentMediaType": "application/x.dash.dpp.identifier", "position": 8 + }, + "meta": { + "type": "object", + "properties": { + "a": { "type": "integer", "minimum": 0, "maximum": 65535, "position": 0 }, + "b": { "type": "string", "maxLength": 5, "position": 1 } + }, + "required": ["a"], + "additionalProperties": false, + "position": 9 + }, + "tags": { + "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 8 }, + "position": 10 + } + }) + } + + /// Four bytes a character, the most UTF-8 takes. + fn wide(characters: usize) -> String { + "\u{1F600}".repeat(characters) + } + + /// Every property of [`every_bounded_kind`] at its largest value. + fn largest_values() -> BTreeMap { + BTreeMap::from([ + ("small".to_string(), Value::U64(255)), + ("large".to_string(), Value::I64(i64::MAX)), + ("label".to_string(), Value::Text(wide(10))), + ("short".to_string(), Value::Text("a".repeat(20))), + // Four characters, ten bytes: the byte bound is the lower one. + ("both".to_string(), Value::Text(format!("{}ab", wide(2)))), + ("key".to_string(), Value::Bytes(vec![1; 33])), + ("blob".to_string(), Value::Bytes(vec![2; 300])), + ("flag".to_string(), Value::Bool(true)), + ("who".to_string(), Value::Identifier([3; 32])), + ( + "meta".to_string(), + Value::Map(vec![ + (Value::Text("a".to_string()), Value::U64(65535)), + (Value::Text("b".to_string()), Value::Text(wide(5))), + ]), + ), + ( + "tags".to_string(), + Value::Array(vec![Value::Text(wide(8)); 3]), + ), + ]) + } + + /// The largest payload is what a document of the type holding every property at its largest + /// serializes to after its system fields: the format version (1), the contract version stamp + /// (1), `$id` (32), `$ownerId` (32) and the system field flags (2), 68 bytes for a private + /// type, which keeps no revision, times or creator. + #[test] + fn should_size_the_largest_payload_as_a_document_serializes_it() { + let platform_version = PlatformVersion::latest(); + let contract = contract(1000, every_bounded_kind(), json!(["small", "large", "key"])); + let secret = contract + .document_type_for_name("secret") + .expect("the secret type"); + + let largest = largest_private_document_payload_size(secret, platform_version) + .expect("every property is bounded"); + // 1 + 8 + (1 + 1 + 40) + (1 + 1 + 20) + (1 + 1 + 10) + 33 + (1 + 2 + 300) + (1 + 1) + // + (1 + 32) + (1 + 1 + 2 + 1 + 1 + 20) + (1 + 1 + 3 * (1 + 32)) + assert_eq!(largest, 583); + + let document = DocumentV0 { + id: Identifier::from([4; 32]), + owner_id: Identifier::from([5; 32]), + properties: largest_values(), + ..Default::default() + }; + let serialized = document + .serialize(secret, &contract, platform_version) + .expect("the document serializes"); + assert_eq!(&serialized[..2], &[3, 0]); + assert_eq!(&serialized[2..34], &[4; 32]); + assert_eq!(&serialized[34..66], &[5; 32]); + assert_eq!(&serialized[66..68], &[0, 0]); + assert_eq!(serialized.len() - 68, largest as usize); + } + + /// The smallest entry size is the largest payload and the envelope's 299 bytes; a type of that + /// size passes, one byte less is refused with both numbers, and a public type always passes. + #[test] + fn should_refuse_a_private_type_whose_entries_cannot_hold_its_largest_payload() { + let platform_version = PlatformVersion::latest(); + assert_eq!(PRIVATE_DOCUMENT_ENVELOPE_V1_OVERHEAD_BYTES, 299); + let required = json!(["small", "large", "key"]); + let minimum = minimum_private_document_entry_size( + contract(1000, every_bounded_kind(), required.clone()) + .document_type_for_name("secret") + .expect("the secret type"), + platform_version, + ) + .expect("every property is bounded"); + assert_eq!(minimum, 583 + 299); + + let fitting = contract(minimum, every_bounded_kind(), required.clone()); + for name in ["secret", "note"] { + validate_private_document_entry_size( + fitting.document_type_for_name(name).expect("the type"), + platform_version, + ) + .unwrap_or_else(|error| panic!("{name} passes: {error}")); + } + + let short = contract(minimum - 1, every_bounded_kind(), required); + match validate_private_document_entry_size( + short.document_type_for_name("secret").expect("the type"), + platform_version, + ) { + Err(ProtocolError::PrivateDocumentEntrySizeTooSmall { + document_type_name, + entry_size, + minimum_entry_size, + }) => { + assert_eq!(document_type_name, "secret"); + assert_eq!(entry_size, minimum - 1); + assert_eq!(minimum_entry_size, minimum); + } + other => panic!("expected the entry size refusal, got {other:?}"), + } + } + + /// A string without `maxLength` or `maxBytes`, or a byte array without `maxItems`, sets no + /// largest payload, so no entry size holds every one. + #[test] + fn should_refuse_a_private_type_with_an_unbounded_property() { + for property in [ + json!({ "type": "string", "position": 1 }), + json!({ "type": "array", "byteArray": true, "position": 1 }), + ] { + let contract = contract( + 4096, + json!({ + "small": { "type": "integer", "minimum": 0, "maximum": 255, "position": 0 }, + "open": property + }), + json!(["small"]), + ); + match validate_private_document_entry_size( + contract.document_type_for_name("secret").expect("the type"), + PlatformVersion::latest(), + ) { + Err(ProtocolError::UnboundedPrivateDocumentProperty { + document_type_name, + property_name, + }) => { + assert_eq!(document_type_name, "secret"); + assert_eq!(property_name, "open"); + } + other => panic!("expected the unbounded refusal, got {other:?}"), + } + } + } + + /// A `Date` property carries a marker byte when it is optional; its largest size counts it, + /// as its encoding writes it. + #[test] + fn should_size_a_date_with_its_optional_marker() { + let platform_version = PlatformVersion::latest(); + for required in [true, false] { + assert_eq!( + DocumentPropertyType::Date + .max_encoded_value_size(required, platform_version) + .expect("sized"), + Some( + DocumentPropertyType::Date + .encode_value_ref_with_size(&Value::Float(1.5), required) + .expect("encodes") + .len() as u32 + ), + "required: {required}" + ); + } + } +} diff --git a/packages/rs-dpp/src/data_contract/document_type/property/mod.rs b/packages/rs-dpp/src/data_contract/document_type/property/mod.rs index e7b17533de8..c9e2567d2e7 100644 --- a/packages/rs-dpp/src/data_contract/document_type/property/mod.rs +++ b/packages/rs-dpp/src/data_contract/document_type/property/mod.rs @@ -3050,6 +3050,80 @@ impl DocumentPropertyType { } } + /// The most bytes [`Self::encode_value_ref_with_size`] writes for a value of this type, `None` + /// when the type sets no largest value: a string with neither `maxLength` nor `maxBytes`, a byte + /// array without `maxItems`, or an untyped array. `required` is the flag the encoding is called + /// with (an optional `Date` carries a marker byte); the presence byte a document writes before + /// an optional property is not counted. + /// + /// Each arm is the largest output of the matching arm of the encoder, which this must follow + /// when that changes. + pub fn max_encoded_value_size( + &self, + required: bool, + platform_version: &PlatformVersion, + ) -> Result, ProtocolError> { + // A varint length, then that many bytes. + let length_prefixed = |bytes: u32| bytes.saturating_add(bytes.required_space() as u32); + Ok(match self { + DocumentPropertyType::String(sizes) => { + // A character takes at most 4 bytes in UTF-8. + let max_bytes = match (sizes.max_length, sizes.max_bytes) { + (max_length, Some(max_bytes)) => max_length + .map_or(u32::from(max_bytes), |length| { + (u32::from(length) * 4).min(u32::from(max_bytes)) + }), + (Some(max_length), None) => u32::from(max_length) * 4, + (None, None) => return Ok(None), + }; + Some(length_prefixed(max_bytes)) + } + DocumentPropertyType::Date => Some(if required { 8 } else { 9 }), + DocumentPropertyType::U128 | DocumentPropertyType::I128 => Some(16), + DocumentPropertyType::U64 | DocumentPropertyType::I64 | DocumentPropertyType::F64 => { + Some(8) + } + DocumentPropertyType::U32 + | DocumentPropertyType::I32 + | DocumentPropertyType::KeyIdWithReference(_) => Some(4), + DocumentPropertyType::U16 | DocumentPropertyType::I16 => Some(2), + DocumentPropertyType::U8 | DocumentPropertyType::I8 | DocumentPropertyType::Boolean => { + Some(1) + } + DocumentPropertyType::ByteArray(sizes) => match (sizes.min_size, sizes.max_size) { + (Some(min), Some(max)) if min == max => Some(u32::from(max)), + (_, Some(max)) => Some(length_prefixed(u32::from(max))), + (_, None) => None, + }, + DocumentPropertyType::Identifier | DocumentPropertyType::IdentifierWithReference(_) => { + Some(32) + } + DocumentPropertyType::Object(inner_fields) => { + let mut inner = 0u32; + for field in inner_fields.values() { + let Some(field_size) = field + .property_type + .max_encoded_value_size(field.required, platform_version)? + else { + return Ok(None); + }; + inner = inner + .saturating_add(field_size) + .saturating_add(u32::from(!field.required)); + } + Some(length_prefixed(inner)) + } + DocumentPropertyType::TypedArray(typed_array) => { + // It saturates at `u16::MAX`, which an unbounded element reports. + match typed_array.max_encoded_size(platform_version)? { + u16::MAX => None, + size => Some(u32::from(size)), + } + } + DocumentPropertyType::Array(_) | DocumentPropertyType::VariableTypeArray(_) => None, + }) + } + pub fn encode_value_ref_with_size( &self, value: &Value, diff --git a/packages/rs-dpp/src/errors/protocol_error.rs b/packages/rs-dpp/src/errors/protocol_error.rs index 1cc5106db22..4bf6d504d64 100644 --- a/packages/rs-dpp/src/errors/protocol_error.rs +++ b/packages/rs-dpp/src/errors/protocol_error.rs @@ -164,6 +164,29 @@ pub enum ProtocolError { #[error("Shielded transaction build error: {0}")] ShieldedBuildError(String), + /// A private document type's `entrySize` is smaller than its largest payload needs in the + /// standard private document envelope. The chain registers such a type, but clients refuse to. + #[error( + "private document type {document_type_name} takes entries of {entry_size} bytes, fewer than \ + the {minimum_entry_size} its largest payload needs in the private document envelope" + )] + PrivateDocumentEntrySizeTooSmall { + document_type_name: String, + entry_size: u32, + minimum_entry_size: u32, + }, + + /// A property of a private document type sets no largest value, so no entry size holds every + /// payload of the type. + #[error( + "property {property_name} of private document type {document_type_name} sets no largest \ + value, so no entry size holds every payload" + )] + UnboundedPrivateDocumentProperty { + document_type_name: String, + property_name: String, + }, + #[error("Not supported Error: {0}")] NotSupported(String), diff --git a/packages/rs-sdk/src/platform/transition/put_contract.rs b/packages/rs-sdk/src/platform/transition/put_contract.rs index 19e0ec51182..225df46c531 100644 --- a/packages/rs-sdk/src/platform/transition/put_contract.rs +++ b/packages/rs-sdk/src/platform/transition/put_contract.rs @@ -4,6 +4,7 @@ use crate::{Error, Sdk}; use crate::platform::transition::put_settings::PutSettings; use dpp::data_contract::accessors::v0::DataContractV0Getters; +use dpp::data_contract::document_type::validate_private_document_entry_size; use dpp::data_contract::DataContract; use dpp::identity::identity_public_key::accessors::v0::IdentityPublicKeyGettersV0; use dpp::identity::signer::Signer; @@ -11,11 +12,26 @@ use dpp::identity::{IdentityPublicKey, PartialIdentity}; use dpp::state_transition::data_contract_create_transition::methods::DataContractCreateTransitionMethodsV0; use dpp::state_transition::data_contract_create_transition::DataContractCreateTransition; use dpp::state_transition::StateTransition; +use dpp::version::PlatformVersion; use super::broadcast::BroadcastStateTransition; use super::validation::ensure_valid_state_transition_structure; use super::waitable::Waitable; +/// Refuses `data_contract` when one of its private document types takes entries too small for +/// its largest payload in the standard private document envelope, or has a property with no +/// largest value. Platform registers such a type, since it never reads an entry, but no full +/// entry fits it and its entry size can never change, so the SDK refuses it before signing. +pub fn ensure_private_document_entries_fit( + data_contract: &DataContract, + platform_version: &PlatformVersion, +) -> Result<(), Error> { + for document_type in data_contract.document_types().values() { + validate_private_document_entry_size(document_type.as_ref(), platform_version)?; + } + Ok(()) +} + #[async_trait::async_trait] /// A trait for putting a contract to platform pub trait PutContract>: Waitable { @@ -48,6 +64,8 @@ impl> PutContract for DataContract { signer: &S, settings: Option, ) -> Result { + ensure_private_document_entries_fit(self, sdk.version())?; + let new_identity_nonce = sdk .get_identity_nonce(self.owner_id(), true, settings) .await?; @@ -93,3 +111,67 @@ impl> PutContract for DataContract { Self::wait_for_response(sdk, state_transition, settings).await } } + +#[cfg(test)] +mod tests { + use super::*; + use dpp::data_contract::conversion::value::v0::DataContractValueConversionMethodsV0; + use dpp::platform_value::string_encoding::Encoding; + use dpp::platform_value::{platform_value, Identifier}; + use dpp::ProtocolError; + + /// A contract with the private type `request` of `entry_size`-byte entries, whose largest + /// payload is 8 + 69 = 77 bytes, so it needs 77 + 299 = 376. + fn contract(entry_size: u32) -> DataContract { + let id = Identifier::from([7; 32]).to_string(Encoding::Base58); + let owner_id = Identifier::from([8; 32]).to_string(Encoding::Base58); + DataContract::from_value( + platform_value!({ + "$formatVersion": "1", + "id": id, + "ownerId": owner_id, + "version": 1, + "documentSchemas": { + "request": { + "type": "object", + "private": { "entrySize": entry_size }, + "documentsMutable": false, + "canBeDeleted": false, + "properties": { + "reference": { "type": "integer", "position": 0 }, + "key": { + "type": "array", "byteArray": true, + "minItems": 69, "maxItems": 69, "position": 1 + } + }, + "required": ["reference", "key"], + "additionalProperties": false + } + } + }), + true, + PlatformVersion::latest(), + ) + .expect("the contract registers") + } + + #[test] + fn should_refuse_a_contract_whose_private_entries_cannot_hold_their_payload() { + let platform_version = PlatformVersion::latest(); + ensure_private_document_entries_fit(&contract(376), platform_version) + .expect("376 bytes hold the largest payload"); + match ensure_private_document_entries_fit(&contract(375), platform_version) { + Err(Error::Protocol(ProtocolError::PrivateDocumentEntrySizeTooSmall { + document_type_name, + entry_size, + minimum_entry_size, + })) => { + assert_eq!( + (document_type_name.as_str(), entry_size, minimum_entry_size), + ("request", 375, 376) + ); + } + other => panic!("expected the entry size refusal, got {other:?}"), + } + } +} diff --git a/packages/wasm-sdk/src/state_transitions/contract.rs b/packages/wasm-sdk/src/state_transitions/contract.rs index 8e66b8220e9..89329140206 100644 --- a/packages/wasm-sdk/src/state_transitions/contract.rs +++ b/packages/wasm-sdk/src/state_transitions/contract.rs @@ -23,7 +23,9 @@ use dash_sdk::dpp::state_transition::data_contract_update_transition::DataContra use dash_sdk::dpp::ProtocolError; use dash_sdk::platform::transition::broadcast::BroadcastStateTransition; use dash_sdk::platform::transition::contract_user_moderation::ModerateContractUser; -use dash_sdk::platform::transition::put_contract::PutContract; +use dash_sdk::platform::transition::put_contract::{ + ensure_private_document_entries_fit, PutContract, +}; use dash_sdk::platform::transition::put_settings::PutSettings; use std::collections::BTreeMap; use wasm_bindgen::prelude::*; @@ -223,6 +225,10 @@ impl WasmSdk { let contract_id: Identifier = updated_contract.id(); let owner_id: Identifier = updated_contract.owner_id(); + // A private document type the update adds takes entries that must hold its largest + // payload, as on create. + ensure_private_document_entries_fit(&updated_contract, self.inner_sdk().version())?; + // Get identity contract nonce let identity_contract_nonce = self .inner_sdk() From 63e31599bde16647143caace3c2231076f5e2f3f Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Sun, 8 Nov 2026 01:21:30 +0700 Subject: [PATCH 02/11] fix(sdk): check only the private types a contract update adds or changes, and size typed arrays exactly - A contract update is checked against the contract as Platform holds it: a private type it already holds with the same properties is skipped, so an update is never refused for a type registered before it. rs-sdk's ensure_private_document_entries_fit takes the stored contract, and the new ensure_private_document_entries_fit_on_update fetches it, only when the update declares a private type; wasm-sdk's contractUpdate calls that. - A typed array is sized from its element's own largest size instead of TypedArrayProperty::max_encoded_size, which saturates at u16::MAX: a bounded array larger than that keeps its size and is refused as too small, not as unbounded, and one of maxItems 0 takes its 1 byte whatever its element type. - The size functions take no platform version: the encoding they follow takes none. Co-Authored-By: Claude Opus 5.5 --- .../document_type/private_document.rs | 82 ++++++++++---- .../document_type/property/mod.rs | 37 +++---- .../src/platform/transition/put_contract.rs | 100 +++++++++++++++--- .../src/state_transitions/contract.rs | 8 +- 4 files changed, 165 insertions(+), 62 deletions(-) diff --git a/packages/rs-dpp/src/data_contract/document_type/private_document.rs b/packages/rs-dpp/src/data_contract/document_type/private_document.rs index b22f0fcb6de..3342f427101 100644 --- a/packages/rs-dpp/src/data_contract/document_type/private_document.rs +++ b/packages/rs-dpp/src/data_contract/document_type/private_document.rs @@ -13,7 +13,6 @@ use crate::data_contract::document_type::accessors::{ }; use crate::data_contract::document_type::{property_names, DocumentTypeRef}; use crate::ProtocolError; -use platform_version::version::PlatformVersion; use std::num::NonZeroU32; /// What a document type's `private` keyword declares (`{ "entrySize": n }`). Built only by the @@ -90,7 +89,6 @@ pub const PRIVATE_DOCUMENT_ENVELOPE_V1_OVERHEAD_BYTES: u32 = /// then no entry size holds every payload. pub fn largest_private_document_payload_size( document_type: DocumentTypeRef, - platform_version: &PlatformVersion, ) -> Result { let mut size = 0u32; for (property_name, property) in document_type.properties() { @@ -99,7 +97,7 @@ pub fn largest_private_document_payload_size( let presence_byte = !property.required || property.transient; let Some(value_size) = property .property_type - .max_encoded_value_size(property.required, platform_version)? + .max_encoded_value_size(property.required) else { return Err(ProtocolError::UnboundedPrivateDocumentProperty { document_type_name: document_type.name().clone(), @@ -118,12 +116,9 @@ pub fn largest_private_document_payload_size( /// [`PRIVATE_DOCUMENT_ENVELOPE_V1_OVERHEAD_BYTES`]. pub fn minimum_private_document_entry_size( document_type: DocumentTypeRef, - platform_version: &PlatformVersion, ) -> Result { - Ok( - largest_private_document_payload_size(document_type, platform_version)? - .saturating_add(PRIVATE_DOCUMENT_ENVELOPE_V1_OVERHEAD_BYTES), - ) + Ok(largest_private_document_payload_size(document_type)? + .saturating_add(PRIVATE_DOCUMENT_ENVELOPE_V1_OVERHEAD_BYTES)) } /// Refuses a private document type whose `entrySize` cannot hold its largest payload in the @@ -133,12 +128,11 @@ pub fn minimum_private_document_entry_size( /// that is not private passes. pub fn validate_private_document_entry_size( document_type: DocumentTypeRef, - platform_version: &PlatformVersion, ) -> Result<(), ProtocolError> { let Some(private_document) = document_type.private_document() else { return Ok(()); }; - let minimum_entry_size = minimum_private_document_entry_size(document_type, platform_version)?; + let minimum_entry_size = minimum_private_document_entry_size(document_type)?; if private_document.entry_size() < minimum_entry_size { return Err(ProtocolError::PrivateDocumentEntrySizeTooSmall { document_type_name: document_type.name().clone(), @@ -160,6 +154,7 @@ mod tests { use crate::document::DocumentV0; use platform_value::string_encoding::Encoding; use platform_value::{Identifier, Value}; + use platform_version::version::PlatformVersion; use serde_json::json; use std::collections::BTreeMap; @@ -281,8 +276,8 @@ mod tests { .document_type_for_name("secret") .expect("the secret type"); - let largest = largest_private_document_payload_size(secret, platform_version) - .expect("every property is bounded"); + let largest = + largest_private_document_payload_size(secret).expect("every property is bounded"); // 1 + 8 + (1 + 1 + 40) + (1 + 1 + 20) + (1 + 1 + 10) + 33 + (1 + 2 + 300) + (1 + 1) // + (1 + 32) + (1 + 1 + 2 + 1 + 1 + 20) + (1 + 1 + 3 * (1 + 32)) assert_eq!(largest, 583); @@ -307,14 +302,12 @@ mod tests { /// size passes, one byte less is refused with both numbers, and a public type always passes. #[test] fn should_refuse_a_private_type_whose_entries_cannot_hold_its_largest_payload() { - let platform_version = PlatformVersion::latest(); assert_eq!(PRIVATE_DOCUMENT_ENVELOPE_V1_OVERHEAD_BYTES, 299); let required = json!(["small", "large", "key"]); let minimum = minimum_private_document_entry_size( contract(1000, every_bounded_kind(), required.clone()) .document_type_for_name("secret") .expect("the secret type"), - platform_version, ) .expect("every property is bounded"); assert_eq!(minimum, 583 + 299); @@ -323,7 +316,6 @@ mod tests { for name in ["secret", "note"] { validate_private_document_entry_size( fitting.document_type_for_name(name).expect("the type"), - platform_version, ) .unwrap_or_else(|error| panic!("{name} passes: {error}")); } @@ -331,7 +323,6 @@ mod tests { let short = contract(minimum - 1, every_bounded_kind(), required); match validate_private_document_entry_size( short.document_type_for_name("secret").expect("the type"), - platform_version, ) { Err(ProtocolError::PrivateDocumentEntrySizeTooSmall { document_type_name, @@ -364,7 +355,6 @@ mod tests { ); match validate_private_document_entry_size( contract.document_type_for_name("secret").expect("the type"), - PlatformVersion::latest(), ) { Err(ProtocolError::UnboundedPrivateDocumentProperty { document_type_name, @@ -378,16 +368,66 @@ mod tests { } } + /// A typed array is its varint count and that many of its largest element, as its encoder + /// writes it: one of no element takes 1 byte whatever its element type, and one larger than + /// `u16::MAX` bytes keeps its exact size. + #[test] + fn should_size_a_typed_array_as_its_encoding_takes_it() { + use crate::data_contract::document_type::property::array::TypedArrayProperty; + use crate::data_contract::document_type::{ByteArrayPropertySizes, StringPropertySizes}; + + let typed_array = |item_type: DocumentPropertyType, max_items: u16| { + DocumentPropertyType::TypedArray(TypedArrayProperty { + item_type: Box::new(item_type), + item_constraints: Default::default(), + min_items: None, + max_items, + unique_items: false, + }) + }; + let unbounded_string = DocumentPropertyType::String(StringPropertySizes { + min_length: None, + max_length: None, + max_bytes: None, + }); + let hundred_bytes = DocumentPropertyType::ByteArray(ByteArrayPropertySizes { + min_size: Some(100), + max_size: Some(100), + }); + + for (array, value) in [ + ( + typed_array(unbounded_string.clone(), 0), + Value::Array(vec![]), + ), + ( + typed_array(hundred_bytes, 1000), + Value::Array(vec![Value::Bytes(vec![1; 100]); 1000]), + ), + ] { + assert_eq!( + array.max_encoded_value_size(true), + Some( + array + .encode_value_ref_with_size(&value, true) + .expect("encodes") + .len() as u32 + ) + ); + } + assert_eq!( + typed_array(unbounded_string, 1).max_encoded_value_size(true), + None + ); + } + /// A `Date` property carries a marker byte when it is optional; its largest size counts it, /// as its encoding writes it. #[test] fn should_size_a_date_with_its_optional_marker() { - let platform_version = PlatformVersion::latest(); for required in [true, false] { assert_eq!( - DocumentPropertyType::Date - .max_encoded_value_size(required, platform_version) - .expect("sized"), + DocumentPropertyType::Date.max_encoded_value_size(required), Some( DocumentPropertyType::Date .encode_value_ref_with_size(&Value::Float(1.5), required) diff --git a/packages/rs-dpp/src/data_contract/document_type/property/mod.rs b/packages/rs-dpp/src/data_contract/document_type/property/mod.rs index c9e2567d2e7..a1f37c863f9 100644 --- a/packages/rs-dpp/src/data_contract/document_type/property/mod.rs +++ b/packages/rs-dpp/src/data_contract/document_type/property/mod.rs @@ -3052,20 +3052,17 @@ impl DocumentPropertyType { /// The most bytes [`Self::encode_value_ref_with_size`] writes for a value of this type, `None` /// when the type sets no largest value: a string with neither `maxLength` nor `maxBytes`, a byte - /// array without `maxItems`, or an untyped array. `required` is the flag the encoding is called + /// array without `maxItems`, an untyped array, or a typed array that may hold an element of + /// such a type. `required` is the flag the encoding is called /// with (an optional `Date` carries a marker byte); the presence byte a document writes before /// an optional property is not counted. /// /// Each arm is the largest output of the matching arm of the encoder, which this must follow /// when that changes. - pub fn max_encoded_value_size( - &self, - required: bool, - platform_version: &PlatformVersion, - ) -> Result, ProtocolError> { + pub fn max_encoded_value_size(&self, required: bool) -> Option { // A varint length, then that many bytes. let length_prefixed = |bytes: u32| bytes.saturating_add(bytes.required_space() as u32); - Ok(match self { + match self { DocumentPropertyType::String(sizes) => { // A character takes at most 4 bytes in UTF-8. let max_bytes = match (sizes.max_length, sizes.max_bytes) { @@ -3074,7 +3071,7 @@ impl DocumentPropertyType { (u32::from(length) * 4).min(u32::from(max_bytes)) }), (Some(max_length), None) => u32::from(max_length) * 4, - (None, None) => return Ok(None), + (None, None) => return None, }; Some(length_prefixed(max_bytes)) } @@ -3101,12 +3098,7 @@ impl DocumentPropertyType { DocumentPropertyType::Object(inner_fields) => { let mut inner = 0u32; for field in inner_fields.values() { - let Some(field_size) = field - .property_type - .max_encoded_value_size(field.required, platform_version)? - else { - return Ok(None); - }; + let field_size = field.property_type.max_encoded_value_size(field.required)?; inner = inner .saturating_add(field_size) .saturating_add(u32::from(!field.required)); @@ -3114,14 +3106,19 @@ impl DocumentPropertyType { Some(length_prefixed(inner)) } DocumentPropertyType::TypedArray(typed_array) => { - // It saturates at `u16::MAX`, which an unbounded element reports. - match typed_array.max_encoded_size(platform_version)? { - u16::MAX => None, - size => Some(u32::from(size)), - } + // A varint count, then each element encoded as a required property of its type. + // Counted here rather than by `max_encoded_size`, which saturates at `u16::MAX`. + let max_items = u32::from(typed_array.max_items); + let elements = if max_items == 0 { + 0 + } else { + let element = typed_array.item_type.max_encoded_value_size(true)?; + max_items.saturating_mul(element) + }; + Some(elements.saturating_add(max_items.required_space() as u32)) } DocumentPropertyType::Array(_) | DocumentPropertyType::VariableTypeArray(_) => None, - }) + } } pub fn encode_value_ref_with_size( diff --git a/packages/rs-sdk/src/platform/transition/put_contract.rs b/packages/rs-sdk/src/platform/transition/put_contract.rs index 225df46c531..f654469ee73 100644 --- a/packages/rs-sdk/src/platform/transition/put_contract.rs +++ b/packages/rs-sdk/src/platform/transition/put_contract.rs @@ -3,7 +3,9 @@ use std::collections::BTreeMap; use crate::{Error, Sdk}; use crate::platform::transition::put_settings::PutSettings; +use crate::platform::Fetch; use dpp::data_contract::accessors::v0::DataContractV0Getters; +use dpp::data_contract::document_type::accessors::{DocumentTypeV0Getters, DocumentTypeV2Getters}; use dpp::data_contract::document_type::validate_private_document_entry_size; use dpp::data_contract::DataContract; use dpp::identity::identity_public_key::accessors::v0::IdentityPublicKeyGettersV0; @@ -12,7 +14,6 @@ use dpp::identity::{IdentityPublicKey, PartialIdentity}; use dpp::state_transition::data_contract_create_transition::methods::DataContractCreateTransitionMethodsV0; use dpp::state_transition::data_contract_create_transition::DataContractCreateTransition; use dpp::state_transition::StateTransition; -use dpp::version::PlatformVersion; use super::broadcast::BroadcastStateTransition; use super::validation::ensure_valid_state_transition_structure; @@ -22,16 +23,43 @@ use super::waitable::Waitable; /// its largest payload in the standard private document envelope, or has a property with no /// largest value. Platform registers such a type, since it never reads an entry, but no full /// entry fits it and its entry size can never change, so the SDK refuses it before signing. +/// +/// For an update, `stored_contract` is the contract as Platform holds it: a type it already +/// holds with the same properties is not checked, since the update does not change what its +/// entries carry, so an update is never refused for a type registered before it. pub fn ensure_private_document_entries_fit( data_contract: &DataContract, - platform_version: &PlatformVersion, + stored_contract: Option<&DataContract>, ) -> Result<(), Error> { - for document_type in data_contract.document_types().values() { - validate_private_document_entry_size(document_type.as_ref(), platform_version)?; + for (name, document_type) in data_contract.document_types() { + let unchanged = stored_contract + .and_then(|stored| stored.document_types().get(name)) + .is_some_and(|stored_type| stored_type.properties() == document_type.properties()); + if !unchanged { + validate_private_document_entry_size(document_type.as_ref())?; + } } Ok(()) } +/// [`ensure_private_document_entries_fit`] for an update of `data_contract`, against the contract +/// as Platform holds it. It fetches that only when `data_contract` declares a private document +/// type, the one case with anything to check. +pub async fn ensure_private_document_entries_fit_on_update( + sdk: &Sdk, + data_contract: &DataContract, +) -> Result<(), Error> { + let declares_private_types = data_contract + .document_types() + .values() + .any(|document_type| document_type.private_document().is_some()); + if !declares_private_types { + return Ok(()); + } + let stored_contract = DataContract::fetch(sdk, data_contract.id()).await?; + ensure_private_document_entries_fit(data_contract, stored_contract.as_ref()) +} + #[async_trait::async_trait] /// A trait for putting a contract to platform pub trait PutContract>: Waitable { @@ -64,7 +92,7 @@ impl> PutContract for DataContract { signer: &S, settings: Option, ) -> Result { - ensure_private_document_entries_fit(self, sdk.version())?; + ensure_private_document_entries_fit(self, None)?; let new_identity_nonce = sdk .get_identity_nonce(self.owner_id(), true, settings) @@ -118,13 +146,30 @@ mod tests { use dpp::data_contract::conversion::value::v0::DataContractValueConversionMethodsV0; use dpp::platform_value::string_encoding::Encoding; use dpp::platform_value::{platform_value, Identifier}; + use dpp::version::PlatformVersion; use dpp::ProtocolError; /// A contract with the private type `request` of `entry_size`-byte entries, whose largest - /// payload is 8 + 69 = 77 bytes, so it needs 77 + 299 = 376. - fn contract(entry_size: u32) -> DataContract { + /// payload is 8 + 69 = 77 bytes, so it needs 77 + 299 = 376; with `label`, an optional string + /// of at most 20 bytes, 22 more. + fn contract(entry_size: u32, label: bool) -> DataContract { let id = Identifier::from([7; 32]).to_string(Encoding::Base58); let owner_id = Identifier::from([8; 32]).to_string(Encoding::Base58); + let mut properties = platform_value!({ + "reference": { "type": "integer", "position": 0 }, + "key": { + "type": "array", "byteArray": true, + "minItems": 69, "maxItems": 69, "position": 1 + } + }); + if label { + properties + .set_value( + "label", + platform_value!({ "type": "string", "maxBytes": 20, "position": 2 }), + ) + .expect("a map"); + } DataContract::from_value( platform_value!({ "$formatVersion": "1", @@ -137,13 +182,7 @@ mod tests { "private": { "entrySize": entry_size }, "documentsMutable": false, "canBeDeleted": false, - "properties": { - "reference": { "type": "integer", "position": 0 }, - "key": { - "type": "array", "byteArray": true, - "minItems": 69, "maxItems": 69, "position": 1 - } - }, + "properties": properties, "required": ["reference", "key"], "additionalProperties": false } @@ -157,10 +196,9 @@ mod tests { #[test] fn should_refuse_a_contract_whose_private_entries_cannot_hold_their_payload() { - let platform_version = PlatformVersion::latest(); - ensure_private_document_entries_fit(&contract(376), platform_version) + ensure_private_document_entries_fit(&contract(376, false), None) .expect("376 bytes hold the largest payload"); - match ensure_private_document_entries_fit(&contract(375), platform_version) { + match ensure_private_document_entries_fit(&contract(375, false), None) { Err(Error::Protocol(ProtocolError::PrivateDocumentEntrySizeTooSmall { document_type_name, entry_size, @@ -174,4 +212,32 @@ mod tests { other => panic!("expected the entry size refusal, got {other:?}"), } } + + /// An update checks the private types it adds or whose properties it changes, and leaves a + /// type Platform already holds unchanged, even one too small, since the update does not + /// change what its entries carry. + #[test] + fn should_check_only_the_private_types_an_update_adds_or_changes() { + let stored = contract(375, false); + ensure_private_document_entries_fit(&contract(375, false), Some(&stored)) + .expect("an unchanged type is not checked"); + assert!(matches!( + ensure_private_document_entries_fit(&contract(375, true), Some(&stored),), + Err(Error::Protocol( + ProtocolError::PrivateDocumentEntrySizeTooSmall { + minimum_entry_size: 398, + .. + } + )) + )); + // A type the stored contract does not hold is new, and checked. + let mut without_the_type = contract(4096, false); + without_the_type.document_types_mut().clear(); + assert!(matches!( + ensure_private_document_entries_fit(&contract(375, false), Some(&without_the_type),), + Err(Error::Protocol( + ProtocolError::PrivateDocumentEntrySizeTooSmall { .. } + )) + )); + } } diff --git a/packages/wasm-sdk/src/state_transitions/contract.rs b/packages/wasm-sdk/src/state_transitions/contract.rs index 89329140206..0ff48503b91 100644 --- a/packages/wasm-sdk/src/state_transitions/contract.rs +++ b/packages/wasm-sdk/src/state_transitions/contract.rs @@ -24,7 +24,7 @@ use dash_sdk::dpp::ProtocolError; use dash_sdk::platform::transition::broadcast::BroadcastStateTransition; use dash_sdk::platform::transition::contract_user_moderation::ModerateContractUser; use dash_sdk::platform::transition::put_contract::{ - ensure_private_document_entries_fit, PutContract, + ensure_private_document_entries_fit_on_update, PutContract, }; use dash_sdk::platform::transition::put_settings::PutSettings; use std::collections::BTreeMap; @@ -225,9 +225,9 @@ impl WasmSdk { let contract_id: Identifier = updated_contract.id(); let owner_id: Identifier = updated_contract.owner_id(); - // A private document type the update adds takes entries that must hold its largest - // payload, as on create. - ensure_private_document_entries_fit(&updated_contract, self.inner_sdk().version())?; + // A private document type the update adds, or whose properties it changes, takes entries + // that must hold its largest payload, as on create. + ensure_private_document_entries_fit_on_update(self.inner_sdk(), &updated_contract).await?; // Get identity contract nonce let identity_contract_nonce = self From 839bfbe7da86badae51382acaa5d440117aefe10 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Sun, 8 Nov 2026 02:25:10 +0700 Subject: [PATCH 03/11] feat(sdk): seal and open private document entries in the standard envelope The client side of private document types: building an entry a recipient can find, opening it, and recovering one's own. platform-encryption, new private_document_envelope (version 1): - seal_private_document_entry: a payload encrypted to one recipient key in an entry of the type's size. cm (keyed, committing to the recipient key, the contract and the type) | epk | ChaCha20-Poly1305 body | sender recovery ciphertext. The caller supplies a fresh 32-byte seed per entry; nothing else is random. - open_private_document_entry: tries each of a wallet's keys, passes over an entry for none of them, refuses one that opens but is malformed or names another recipient identity. - recover_sent_private_document_entry: the sender's own entries from its outgoing viewing key alone. - Three sender modes: anonymous; a deniable MAC under the static ECDH of the sender's and recipient's keys (DashPay's); a recoverable ECDSA signature. OpenedPrivateDocumentEntry::verify_sender checks the claim against the sender identity's key. - The 299 bytes of overhead are named constants; new CryptoError variants for the refusals. dpp: encode_private_document_payload / decode_private_document_payload, a type's properties as a format 3 document writes them after its system fields; decoding refuses any bytes that do not re-encode. rs-sdk tests tie the two: both crates count the envelope's bytes alike, and the largest payload of a type sized at its minimum fills one entry, sealed, opened, checked and decoded. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 1 + .../src/data_contract/document_type/mod.rs | 1 + .../document_type/private_document.rs | 194 ++++ packages/rs-platform-encryption/Cargo.toml | 5 +- packages/rs-platform-encryption/src/error.rs | 24 + packages/rs-platform-encryption/src/lib.rs | 10 + .../src/private_document_envelope.rs | 941 ++++++++++++++++++ packages/rs-sdk/src/platform.rs | 2 + .../private_document_envelope_tests.rs | 159 +++ 9 files changed, 1335 insertions(+), 2 deletions(-) create mode 100644 packages/rs-platform-encryption/src/private_document_envelope.rs create mode 100644 packages/rs-sdk/src/platform/private_document_envelope_tests.rs diff --git a/Cargo.lock b/Cargo.lock index dcedf6fa136..c903b1a44ec 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5383,6 +5383,7 @@ version = "5.0.3" dependencies = [ "aes 0.8.4", "cbc", + "chacha20poly1305", "hmac", "secp256k1 0.33.1", "sha2 0.10.9", diff --git a/packages/rs-dpp/src/data_contract/document_type/mod.rs b/packages/rs-dpp/src/data_contract/document_type/mod.rs index cf279a48e93..06cf577d693 100644 --- a/packages/rs-dpp/src/data_contract/document_type/mod.rs +++ b/packages/rs-dpp/src/data_contract/document_type/mod.rs @@ -16,6 +16,7 @@ pub use index_level::IndexLevelTypeInfo; pub use index_level::IndexType; pub(crate) use private_document::PRIVATE_DOCUMENT_TYPE_KEYWORDS; pub use private_document::{ + decode_private_document_payload, encode_private_document_payload, largest_private_document_payload_size, minimum_private_document_entry_size, validate_private_document_entry_size, PrivateDocumentConfig, PRIVATE_DOCUMENT_ENVELOPE_V1_BODY_HEADER_BYTES, PRIVATE_DOCUMENT_ENVELOPE_V1_OVERHEAD_BYTES, diff --git a/packages/rs-dpp/src/data_contract/document_type/private_document.rs b/packages/rs-dpp/src/data_contract/document_type/private_document.rs index 3342f427101..666198bc1da 100644 --- a/packages/rs-dpp/src/data_contract/document_type/private_document.rs +++ b/packages/rs-dpp/src/data_contract/document_type/private_document.rs @@ -12,7 +12,13 @@ use crate::data_contract::document_type::accessors::{ DocumentTypeV0Getters, DocumentTypeV2Getters, }; use crate::data_contract::document_type::{property_names, DocumentTypeRef}; +use crate::data_contract::DataContract; +use crate::document::serialization_traits::DocumentPlatformConversionMethodsV0; +use crate::document::DocumentV0; use crate::ProtocolError; +use platform_value::Value; +use platform_version::version::PlatformVersion; +use std::collections::BTreeMap; use std::num::NonZeroU32; /// What a document type's `private` keyword declares (`{ "entrySize": n }`). Built only by the @@ -143,6 +149,88 @@ pub fn validate_private_document_entry_size( Ok(()) } +/// The document serialization format whose property encoding a private document payload is: +/// a payload holds a type's properties exactly as a format 3 document writes them after its +/// system fields, whatever format later documents take. +const PRIVATE_DOCUMENT_PAYLOAD_DOCUMENT_FORMAT: u16 = 3; + +/// What a format 3 document of a private type writes before its properties, when its `$id` and +/// `$ownerId` are zeros and it carries no contract version stamp: the format version, the stamp +/// (0), the two ids and the system field flags, none set. A private type keeps no revision, no +/// times and no creator, so nothing else comes first. +fn private_document_payload_prefix() -> [u8; 68] { + let mut prefix = [0u8; 68]; + prefix[0] = PRIVATE_DOCUMENT_PAYLOAD_DOCUMENT_FORMAT as u8; + prefix +} + +fn refuse_a_public_type(document_type: DocumentTypeRef) -> Result<(), ProtocolError> { + match document_type.private_document() { + Some(_) => Ok(()), + None => Err(ProtocolError::NotSupported(format!( + "document type {} is not private, so it has no private document payload", + document_type.name() + ))), + } +} + +/// The payload a private document entry of `document_type` (of `data_contract`) carries for +/// `properties`: the type's properties in the document property encoding, as a format 3 document +/// writes them after its system fields. A value of the wrong type is refused; the schema's +/// bounds are not checked here, so a sender validates `properties` against the type first +/// (`DataContract::validate_document_properties`). +pub fn encode_private_document_payload( + data_contract: &DataContract, + document_type: DocumentTypeRef, + properties: BTreeMap, +) -> Result, ProtocolError> { + refuse_a_public_type(document_type)?; + let document = DocumentV0 { + properties, + ..Default::default() + }; + let serialized = document.serialize_specific_version( + document_type, + data_contract, + PRIVATE_DOCUMENT_PAYLOAD_DOCUMENT_FORMAT, + )?; + serialized + .strip_prefix(private_document_payload_prefix().as_slice()) + .map(<[u8]>::to_vec) + .ok_or_else(|| { + ProtocolError::CorruptedCodeExecution( + "a private type's document serializes its properties behind 68 bytes of \ + system fields" + .to_string(), + ) + }) +} + +/// The properties a private document payload of `document_type` (of `data_contract`) holds. +/// Only the encoding [`encode_private_document_payload`] gives back is read: a payload that does +/// not decode, or that holds anything else, such as bytes after the last property, is refused. +/// The schema's bounds are not checked here, so a recipient validates the properties against +/// the type before trusting them (`DataContract::validate_document_properties`). +pub fn decode_private_document_payload( + data_contract: &DataContract, + document_type: DocumentTypeRef, + payload: &[u8], + platform_version: &PlatformVersion, +) -> Result, ProtocolError> { + refuse_a_public_type(document_type)?; + let mut serialized = private_document_payload_prefix().to_vec(); + serialized.extend_from_slice(payload); + let properties = + DocumentV0::from_bytes(&serialized, document_type, platform_version)?.properties; + if encode_private_document_payload(data_contract, document_type, properties.clone())? != payload + { + return Err(ProtocolError::DecodingError( + "a private document payload holds bytes its properties do not encode to".to_string(), + )); + } + Ok(properties) +} + #[cfg(test)] mod tests { use super::*; @@ -421,6 +509,112 @@ mod tests { ); } + /// A payload is the type's properties as a document writes them after its system fields: + /// every property at its largest encodes to exactly the largest payload size, and decodes + /// back to properties that encode to the same bytes. + #[test] + fn should_encode_and_decode_a_payload_as_a_document_writes_its_properties() { + let platform_version = PlatformVersion::latest(); + let contract = contract(1000, every_bounded_kind(), json!(["small", "large", "key"])); + let secret = contract + .document_type_for_name("secret") + .expect("the secret type"); + + let payload = encode_private_document_payload(&contract, secret, largest_values()) + .expect("the values encode"); + assert_eq!( + payload.len() as u32, + largest_private_document_payload_size(secret).expect("bounded") + ); + let decoded = + decode_private_document_payload(&contract, secret, &payload, platform_version) + .expect("the payload decodes"); + assert_eq!(decoded.get("label"), Some(&Value::Text(wide(10)))); + assert_eq!(decoded.get("key"), Some(&Value::Bytes(vec![1; 33]))); + assert_eq!( + encode_private_document_payload(&contract, secret, decoded).expect("re-encodes"), + payload + ); + + // Only the required properties: each absent optional one is its presence byte. + let smallest = BTreeMap::from([ + ("small".to_string(), Value::U64(1)), + ("large".to_string(), Value::I64(2)), + ("key".to_string(), Value::Bytes(vec![1; 33])), + ]); + assert_eq!( + encode_private_document_payload(&contract, secret, smallest) + .expect("encodes") + .len(), + 1 + 8 + 33 + 8 + ); + } + + /// A payload holding anything but what its properties encode to, a byte after the last + /// property or one cut off, is refused, and a public type has no payload. + #[test] + fn should_refuse_a_payload_its_properties_do_not_encode_to() { + let platform_version = PlatformVersion::latest(); + let contract = contract(1000, every_bounded_kind(), json!(["small", "large", "key"])); + let secret = contract + .document_type_for_name("secret") + .expect("the secret type"); + let payload = + encode_private_document_payload(&contract, secret, largest_values()).expect("encodes"); + + let mut trailing = payload.clone(); + trailing.push(0); + assert!( + decode_private_document_payload(&contract, secret, &trailing, platform_version) + .is_err() + ); + assert!(decode_private_document_payload( + &contract, + secret, + &payload[..payload.len() - 1], + platform_version + ) + .is_err()); + + let note = contract + .document_type_for_name("note") + .expect("the note type"); + assert!(matches!( + encode_private_document_payload(&contract, note, BTreeMap::new()), + Err(ProtocolError::NotSupported(_)) + )); + assert!(matches!( + decode_private_document_payload(&contract, note, &[0], platform_version), + Err(ProtocolError::NotSupported(_)) + )); + } + + /// The type's schema validates a payload's properties, before sealing and after opening: + /// the largest values pass, and a string over its bound, which decodes, is refused. + #[cfg(feature = "validation")] + #[test] + fn should_validate_payload_properties_against_the_type() { + use crate::data_contract::document_type::property_constraints::DocumentSystemValues; + use crate::data_contract::methods::validate_document::DataContractDocumentValidationMethodsV0; + + let platform_version = PlatformVersion::latest(); + let contract = contract(1000, every_bounded_kind(), json!(["small", "large", "key"])); + let validate = |properties: BTreeMap| { + contract + .validate_document_properties( + "secret", + Value::from(properties), + &DocumentSystemValues::default(), + platform_version, + ) + .expect("validation runs") + }; + assert!(validate(largest_values()).is_valid()); + let mut too_long = largest_values(); + too_long.insert("label".to_string(), Value::Text(wide(11))); + assert!(!validate(too_long).is_valid()); + } + /// A `Date` property carries a marker byte when it is optional; its largest size counts it, /// as its encoding writes it. #[test] diff --git a/packages/rs-platform-encryption/Cargo.toml b/packages/rs-platform-encryption/Cargo.toml index 32c8f7a74ab..4f3a689792c 100644 --- a/packages/rs-platform-encryption/Cargo.toml +++ b/packages/rs-platform-encryption/Cargo.toml @@ -11,9 +11,10 @@ description = "Cryptographic utilities for Dash Platform (DIP-15 DashPay encrypt # doesn't pull in/compile all of dashcore. `secp256k1` is pinned to the same # 0.33 dashcore re-exports, so the public `SecretKey`/`PublicKey` types unify # with dashcore-typed callers (platform-wallet, rs-sdk-ffi). -secp256k1 = { version = "0.33.1", features = ["std"] } +secp256k1 = { version = "0.33.1", features = ["std", "recovery"] } aes = "0.8" cbc = "0.1" +chacha20poly1305 = "0.10" hmac = "0.12" sha2 = "0.10" thiserror = "1.0" @@ -21,4 +22,4 @@ thiserror = "1.0" [dev-dependencies] # Tests generate keypairs via secp256k1's RNG helpers (`generate_keypair`, # `secp256k1::rand`), gated behind the `rand` feature. -secp256k1 = { version = "0.33.1", features = ["std", "rand"] } +secp256k1 = { version = "0.33.1", features = ["std", "rand", "recovery"] } diff --git a/packages/rs-platform-encryption/src/error.rs b/packages/rs-platform-encryption/src/error.rs index 763aaa6ee6b..fbdac68ce7a 100644 --- a/packages/rs-platform-encryption/src/error.rs +++ b/packages/rs-platform-encryption/src/error.rs @@ -14,4 +14,28 @@ pub enum CryptoError { #[error("Invalid compact xpub length (DIP-15 requires exactly 69 bytes, got {0})")] InvalidCompactXpubLength(usize), + + #[error("a private document payload of {payload_len} bytes does not fit an entry that holds {capacity}")] + PrivateDocumentPayloadTooLarge { payload_len: usize, capacity: usize }, + + #[error("a private document entry of {0} bytes is shorter than the envelope's 299")] + InvalidPrivateDocumentEntryLength(usize), + + #[error("the ephemeral seed derives no valid secret key; draw another")] + InvalidPrivateDocumentEphemeralSeed, + + #[error("malformed private document entry: {0}")] + MalformedPrivateDocumentEntry(&'static str), + + #[error("private document envelope version {0} is not supported")] + UnsupportedPrivateDocumentEnvelopeVersion(u8), + + #[error("the private document entry names another recipient identity")] + WrongPrivateDocumentRecipient, + + #[error("the private document entry is anonymous: it names no sender to check")] + AnonymousPrivateDocumentSender, + + #[error("the private document entry's sender authentication does not verify")] + PrivateDocumentSenderNotAuthenticated, } diff --git a/packages/rs-platform-encryption/src/lib.rs b/packages/rs-platform-encryption/src/lib.rs index 747c0528d0f..b4785b10095 100644 --- a/packages/rs-platform-encryption/src/lib.rs +++ b/packages/rs-platform-encryption/src/lib.rs @@ -10,6 +10,7 @@ //! - [`account_label`] โ€” `encryptedAccountLabel`. //! - [`contact_info`] โ€” `contactInfo` (`encToUserId` + `privateData`). //! - [`account_reference`] โ€” the masked `accountReference`. +//! - [`private_document_envelope`] โ€” the standard private document envelope (version 1). //! - [`error`] โ€” the shared [`CryptoError`]. //! //! Every public item is re-exported at the crate root, so the API is flat @@ -22,6 +23,7 @@ mod compact_xpub; mod contact_info; mod ecdh; mod error; +mod private_document_envelope; pub use account_label::{decrypt_account_label, encrypt_account_label}; pub use account_reference::{ @@ -38,3 +40,11 @@ pub use contact_info::{ }; pub use ecdh::derive_shared_key_ecdh; pub use error::CryptoError; +pub use private_document_envelope::{ + open_private_document_entry, private_document_outgoing_viewing_key, + recover_sent_private_document_entry, seal_private_document_entry, OpenedPrivateDocumentEntry, + PrivateDocumentAuthMode, PrivateDocumentRecipient, PrivateDocumentSender, + PrivateDocumentTarget, PRIVATE_DOCUMENT_ENVELOPE_BODY_HEADER_LEN, + PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN, PRIVATE_DOCUMENT_ENVELOPE_VERSION, + PRIVATE_DOCUMENT_ENVELOPE_WRAPPER_LEN, +}; diff --git a/packages/rs-platform-encryption/src/private_document_envelope.rs b/packages/rs-platform-encryption/src/private_document_envelope.rs new file mode 100644 index 00000000000..549b51bacb7 --- /dev/null +++ b/packages/rs-platform-encryption/src/private_document_envelope.rs @@ -0,0 +1,941 @@ +//! The standard private document envelope, version 1. +//! +//! A private document type (protocol version 15) stores fixed-size entries that Platform never +//! reads. Clients fill each one with this envelope: a payload encrypted to one recipient key, +//! which the recipient finds by trying to open every entry of the type, and which the sender can +//! recover later from its outgoing viewing key alone. An entry of `entry_size` bytes is +//! +//! ```text +//! cm (32) | epk (33) | body_ct (B + 16) | out_ct (81) B = entry_size - 162 +//! ``` +//! +//! derived from a fresh 32-byte `esk_seed`, the recipient's secp256k1 key `R` and the sender's +//! outgoing viewing key `ovk` (`H` is SHA-256, `ser` a compressed point, `||` concatenation): +//! +//! ```text +//! esk = H("Dash/PrivDoc/v1/esk" || esk_seed), refused if not a valid secret key +//! epk = esk * G +//! key = H("Dash/PrivDoc/v1/key" || ser(esk * R) || ser(epk) || ser(R)) +//! cm = H("Dash/PrivDoc/v1/cm" || key || contract_id || u32le(len(type)) || type || ser(R) +//! || body) +//! body_ct = ChaCha20-Poly1305(key, nonce 0, aad cm, body) +//! ock = H("Dash/PrivDoc/v1/ock" || ovk || ser(epk)) +//! out_ct = ChaCha20-Poly1305(ock, nonce 0, aad cm, ser(R) || esk_seed) +//! ``` +//! +//! `cm` is keyed, so nobody without `key` can confirm a guess about an entry, and commits to +//! `R`, so a ciphertext that would also open under another key is refused there. It commits to +//! the contract and type too, so an entry copied into another type does not open. A zero nonce is +//! safe because each key encrypts once: `esk_seed` must be fresh for every entry built. +//! +//! The body, `B` bytes, is +//! +//! ```text +//! version (1) | auth mode (1) | sender identity id (32) | sender key id (u32le) | auth (65) +//! | recipient identity id (32) | payload length (u16le) | payload | zero padding +//! ``` +//! +//! and the authentication covers +//! +//! ```text +//! m = H("Dash/PrivDoc/v1/auth" || version || auth mode || contract_id || u32le(len(type)) +//! || type || sender identity id || sender key id || recipient identity id +//! || payload length || payload) +//! ``` +//! +//! - anonymous (0): sender fields and `auth` are zeros; +//! - deniable MAC (1): `auth` is +//! `HMAC-SHA256(H("Dash/PrivDoc/v1/mac" || ser(sender key * R)), m)`, then zeros. The +//! recipient learns who sent the entry but could have computed the MAC itself, so it cannot +//! prove it to anyone; +//! - signature (2): `auth` is a recoverable ECDSA signature of `m` by the sender key, in the +//! compact form (header byte `31 + recovery id`, then `r || s`), which anyone can check. + +use chacha20poly1305::aead::{Aead, KeyInit, Payload}; +use chacha20poly1305::{ChaCha20Poly1305, Key, Nonce}; +use hmac::{Hmac, Mac}; +use secp256k1::ecdsa::{RecoverableSignature, RecoveryId}; +use secp256k1::{Message, PublicKey, Scalar, SecretKey}; +use sha2::{Digest, Sha256}; + +use crate::error::CryptoError; + +/// The envelope version this module builds and opens. +pub const PRIVATE_DOCUMENT_ENVELOPE_VERSION: u8 = 1; + +const COMMITMENT_LEN: usize = 32; +const EPHEMERAL_KEY_LEN: usize = 33; +const TAG_LEN: usize = 16; +const SENDER_RECOVERY_PLAINTEXT_LEN: usize = 33 + 32; +const SENDER_RECOVERY_LEN: usize = SENDER_RECOVERY_PLAINTEXT_LEN + TAG_LEN; +const AUTH_LEN: usize = 65; +const MAC_LEN: usize = 32; + +/// The bytes around the encrypted body: the commitment, the ephemeral key, the body's tag and +/// the sender-recovery ciphertext. +pub const PRIVATE_DOCUMENT_ENVELOPE_WRAPPER_LEN: usize = + COMMITMENT_LEN + EPHEMERAL_KEY_LEN + TAG_LEN + SENDER_RECOVERY_LEN; + +/// The bytes of the body before the payload. +pub const PRIVATE_DOCUMENT_ENVELOPE_BODY_HEADER_LEN: usize = 1 + 1 + 32 + 4 + AUTH_LEN + 32 + 2; + +/// Every byte of an entry besides its payload: 299. An entry holds a payload of at most its +/// size minus this. +pub const PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN: usize = + PRIVATE_DOCUMENT_ENVELOPE_WRAPPER_LEN + PRIVATE_DOCUMENT_ENVELOPE_BODY_HEADER_LEN; + +const DOMAIN_ESK: &[u8] = b"Dash/PrivDoc/v1/esk"; +const DOMAIN_KEY: &[u8] = b"Dash/PrivDoc/v1/key"; +const DOMAIN_CM: &[u8] = b"Dash/PrivDoc/v1/cm"; +const DOMAIN_OVK: &[u8] = b"Dash/PrivDoc/v1/ovk"; +const DOMAIN_OCK: &[u8] = b"Dash/PrivDoc/v1/ock"; +const DOMAIN_AUTH: &[u8] = b"Dash/PrivDoc/v1/auth"; +const DOMAIN_MAC: &[u8] = b"Dash/PrivDoc/v1/mac"; + +/// The compact signature header of a compressed key: 27 + 4, plus the recovery id. +const COMPACT_SIGNATURE_HEADER_BASE: u8 = 31; + +/// The private document type an entry belongs to. Both are bound into the commitment, so an +/// entry opens only for the type it was built for. +#[derive(Clone, Copy, Debug)] +pub struct PrivateDocumentTarget<'a> { + pub contract_id: [u8; 32], + pub document_type_name: &'a str, +} + +/// Whom an entry is for: the identity, written in the body so that an entry cannot be replayed +/// to another identity holding the same key, and the key it is encrypted to. For DashPay, the +/// recipient's DashPay decryption key. +#[derive(Clone, Copy, Debug)] +pub struct PrivateDocumentRecipient<'a> { + pub identity_id: [u8; 32], + pub public_key: &'a PublicKey, +} + +/// How an entry tells its recipient who wrote it. +#[derive(Clone, Copy, Debug)] +pub enum PrivateDocumentSender<'a> { + /// Nobody: the recipient learns nothing of the writer. + Anonymous, + /// The sender's identity and key, with a MAC under the static ECDH of that key and the + /// recipient's. The recipient learns who wrote the entry, but could have computed the MAC + /// itself, so it cannot prove that to anyone. DashPay contact requests use this, with the + /// sender's DashPay encryption key. + DeniableMac { + identity_id: [u8; 32], + key_id: u32, + secret_key: &'a SecretKey, + }, + /// The sender's identity and key, with a signature by that key anyone can check. + Signature { + identity_id: [u8; 32], + key_id: u32, + secret_key: &'a SecretKey, + }, +} + +/// The authentication an opened entry carries. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum PrivateDocumentAuthMode { + Anonymous = 0, + DeniableMac = 1, + Signature = 2, +} + +impl PrivateDocumentAuthMode { + fn from_byte(byte: u8) -> Option { + match byte { + 0 => Some(Self::Anonymous), + 1 => Some(Self::DeniableMac), + 2 => Some(Self::Signature), + _ => None, + } + } +} + +/// An entry its recipient opened, or its sender recovered. +/// +/// The sender fields are what the entry claims; [`Self::verify_sender`] checks the claim +/// against the key the sender's identity holds under `sender_key_id`. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct OpenedPrivateDocumentEntry { + /// The entry's commitment: two entries with the same one are copies. + pub commitment: [u8; 32], + /// Which of the keys given to [`open_private_document_entry`] opened it; `None` when the + /// sender recovered it. + pub recipient_key_index: Option, + /// The key the entry is encrypted to. + pub recipient_public_key: PublicKey, + pub recipient_identity_id: [u8; 32], + pub auth_mode: PrivateDocumentAuthMode, + /// Zeros when the entry is anonymous. + pub sender_identity_id: [u8; 32], + /// Zero when the entry is anonymous. + pub sender_key_id: u32, + /// The type's properties in the document property encoding, for the type's schema to + /// decode and validate. + pub payload: Vec, + auth: [u8; AUTH_LEN], + auth_message: [u8; 32], +} + +impl OpenedPrivateDocumentEntry { + /// Checks that the key the entry names wrote it: `sender_public_key` is the key the sender + /// identity holds under `sender_key_id`, as it was when the entry was written (keys are + /// disabled, never removed). A deniable MAC is checked with the recipient's own secret key, + /// the one that opened the entry; a signature needs only the sender's key. + pub fn verify_sender( + &self, + sender_public_key: &PublicKey, + recipient_secret_key: &SecretKey, + ) -> Result<(), CryptoError> { + match self.auth_mode { + PrivateDocumentAuthMode::Anonymous => Err(CryptoError::AnonymousPrivateDocumentSender), + PrivateDocumentAuthMode::DeniableMac => { + let mac_key = mac_key(&shared_point(recipient_secret_key, sender_public_key)?); + let mut mac = as Mac>::new_from_slice(&mac_key) + .expect("HMAC takes a key of any length"); + mac.update(&self.auth_message); + mac.verify_slice(&self.auth[..MAC_LEN]) + .map_err(|_| CryptoError::PrivateDocumentSenderNotAuthenticated) + } + PrivateDocumentAuthMode::Signature => { + let recovery_id = RecoveryId::from_u8_masked( + self.auth[0].wrapping_sub(COMPACT_SIGNATURE_HEADER_BASE), + ); + let signature = RecoverableSignature::from_compact(&self.auth[1..], recovery_id) + .map_err(|_| CryptoError::PrivateDocumentSenderNotAuthenticated)?; + let signer = signature + .recover_ecdsa(Message::from_digest(self.auth_message)) + .map_err(|_| CryptoError::PrivateDocumentSenderNotAuthenticated)?; + if signer == *sender_public_key { + Ok(()) + } else { + Err(CryptoError::PrivateDocumentSenderNotAuthenticated) + } + } + } + } +} + +/// The outgoing viewing key a sender derives from a secret of its wallet: with it, and nothing +/// else, the sender recovers every entry it built from the entries alone. +pub fn private_document_outgoing_viewing_key(wallet_secret: &[u8; 32]) -> [u8; 32] { + hash(&[DOMAIN_OVK, wallet_secret]) +} + +/// Builds an entry of `entry_size` bytes carrying `payload` to `recipient`, for the private +/// document type `target`. +/// +/// `esk_seed` must be 32 fresh random bytes for every entry built, never reused, not even on a +/// retry: the entry's keys are derived from it, and a zero nonce is safe only because each key +/// encrypts once. A seed whose hash is not a valid secret key (a chance of about 2^-128) is +/// refused with `InvalidPrivateDocumentEphemeralSeed`; draw another. +pub fn seal_private_document_entry( + target: &PrivateDocumentTarget, + entry_size: usize, + recipient: &PrivateDocumentRecipient, + sender: &PrivateDocumentSender, + payload: &[u8], + outgoing_viewing_key: &[u8; 32], + esk_seed: &[u8; 32], +) -> Result, CryptoError> { + let capacity = entry_size.saturating_sub(PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN); + let payload_len = u16::try_from(payload.len()) + .ok() + .filter(|_| { + entry_size >= PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN && payload.len() <= capacity + }) + .ok_or(CryptoError::PrivateDocumentPayloadTooLarge { + payload_len: payload.len(), + capacity, + })?; + let body_len = entry_size - PRIVATE_DOCUMENT_ENVELOPE_WRAPPER_LEN; + + let esk = ephemeral_secret_key(esk_seed)?; + let epk = PublicKey::from_secret_key(&esk).serialize(); + let recipient_key = recipient.public_key.serialize(); + let key = entry_key( + &shared_point(&esk, recipient.public_key)?, + &epk, + &recipient_key, + ); + + let (auth_mode, sender_identity_id, sender_key_id) = match sender { + PrivateDocumentSender::Anonymous => (PrivateDocumentAuthMode::Anonymous, [0; 32], 0), + PrivateDocumentSender::DeniableMac { + identity_id, + key_id, + .. + } => (PrivateDocumentAuthMode::DeniableMac, *identity_id, *key_id), + PrivateDocumentSender::Signature { + identity_id, + key_id, + .. + } => (PrivateDocumentAuthMode::Signature, *identity_id, *key_id), + }; + let auth_message = auth_message( + target, + auth_mode, + &sender_identity_id, + sender_key_id, + &recipient.identity_id, + payload, + ); + let mut auth = [0u8; AUTH_LEN]; + match sender { + PrivateDocumentSender::Anonymous => {} + PrivateDocumentSender::DeniableMac { secret_key, .. } => { + let mac_key = mac_key(&shared_point(secret_key, recipient.public_key)?); + let mut mac = as Mac>::new_from_slice(&mac_key) + .expect("HMAC takes a key of any length"); + mac.update(&auth_message); + auth[..MAC_LEN].copy_from_slice(&mac.finalize().into_bytes()); + } + PrivateDocumentSender::Signature { secret_key, .. } => { + let (recovery_id, compact) = RecoverableSignature::sign_ecdsa_recoverable( + Message::from_digest(auth_message), + secret_key, + ) + .serialize_compact(); + auth[0] = COMPACT_SIGNATURE_HEADER_BASE + u8::from(recovery_id); + auth[1..].copy_from_slice(&compact); + } + } + + let mut body = Vec::with_capacity(body_len); + body.push(PRIVATE_DOCUMENT_ENVELOPE_VERSION); + body.push(auth_mode as u8); + body.extend_from_slice(&sender_identity_id); + body.extend_from_slice(&sender_key_id.to_le_bytes()); + body.extend_from_slice(&auth); + body.extend_from_slice(&recipient.identity_id); + body.extend_from_slice(&payload_len.to_le_bytes()); + body.extend_from_slice(payload); + body.resize(body_len, 0); + + let commitment = commitment(&key, target, &recipient_key, &body); + let body_ct = encrypt(&key, &commitment, &body)?; + let mut sender_recovery = Vec::with_capacity(SENDER_RECOVERY_PLAINTEXT_LEN); + sender_recovery.extend_from_slice(&recipient_key); + sender_recovery.extend_from_slice(esk_seed); + let out_ct = encrypt( + &outgoing_cipher_key(outgoing_viewing_key, &epk), + &commitment, + &sender_recovery, + )?; + + let mut entry = Vec::with_capacity(entry_size); + entry.extend_from_slice(&commitment); + entry.extend_from_slice(&epk); + entry.extend_from_slice(&body_ct); + entry.extend_from_slice(&out_ct); + debug_assert_eq!(entry.len(), entry_size); + Ok(entry) +} + +/// Opens `entry` of the private document type `target` with the first of +/// `recipient_secret_keys` it is encrypted to, for the identity `recipient_identity_id`. +/// +/// `Ok(None)` when it is for none of the keys, the case of nearly every entry a wallet scans: +/// a key whose decryption fails, or whose commitment does not match, is passed over for the +/// next. An entry that opens but is malformed, or names another recipient identity, is refused +/// with an error. The sender is not yet checked: see +/// [`OpenedPrivateDocumentEntry::verify_sender`]. +pub fn open_private_document_entry( + entry: &[u8], + target: &PrivateDocumentTarget, + recipient_identity_id: &[u8; 32], + recipient_secret_keys: &[SecretKey], +) -> Result, CryptoError> { + let parts = EntryParts::split(entry)?; + let Ok(epk) = PublicKey::from_slice(parts.epk) else { + // No key opens an entry whose ephemeral key is not a point. + return Ok(None); + }; + for (index, secret_key) in recipient_secret_keys.iter().enumerate() { + let recipient_public_key = PublicKey::from_secret_key(secret_key); + let recipient_key = recipient_public_key.serialize(); + let key = entry_key(&shared_point(secret_key, &epk)?, parts.epk, &recipient_key); + let Ok(body) = decrypt(&key, parts.commitment, parts.body_ct) else { + continue; + }; + if commitment(&key, target, &recipient_key, &body) != *parts.commitment { + continue; + } + let opened = parse_body( + &body, + target, + *parts.commitment, + recipient_public_key, + Some(index), + )?; + if opened.recipient_identity_id != *recipient_identity_id { + return Err(CryptoError::WrongPrivateDocumentRecipient); + } + return Ok(Some(opened)); + } + Ok(None) +} + +/// Recovers `entry` of the private document type `target` that the holder of +/// `outgoing_viewing_key` built, as after a restore from seed: `Ok(None)` when it built another +/// sender's entry. An entry whose sender recovery opens but whose body does not is refused. +pub fn recover_sent_private_document_entry( + entry: &[u8], + target: &PrivateDocumentTarget, + outgoing_viewing_key: &[u8; 32], +) -> Result, CryptoError> { + let parts = EntryParts::split(entry)?; + let Ok(sender_recovery) = decrypt( + &outgoing_cipher_key(outgoing_viewing_key, parts.epk), + parts.commitment, + parts.out_ct, + ) else { + return Ok(None); + }; + let malformed = || CryptoError::MalformedPrivateDocumentEntry("sender recovery"); + let recipient_public_key = + PublicKey::from_slice(&sender_recovery[..EPHEMERAL_KEY_LEN]).map_err(|_| malformed())?; + let esk_seed: [u8; 32] = sender_recovery[EPHEMERAL_KEY_LEN..] + .try_into() + .map_err(|_| malformed())?; + let esk = ephemeral_secret_key(&esk_seed).map_err(|_| malformed())?; + if PublicKey::from_secret_key(&esk).serialize() != *parts.epk { + return Err(malformed()); + } + let recipient_key = recipient_public_key.serialize(); + let key = entry_key( + &shared_point(&esk, &recipient_public_key)?, + parts.epk, + &recipient_key, + ); + let body = decrypt(&key, parts.commitment, parts.body_ct).map_err(|_| malformed())?; + if commitment(&key, target, &recipient_key, &body) != *parts.commitment { + return Err(malformed()); + } + parse_body(&body, target, *parts.commitment, recipient_public_key, None).map(Some) +} + +/// An entry cut into its four parts. +struct EntryParts<'a> { + commitment: &'a [u8; 32], + epk: &'a [u8; 33], + body_ct: &'a [u8], + out_ct: &'a [u8], +} + +impl<'a> EntryParts<'a> { + fn split(entry: &'a [u8]) -> Result { + if entry.len() < PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN { + return Err(CryptoError::InvalidPrivateDocumentEntryLength(entry.len())); + } + let (commitment, rest) = entry.split_at(COMMITMENT_LEN); + let (epk, rest) = rest.split_at(EPHEMERAL_KEY_LEN); + let (body_ct, out_ct) = rest.split_at(rest.len() - SENDER_RECOVERY_LEN); + Ok(Self { + commitment: commitment.try_into().expect("32 bytes"), + epk: epk.try_into().expect("33 bytes"), + body_ct, + out_ct, + }) + } +} + +/// Reads a decrypted body, refusing one no sender of this version writes. +fn parse_body( + body: &[u8], + target: &PrivateDocumentTarget, + commitment: [u8; 32], + recipient_public_key: PublicKey, + recipient_key_index: Option, +) -> Result { + let malformed = CryptoError::MalformedPrivateDocumentEntry; + if body.len() < PRIVATE_DOCUMENT_ENVELOPE_BODY_HEADER_LEN { + return Err(malformed("body shorter than its header")); + } + if body[0] != PRIVATE_DOCUMENT_ENVELOPE_VERSION { + return Err(CryptoError::UnsupportedPrivateDocumentEnvelopeVersion( + body[0], + )); + } + let auth_mode = + PrivateDocumentAuthMode::from_byte(body[1]).ok_or(malformed("unknown auth mode"))?; + let sender_identity_id: [u8; 32] = body[2..34].try_into().expect("32 bytes"); + let sender_key_id = u32::from_le_bytes(body[34..38].try_into().expect("4 bytes")); + let auth: [u8; AUTH_LEN] = body[38..103].try_into().expect("65 bytes"); + let recipient_identity_id: [u8; 32] = body[103..135].try_into().expect("32 bytes"); + let payload_len = u16::from_le_bytes(body[135..137].try_into().expect("2 bytes")) as usize; + let rest = &body[PRIVATE_DOCUMENT_ENVELOPE_BODY_HEADER_LEN..]; + if payload_len > rest.len() { + return Err(malformed("payload longer than the body")); + } + let (payload, padding) = rest.split_at(payload_len); + if padding.iter().any(|byte| *byte != 0) { + return Err(malformed("padding is not zeros")); + } + let well_formed_auth = match auth_mode { + PrivateDocumentAuthMode::Anonymous => { + sender_identity_id == [0; 32] && sender_key_id == 0 && auth == [0; AUTH_LEN] + } + PrivateDocumentAuthMode::DeniableMac => auth[MAC_LEN..].iter().all(|byte| *byte == 0), + PrivateDocumentAuthMode::Signature => { + (COMPACT_SIGNATURE_HEADER_BASE..COMPACT_SIGNATURE_HEADER_BASE + 4).contains(&auth[0]) + } + }; + if !well_formed_auth { + return Err(malformed("sender fields do not match the auth mode")); + } + let auth_message = auth_message( + target, + auth_mode, + &sender_identity_id, + sender_key_id, + &recipient_identity_id, + payload, + ); + Ok(OpenedPrivateDocumentEntry { + commitment, + recipient_key_index, + recipient_public_key, + recipient_identity_id, + auth_mode, + sender_identity_id, + sender_key_id, + payload: payload.to_vec(), + auth, + auth_message, + }) +} + +fn hash(parts: &[&[u8]]) -> [u8; 32] { + let mut hasher = Sha256::new(); + for part in parts { + hasher.update(part); + } + hasher.finalize().into() +} + +fn type_name_length(target: &PrivateDocumentTarget) -> [u8; 4] { + (target.document_type_name.len() as u32).to_le_bytes() +} + +fn ephemeral_secret_key(esk_seed: &[u8; 32]) -> Result { + SecretKey::from_secret_bytes(hash(&[DOMAIN_ESK, esk_seed])) + .map_err(|_| CryptoError::InvalidPrivateDocumentEphemeralSeed) +} + +/// `secret_key * public_key`, compressed. +fn shared_point(secret_key: &SecretKey, public_key: &PublicKey) -> Result<[u8; 33], CryptoError> { + let scalar = Scalar::from_be_bytes(secret_key.to_secret_bytes()) + .map_err(|_| CryptoError::MalformedPrivateDocumentEntry("secret key out of range"))?; + public_key + .mul_tweak(&scalar) + .map(|point| point.serialize()) + .map_err(|_| CryptoError::MalformedPrivateDocumentEntry("shared point at infinity")) +} + +fn entry_key(shared_point: &[u8; 33], epk: &[u8; 33], recipient_key: &[u8; 33]) -> [u8; 32] { + hash(&[DOMAIN_KEY, shared_point, epk, recipient_key]) +} + +fn commitment( + key: &[u8; 32], + target: &PrivateDocumentTarget, + recipient_key: &[u8; 33], + body: &[u8], +) -> [u8; 32] { + hash(&[ + DOMAIN_CM, + key, + &target.contract_id, + &type_name_length(target), + target.document_type_name.as_bytes(), + recipient_key, + body, + ]) +} + +fn outgoing_cipher_key(outgoing_viewing_key: &[u8; 32], epk: &[u8; 33]) -> [u8; 32] { + hash(&[DOMAIN_OCK, outgoing_viewing_key, epk]) +} + +fn mac_key(shared_point: &[u8; 33]) -> [u8; 32] { + hash(&[DOMAIN_MAC, shared_point]) +} + +fn auth_message( + target: &PrivateDocumentTarget, + auth_mode: PrivateDocumentAuthMode, + sender_identity_id: &[u8; 32], + sender_key_id: u32, + recipient_identity_id: &[u8; 32], + payload: &[u8], +) -> [u8; 32] { + hash(&[ + DOMAIN_AUTH, + &[PRIVATE_DOCUMENT_ENVELOPE_VERSION, auth_mode as u8], + &target.contract_id, + &type_name_length(target), + target.document_type_name.as_bytes(), + sender_identity_id, + &sender_key_id.to_le_bytes(), + recipient_identity_id, + &(payload.len() as u16).to_le_bytes(), + payload, + ]) +} + +fn encrypt(key: &[u8; 32], aad: &[u8; 32], plaintext: &[u8]) -> Result, CryptoError> { + ChaCha20Poly1305::new(Key::from_slice(key)) + .encrypt( + Nonce::from_slice(&[0; 12]), + Payload { + msg: plaintext, + aad, + }, + ) + .map_err(|_| CryptoError::MalformedPrivateDocumentEntry("encryption failed")) +} + +fn decrypt(key: &[u8; 32], aad: &[u8; 32], ciphertext: &[u8]) -> Result, CryptoError> { + ChaCha20Poly1305::new(Key::from_slice(key)) + .decrypt( + Nonce::from_slice(&[0; 12]), + Payload { + msg: ciphertext, + aad, + }, + ) + .map_err(|_| CryptoError::DecryptionFailed) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// DashPay's `privateContactRequest`: 589-byte entries, whose largest payload is 290 bytes. + const ENTRY_SIZE: usize = 589; + const LARGEST_PAYLOAD: usize = 290; + const SENDER_IDENTITY: [u8; 32] = [0xA0; 32]; + const RECIPIENT_IDENTITY: [u8; 32] = [0xB0; 32]; + + fn target() -> PrivateDocumentTarget<'static> { + PrivateDocumentTarget { + contract_id: [7; 32], + document_type_name: "privateContactRequest", + } + } + + fn secret_key(byte: u8) -> SecretKey { + SecretKey::from_secret_bytes([byte; 32]).expect("a valid secret key") + } + + fn public_key(byte: u8) -> PublicKey { + PublicKey::from_secret_key(&secret_key(byte)) + } + + fn payload() -> Vec { + (0..LARGEST_PAYLOAD).map(|i| i as u8).collect() + } + + fn outgoing_viewing_key() -> [u8; 32] { + private_document_outgoing_viewing_key(&[0x0F; 32]) + } + + /// An entry to the recipient key `secret_key(2)` from `sender`, built from `esk_seed`. + fn seal(sender: &PrivateDocumentSender, esk_seed: u8) -> Vec { + seal_private_document_entry( + &target(), + ENTRY_SIZE, + &PrivateDocumentRecipient { + identity_id: RECIPIENT_IDENTITY, + public_key: &public_key(2), + }, + sender, + &payload(), + &outgoing_viewing_key(), + &[esk_seed; 32], + ) + .expect("the payload fits") + } + + fn open(entry: &[u8], keys: &[SecretKey]) -> Option { + open_private_document_entry(entry, &target(), &RECIPIENT_IDENTITY, keys) + .expect("the entry is well formed") + } + + fn deniable_mac_sender(secret_key: &SecretKey) -> PrivateDocumentSender<'_> { + PrivateDocumentSender::DeniableMac { + identity_id: SENDER_IDENTITY, + key_id: 4, + secret_key, + } + } + + /// The recipient opens an entry with whichever of its keys it is encrypted to, reads the + /// payload and the sender it claims, and checks the deniable MAC against the sender's key. + #[test] + fn should_open_an_entry_with_its_key_and_check_a_deniable_mac() { + let sender_key = secret_key(1); + let entry = seal(&deniable_mac_sender(&sender_key), 9); + assert_eq!(entry.len(), ENTRY_SIZE); + + let opened = + open(&entry, &[secret_key(3), secret_key(2)]).expect("the second key opens it"); + assert_eq!(opened.recipient_key_index, Some(1)); + assert_eq!(opened.recipient_public_key, public_key(2)); + assert_eq!(opened.recipient_identity_id, RECIPIENT_IDENTITY); + assert_eq!(opened.auth_mode, PrivateDocumentAuthMode::DeniableMac); + assert_eq!(opened.sender_identity_id, SENDER_IDENTITY); + assert_eq!(opened.sender_key_id, 4); + assert_eq!(opened.payload, payload()); + + opened + .verify_sender(&public_key(1), &secret_key(2)) + .expect("the sender's key wrote the MAC"); + assert!(matches!( + opened.verify_sender(&public_key(5), &secret_key(2)), + Err(CryptoError::PrivateDocumentSenderNotAuthenticated) + )); + } + + /// A signed entry is checked against the sender's key alone. + #[test] + fn should_check_a_signature_against_the_sender_key() { + let sender_key = secret_key(1); + let entry = seal( + &PrivateDocumentSender::Signature { + identity_id: SENDER_IDENTITY, + key_id: 4, + secret_key: &sender_key, + }, + 9, + ); + let opened = open(&entry, &[secret_key(2)]).expect("it opens"); + assert_eq!(opened.auth_mode, PrivateDocumentAuthMode::Signature); + opened + .verify_sender(&public_key(1), &secret_key(2)) + .expect("the sender's key signed it"); + assert!(matches!( + opened.verify_sender(&public_key(5), &secret_key(2)), + Err(CryptoError::PrivateDocumentSenderNotAuthenticated) + )); + } + + /// An anonymous entry names no sender, and there is nothing to check. + #[test] + fn should_open_an_anonymous_entry_without_a_sender() { + let entry = seal(&PrivateDocumentSender::Anonymous, 9); + let opened = open(&entry, &[secret_key(2)]).expect("it opens"); + assert_eq!(opened.auth_mode, PrivateDocumentAuthMode::Anonymous); + assert_eq!(opened.sender_identity_id, [0; 32]); + assert_eq!(opened.sender_key_id, 0); + assert_eq!(opened.payload, payload()); + assert!(matches!( + opened.verify_sender(&public_key(1), &secret_key(2)), + Err(CryptoError::AnonymousPrivateDocumentSender) + )); + } + + /// Nearly every entry a wallet scans is for someone else: it is passed over, not refused. + #[test] + fn should_pass_over_an_entry_for_other_keys() { + let sender_key = secret_key(1); + let entry = seal(&deniable_mac_sender(&sender_key), 9); + assert_eq!(open(&entry, &[secret_key(3), secret_key(1)]), None); + assert_eq!(open(&entry, &[]), None); + } + + /// A byte changed in the commitment, the ephemeral key or the body, or the entry read as one + /// of another contract or type, opens for nobody. + #[test] + fn should_not_open_an_entry_changed_or_moved_to_another_type() { + let sender_key = secret_key(1); + let entry = seal(&deniable_mac_sender(&sender_key), 9); + for position in [0, 31, 33, 64, 65, 300, ENTRY_SIZE - 82] { + let mut changed = entry.clone(); + changed[position] ^= 1; + assert_eq!(open(&changed, &[secret_key(2)]), None, "byte {position}"); + } + for moved in [ + PrivateDocumentTarget { + contract_id: [8; 32], + ..target() + }, + PrivateDocumentTarget { + document_type_name: "contactRequest", + ..target() + }, + ] { + assert_eq!( + open_private_document_entry(&entry, &moved, &RECIPIENT_IDENTITY, &[secret_key(2)]) + .expect("well formed"), + None + ); + } + } + + /// An entry that opens under the identity's key but names another identity is a replay, + /// and is refused. + #[test] + fn should_refuse_an_entry_naming_another_recipient_identity() { + let sender_key = secret_key(1); + let entry = seal(&deniable_mac_sender(&sender_key), 9); + assert!(matches!( + open_private_document_entry(&entry, &target(), &[0xC0; 32], &[secret_key(2)]), + Err(CryptoError::WrongPrivateDocumentRecipient) + )); + } + + /// The sender recovers its own entry, recipient and payload included, from its outgoing + /// viewing key alone; another sender's key recovers nothing, and nor does a changed + /// sender-recovery ciphertext. + #[test] + fn should_recover_a_sent_entry_with_the_outgoing_viewing_key() { + let sender_key = secret_key(1); + let entry = seal(&deniable_mac_sender(&sender_key), 9); + let recovered = + recover_sent_private_document_entry(&entry, &target(), &outgoing_viewing_key()) + .expect("well formed") + .expect("the sender built it"); + assert_eq!(recovered.recipient_key_index, None); + assert_eq!(recovered.recipient_public_key, public_key(2)); + assert_eq!(recovered.payload, payload()); + assert_eq!( + recovered, + OpenedPrivateDocumentEntry { + recipient_key_index: None, + ..open(&entry, &[secret_key(2)]).expect("it opens") + } + ); + + let other_sender = private_document_outgoing_viewing_key(&[0x1F; 32]); + assert_eq!( + recover_sent_private_document_entry(&entry, &target(), &other_sender) + .expect("well formed"), + None + ); + let mut changed = entry.clone(); + changed[ENTRY_SIZE - 1] ^= 1; + assert_eq!( + recover_sent_private_document_entry(&changed, &target(), &outgoing_viewing_key()) + .expect("well formed"), + None + ); + } + + /// An entry holds a payload of at most its size minus 299 bytes. + #[test] + fn should_refuse_a_payload_the_entry_cannot_hold() { + assert_eq!(PRIVATE_DOCUMENT_ENVELOPE_WRAPPER_LEN, 162); + assert_eq!(PRIVATE_DOCUMENT_ENVELOPE_BODY_HEADER_LEN, 137); + assert_eq!(PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN, 299); + for (entry_size, payload_len, capacity) in [ + (ENTRY_SIZE, LARGEST_PAYLOAD + 1, LARGEST_PAYLOAD), + (298, 0, 0), + ] { + assert!( + matches!( + seal_private_document_entry( + &target(), + entry_size, + &PrivateDocumentRecipient { + identity_id: RECIPIENT_IDENTITY, + public_key: &public_key(2), + }, + &PrivateDocumentSender::Anonymous, + &vec![1; payload_len], + &outgoing_viewing_key(), + &[9; 32], + ), + Err(CryptoError::PrivateDocumentPayloadTooLarge { payload_len: refused, capacity: held }) + if refused == payload_len && held == capacity + ), + "{payload_len} bytes in {entry_size}" + ); + } + assert!(matches!( + open_private_document_entry(&[0; 298], &target(), &RECIPIENT_IDENTITY, &[]), + Err(CryptoError::InvalidPrivateDocumentEntryLength(298)) + )); + } + + /// A body no sender of this version writes is refused once it decrypts: another version, + /// an unknown auth mode, a payload longer than the body, padding that is not zeros, and + /// sender fields an anonymous entry does not carry. + #[test] + fn should_refuse_a_body_no_sender_writes() { + let well_formed = || { + let mut body = vec![0u8; ENTRY_SIZE - PRIVATE_DOCUMENT_ENVELOPE_WRAPPER_LEN]; + body[0] = PRIVATE_DOCUMENT_ENVELOPE_VERSION; + body[135..137].copy_from_slice(&3u16.to_le_bytes()); + body + }; + let parse = |body: &[u8]| parse_body(body, &target(), [0; 32], public_key(2), Some(0)); + parse(&well_formed()).expect("an anonymous body of 3 zero bytes"); + + let mut other_version = well_formed(); + other_version[0] = 2; + assert!(matches!( + parse(&other_version), + Err(CryptoError::UnsupportedPrivateDocumentEnvelopeVersion(2)) + )); + for (position, value) in [ + (1, 3u8), // auth mode + (136, 2), // a payload length over the body + (ENTRY_SIZE - 163, 1), // the last padding byte + (2, 1), // a sender identity on an anonymous entry + (40, 1), // an auth on an anonymous entry + ] { + let mut body = well_formed(); + body[position] = value; + assert!( + matches!( + parse(&body), + Err(CryptoError::MalformedPrivateDocumentEntry(_)) + ), + "byte {position}" + ); + } + } + + /// The same inputs build the same entry, byte for byte, in every mode; another seed builds + /// an unlinkable one. The hashes pin version 1 of the format. + #[test] + fn should_build_the_same_entry_from_the_same_inputs() { + let sender_key = secret_key(1); + let senders = [ + PrivateDocumentSender::Anonymous, + deniable_mac_sender(&sender_key), + PrivateDocumentSender::Signature { + identity_id: SENDER_IDENTITY, + key_id: 4, + secret_key: &sender_key, + }, + ]; + let pinned: Vec = senders + .iter() + .map(|sender| { + let entry = seal(sender, 9); + assert_eq!(entry, seal(sender, 9)); + let other = seal(sender, 10); + assert_ne!(entry[..COMMITMENT_LEN], other[..COMMITMENT_LEN]); + assert_ne!(entry[COMMITMENT_LEN..65], other[COMMITMENT_LEN..65]); + hex(&hash(&[&entry])) + }) + .collect(); + assert_eq!( + pinned, + [ + "abb644128f3e73aade8b6210573fba942709e7e44eaeffef92dc02d5187f37d3", + "bedf5084aca776ae520e1395e4a4f92628f4589f04b244630acc890649f74a82", + "a1054055987e953aeeb76deb9998db79eebe3e798a7296eadeb90575bc6e0e56", + ] + ); + } + + fn hex(bytes: &[u8]) -> String { + bytes.iter().map(|byte| format!("{byte:02x}")).collect() + } +} diff --git a/packages/rs-sdk/src/platform.rs b/packages/rs-sdk/src/platform.rs index 0f3b7a88d57..06d5dd53e4e 100644 --- a/packages/rs-sdk/src/platform.rs +++ b/packages/rs-sdk/src/platform.rs @@ -27,6 +27,8 @@ pub mod identities_contract_keys_query; pub mod identity_keys_remaining_budgets; pub mod moderation_charters; pub mod private_document_entries; +#[cfg(test)] +mod private_document_envelope_tests; pub mod query; pub mod query_settings; #[cfg(feature = "shielded")] diff --git a/packages/rs-sdk/src/platform/private_document_envelope_tests.rs b/packages/rs-sdk/src/platform/private_document_envelope_tests.rs new file mode 100644 index 00000000000..bac232c011e --- /dev/null +++ b/packages/rs-sdk/src/platform/private_document_envelope_tests.rs @@ -0,0 +1,159 @@ +//! The private document envelope (`platform-encryption`) and a private type's payload (dpp) fit +//! together: both count the envelope's bytes alike, and a type whose entries take its minimum +//! size carries its largest payload, sealed and opened, in exactly one entry. + +use dpp::data_contract::accessors::v0::DataContractV0Getters; +use dpp::data_contract::conversion::value::v0::DataContractValueConversionMethodsV0; +use dpp::data_contract::document_type::accessors::DocumentTypeV2Getters; +use dpp::data_contract::document_type::{ + decode_private_document_payload, encode_private_document_payload, + minimum_private_document_entry_size, PRIVATE_DOCUMENT_ENVELOPE_V1_BODY_HEADER_BYTES, + PRIVATE_DOCUMENT_ENVELOPE_V1_OVERHEAD_BYTES, PRIVATE_DOCUMENT_ENVELOPE_V1_WRAPPER_BYTES, +}; +use dpp::data_contract::DataContract; +use dpp::platform_value::string_encoding::Encoding; +use dpp::platform_value::{platform_value, Identifier, Value}; +use dpp::secp256k1::{PublicKey, SecretKey}; +use dpp::version::PlatformVersion; +use platform_encryption::{ + open_private_document_entry, private_document_outgoing_viewing_key, + seal_private_document_entry, PrivateDocumentRecipient, PrivateDocumentSender, + PrivateDocumentTarget, PRIVATE_DOCUMENT_ENVELOPE_BODY_HEADER_LEN, + PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN, PRIVATE_DOCUMENT_ENVELOPE_WRAPPER_LEN, +}; +use std::collections::BTreeMap; + +/// A contract with the private type `request`, shaped as DashPay's `privateContactRequest`, of +/// `entry_size`-byte entries. Unlike DashPay, it keeps sized integer types on, so +/// `accountReference` is a u32: its largest payload is 286 bytes, not DashPay's 290. +fn contract(entry_size: u32) -> DataContract { + let id = Identifier::from([7; 32]).to_string(Encoding::Base58); + let owner_id = Identifier::from([8; 32]).to_string(Encoding::Base58); + DataContract::from_value( + platform_value!({ + "$formatVersion": "1", + "id": id, + "ownerId": owner_id, + "version": 1, + "documentSchemas": { + "request": { + "type": "object", + "private": { "entrySize": entry_size }, + "documentsMutable": false, + "canBeDeleted": false, + "properties": { + "accountReference": { + "type": "integer", "minimum": 0, "maximum": 4294967295u64, + "position": 0 + }, + "extendedPublicKey": { + "type": "array", "byteArray": true, + "minItems": 69, "maxItems": 69, "position": 1 + }, + "accountLabel": { "type": "string", "maxBytes": 63, "position": 2 }, + "autoAcceptProof": { + "type": "array", "byteArray": true, + "minItems": 38, "maxItems": 102, "position": 3 + }, + "shieldedAddress": { + "type": "array", "byteArray": true, + "minItems": 43, "maxItems": 43, "position": 4 + } + }, + "required": ["accountReference", "extendedPublicKey"], + "additionalProperties": false + } + } + }), + true, + PlatformVersion::latest(), + ) + .expect("the contract registers") +} + +#[test] +fn should_count_the_envelope_bytes_alike_in_both_crates() { + assert_eq!( + PRIVATE_DOCUMENT_ENVELOPE_WRAPPER_LEN as u32, + PRIVATE_DOCUMENT_ENVELOPE_V1_WRAPPER_BYTES + ); + assert_eq!( + PRIVATE_DOCUMENT_ENVELOPE_BODY_HEADER_LEN as u32, + PRIVATE_DOCUMENT_ENVELOPE_V1_BODY_HEADER_BYTES + ); + assert_eq!( + PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN as u32, + PRIVATE_DOCUMENT_ENVELOPE_V1_OVERHEAD_BYTES + ); +} + +/// The largest payload of a type whose entries take its minimum size is sealed into one entry +/// of exactly that size, opens for its recipient with its sender checked, and decodes back. +#[test] +fn should_carry_the_largest_payload_in_an_entry_of_the_minimum_size() { + let platform_version = PlatformVersion::latest(); + let minimum = minimum_private_document_entry_size( + contract(4096) + .document_type_for_name("request") + .expect("the type"), + ) + .expect("bounded"); + assert_eq!(minimum, 286 + 299); + let contract = contract(minimum); + let request = contract + .document_type_for_name("request") + .expect("the type"); + let entry_size = request.private_document().expect("private").entry_size() as usize; + + let properties = BTreeMap::from([ + ("accountReference".to_string(), Value::U32(u32::MAX)), + ("extendedPublicKey".to_string(), Value::Bytes(vec![1; 69])), + ("accountLabel".to_string(), Value::Text("a".repeat(63))), + ("autoAcceptProof".to_string(), Value::Bytes(vec![2; 102])), + ("shieldedAddress".to_string(), Value::Bytes(vec![3; 43])), + ]); + let payload = encode_private_document_payload(&contract, request, properties).expect("encodes"); + assert_eq!( + payload.len(), + entry_size - PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN + ); + + let sender_key = SecretKey::from_secret_bytes([1; 32]).expect("a key"); + let recipient_key = SecretKey::from_secret_bytes([2; 32]).expect("a key"); + let target = PrivateDocumentTarget { + contract_id: contract.id().to_buffer(), + document_type_name: "request", + }; + let entry = seal_private_document_entry( + &target, + entry_size, + &PrivateDocumentRecipient { + identity_id: [0xB0; 32], + public_key: &PublicKey::from_secret_key(&recipient_key), + }, + &PrivateDocumentSender::DeniableMac { + identity_id: [0xA0; 32], + key_id: 4, + secret_key: &sender_key, + }, + &payload, + &private_document_outgoing_viewing_key(&[0x0F; 32]), + &[9; 32], + ) + .expect("the largest payload fits"); + assert_eq!(entry.len(), entry_size); + + let opened = open_private_document_entry(&entry, &target, &[0xB0; 32], &[recipient_key]) + .expect("well formed") + .expect("for the recipient"); + opened + .verify_sender(&PublicKey::from_secret_key(&sender_key), &recipient_key) + .expect("from the sender"); + let decoded = + decode_private_document_payload(&contract, request, &opened.payload, platform_version) + .expect("decodes"); + assert_eq!( + decoded.get("accountLabel"), + Some(&Value::Text("a".repeat(63))) + ); +} From e3e77076cb1006975724358ffe50ba54fac8ce91 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Sun, 8 Nov 2026 02:52:56 +0700 Subject: [PATCH 04/11] fix(sdk): check private entry sizes on native wallet contract updates too - platform-wallet's update_data_contract_with_signer runs ensure_private_document_entries_fit against the contract it already fetched, before fetching the nonce, so a native update adding an undersized private type is refused as a wasm-sdk update and a create are. - The largest payload is documented as an upper bound read from the property types alone: a schema's enum, or a maxProperties keeping optional properties apart, can only lower the real one and is not counted. The book says so too. - rs-sdk tests ensure_private_document_entries_fit_on_update with the mock SDK: an unchanged undersized type passes against the fetched contract, a changed one is refused, every type is checked when Platform holds no such contract, a failed fetch stops the update, and a contract with no private type fetches nothing. Co-Authored-By: Claude Opus 5.5 --- book/src/contract-keywords.md | 2 +- .../document_type/private_document.rs | 22 +++-- .../src/wallet/identity/network/contract.rs | 10 ++- .../src/platform/transition/put_contract.rs | 84 +++++++++++++++++++ 4 files changed, 109 insertions(+), 9 deletions(-) diff --git a/book/src/contract-keywords.md b/book/src/contract-keywords.md index d25620aee1d..1d70ac185fd 100644 --- a/book/src/contract-keywords.md +++ b/book/src/contract-keywords.md @@ -146,7 +146,7 @@ Every key a contract can write, grouped by where it goes. **Since** is the proto | `rangeCountable`, `rangeSummable`, `rangeAverageable` | boolean | Provable counts, sums or averages over ranges of document ids. | 12 | [Document type range keys](contract-keywords/aggregates.md#document-type-rangecountable-rangesummable-rangeaverageable) | | `indexOnly` | boolean | Documents are never stored whole: the index entries are the rows. | 14 | [indexOnly](contract-keywords/index-only.md#indexonly) ยท [internals](drive/index-only-document-types.md) | | `entryPayload` | array of 1 to 16 names | On an index-only type, properties carried in each entry's value instead of a key. | 14 | [entryPayload](contract-keywords/index-only.md#entrypayload) | -| `private` | object: `entrySize`, 1 to 4096 | A private type: its documents are encrypted entries of `entrySize` bytes, which the chain never reads. Its `properties` describe the plaintext. It declares only `type`, `properties`, `required`, `additionalProperties`, `minProperties`, `maxProperties`, `dependentRequired`, `$comment`, `description`, the two bounded key keys, and `documentsMutable`, `canBeDeleted` and `documentsKeepHistory` as `false`, each at most once; neither its properties nor `required` nor `dependentRequired` name a system field, no property at any depth declares `refersTo`, `distinctFrom`, `generatedFrom`, `encryptedFor` or `requiredSince`, and the contract's elected moderators may not moderate it. No reference, `countOf` or `sumOf` may name it, an update cannot change it, and a Batch refuses every document transition on it (`DocumentTypePrivateError`, 10425). Entries are appended only by `PrivateDocumentCreateFromShieldedPool` (type 29), from 1 to 16 distinct entries of exactly `entrySize` bytes, paid from the credit shielded pool. The chain does not compare `entrySize` with the properties; the SDK refuses to register a private type whose `entrySize` is below its largest payload plus the private document envelope's 299 bytes, or whose properties are not all bounded (`minimum_private_document_entry_size` in dpp). | 15 | | +| `private` | object: `entrySize`, 1 to 4096 | A private type: its documents are encrypted entries of `entrySize` bytes, which the chain never reads. Its `properties` describe the plaintext. It declares only `type`, `properties`, `required`, `additionalProperties`, `minProperties`, `maxProperties`, `dependentRequired`, `$comment`, `description`, the two bounded key keys, and `documentsMutable`, `canBeDeleted` and `documentsKeepHistory` as `false`, each at most once; neither its properties nor `required` nor `dependentRequired` name a system field, no property at any depth declares `refersTo`, `distinctFrom`, `generatedFrom`, `encryptedFor` or `requiredSince`, and the contract's elected moderators may not moderate it. No reference, `countOf` or `sumOf` may name it, an update cannot change it, and a Batch refuses every document transition on it (`DocumentTypePrivateError`, 10425). Entries are appended only by `PrivateDocumentCreateFromShieldedPool` (type 29), from 1 to 16 distinct entries of exactly `entrySize` bytes, paid from the credit shielded pool. The chain does not compare `entrySize` with the properties; the SDK refuses to register a private type whose `entrySize` is below its largest payload plus the private document envelope's 299 bytes, or whose properties are not all bounded (`minimum_private_document_entry_size` in dpp). The largest payload is read from the property types alone: an `enum` or a `maxProperties` that would make it smaller is not counted. | 15 | | ### Property diff --git a/packages/rs-dpp/src/data_contract/document_type/private_document.rs b/packages/rs-dpp/src/data_contract/document_type/private_document.rs index 3342f427101..76fc87dec72 100644 --- a/packages/rs-dpp/src/data_contract/document_type/private_document.rs +++ b/packages/rs-dpp/src/data_contract/document_type/private_document.rs @@ -80,10 +80,17 @@ pub const PRIVATE_DOCUMENT_ENVELOPE_V1_BODY_HEADER_BYTES: u32 = 1 + 1 + 32 + 4 + pub const PRIVATE_DOCUMENT_ENVELOPE_V1_OVERHEAD_BYTES: u32 = PRIVATE_DOCUMENT_ENVELOPE_V1_WRAPPER_BYTES + PRIVATE_DOCUMENT_ENVELOPE_V1_BODY_HEADER_BYTES; -/// The most bytes a payload of `document_type` takes: its properties in the document property -/// encoding, as a document writes them after its system fields, each one present at its largest -/// and one written with a presence byte (optional or transient) counting that byte. A private -/// type's entries carry their plaintext in this encoding. +/// The most bytes a payload of `document_type` takes as its property types bound it: its +/// properties in the document property encoding, as a document writes them after its system +/// fields, each one present at its largest and one written with a presence byte (optional or +/// transient) counting that byte. A private type's entries carry their plaintext in this +/// encoding. +/// +/// It is an upper bound, read from the property types alone: a schema's `enum`, or a +/// `maxProperties` keeping some optional properties from appearing together, can only make the +/// real largest payload smaller, and is not counted. A type sized between the two is refused by +/// [`validate_private_document_entry_size`] although every payload its schema admits would fit; +/// size it to this bound, or bound the property types themselves. /// /// Refused with `UnboundedPrivateDocumentProperty` when a property sets no largest value, since /// then no entry size holds every payload. @@ -111,9 +118,10 @@ pub fn largest_private_document_payload_size( Ok(size) } -/// The smallest `entrySize` that holds every payload of `document_type` in the standard private -/// document envelope (version 1): its largest payload plus -/// [`PRIVATE_DOCUMENT_ENVELOPE_V1_OVERHEAD_BYTES`]. +/// The smallest `entrySize` that holds every payload the property types of `document_type` +/// allow in the standard private document envelope (version 1): its largest payload plus +/// [`PRIVATE_DOCUMENT_ENVELOPE_V1_OVERHEAD_BYTES`]. As +/// [`largest_private_document_payload_size`] says, `enum` and `maxProperties` are not counted. pub fn minimum_private_document_entry_size( document_type: DocumentTypeRef, ) -> Result { diff --git a/packages/rs-platform-wallet/src/wallet/identity/network/contract.rs b/packages/rs-platform-wallet/src/wallet/identity/network/contract.rs index ffa31f95316..809927f9aca 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/network/contract.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/network/contract.rs @@ -43,7 +43,9 @@ use dpp::version::TryFromPlatformVersioned; use dpp::ProtocolError; use dash_sdk::platform::transition::broadcast::BroadcastStateTransition; -use dash_sdk::platform::transition::put_contract::PutContract; +use dash_sdk::platform::transition::put_contract::{ + ensure_private_document_entries_fit, PutContract, +}; use dash_sdk::platform::transition::waitable::Waitable; use dash_sdk::platform::Fetch; @@ -503,6 +505,12 @@ impl IdentityWallet { )) })?; + // A private document type the update adds, or whose properties it changes, takes entries + // that must hold its largest payload, as `PutContract` checks on create; `existing` is the + // contract as Platform holds it, so an unchanged type is not checked again. + ensure_private_document_entries_fit(&updated_contract, Some(&existing)) + .map_err(PlatformWalletError::Sdk)?; + // 4. Build + broadcast the update transition. There's no // `UpdateContract` SDK extension mirroring `PutContract`, // so assemble the `DataContractUpdateTransition` directly: diff --git a/packages/rs-sdk/src/platform/transition/put_contract.rs b/packages/rs-sdk/src/platform/transition/put_contract.rs index f654469ee73..1befb981eb9 100644 --- a/packages/rs-sdk/src/platform/transition/put_contract.rs +++ b/packages/rs-sdk/src/platform/transition/put_contract.rs @@ -240,4 +240,88 @@ mod tests { )) )); } + + /// A mock SDK at the latest protocol version, the first whose contracts declare private + /// types. + fn latest_mock_sdk() -> Sdk { + crate::SdkBuilder::new_mock() + .with_version(PlatformVersion::latest()) + .build() + .expect("a mock SDK") + } + + /// A contract holding only the public type `note`. + fn public_contract() -> DataContract { + let id = Identifier::from([7; 32]).to_string(Encoding::Base58); + let owner_id = Identifier::from([8; 32]).to_string(Encoding::Base58); + DataContract::from_value( + platform_value!({ + "$formatVersion": "1", + "id": id, + "ownerId": owner_id, + "version": 1, + "documentSchemas": { + "note": { + "type": "object", + "properties": { + "text": { "type": "string", "maxLength": 63, "position": 0 } + }, + "additionalProperties": false + } + } + }), + true, + PlatformVersion::latest(), + ) + .expect("the contract registers") + } + + /// An update declaring a private type is checked against the contract Platform holds, + /// fetched: an unchanged undersized type passes, a changed one is refused, every type is new + /// when Platform holds no such contract, and a fetch that fails stops the update. An update + /// declaring no private type fetches nothing. + #[tokio::test] + async fn should_check_an_update_against_the_contract_platform_holds() { + let stored = contract(375, false); + let mut sdk = latest_mock_sdk(); + sdk.mock() + .expect_fetch(stored.id(), Some(stored.clone())) + .await + .expect("an expectation"); + ensure_private_document_entries_fit_on_update(&sdk, &contract(375, false)) + .await + .expect("an unchanged type is not checked"); + assert!(matches!( + ensure_private_document_entries_fit_on_update(&sdk, &contract(375, true)).await, + Err(Error::Protocol( + ProtocolError::PrivateDocumentEntrySizeTooSmall { + minimum_entry_size: 398, + .. + } + )) + )); + + let mut absent = latest_mock_sdk(); + absent + .mock() + .expect_fetch(stored.id(), None::) + .await + .expect("an expectation"); + assert!(matches!( + ensure_private_document_entries_fit_on_update(&absent, &contract(375, false)).await, + Err(Error::Protocol( + ProtocolError::PrivateDocumentEntrySizeTooSmall { .. } + )) + )); + + // No expectation: the mock fails the fetch, and the update stops there. + let failing = latest_mock_sdk(); + let error = ensure_private_document_entries_fit_on_update(&failing, &contract(376, false)) + .await + .expect_err("the fetch fails"); + assert!(!matches!(error, Error::Protocol(_)), "{error:?}"); + ensure_private_document_entries_fit_on_update(&failing, &public_contract()) + .await + .expect("a contract with no private type is not fetched"); + } } From d1308804f2167d226269c1b393a57224038ab171 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Sun, 8 Nov 2026 03:09:59 +0700 Subject: [PATCH 05/11] test(dpp): count a private type's integers at the width the contract stores them A test holds largest_private_document_payload_size to the contract's integer width: with a version 0 config, or sized integer types off as DashPay keeps them, a bounded integer counts 8 bytes, as format 0 writes every integer; with sized integers on, its own width. Co-Authored-By: Claude Opus 5.5 --- .../document_type/private_document.rs | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/packages/rs-dpp/src/data_contract/document_type/private_document.rs b/packages/rs-dpp/src/data_contract/document_type/private_document.rs index 76fc87dec72..4c7760730e2 100644 --- a/packages/rs-dpp/src/data_contract/document_type/private_document.rs +++ b/packages/rs-dpp/src/data_contract/document_type/private_document.rs @@ -429,6 +429,59 @@ mod tests { ); } + /// Integers take the width the contract's documents store them in: with sized integer + /// types off, as a version 0 config always has them and DashPay keeps them, a bounded + /// integer is an i64 of 8 bytes, as format 0 writes every integer. + #[test] + fn should_count_integers_at_the_width_the_contract_stores_them() { + for config in [ + json!({ "$formatVersion": "0" }), + json!({ "$formatVersion": "1", "sizedIntegerTypes": false }), + json!({ "$formatVersion": "1", "sizedIntegerTypes": true }), + ] { + let sized = config.get("sizedIntegerTypes") == Some(&json!(true)); + let contract = DataContract::from_value( + platform_value::to_value(json!({ + "$formatVersion": "1", + "id": Identifier::from([7; 32]).to_string(Encoding::Base58), + "ownerId": Identifier::from([8; 32]).to_string(Encoding::Base58), + "version": 1, + "config": config, + "documentSchemas": { + "secret": { + "type": "object", + "private": { "entrySize": 400 }, + "documentsMutable": false, + "canBeDeleted": false, + "properties": { + "small": { + "type": "integer", "minimum": 0, "maximum": 255, + "position": 0 + } + }, + "required": ["small"], + "additionalProperties": false + } + } + })) + .expect("the contract converts"), + true, + PlatformVersion::latest(), + ) + .expect("the contract registers"); + assert_eq!( + largest_private_document_payload_size( + contract + .document_type_for_name("secret") + .expect("the secret type") + ) + .expect("bounded"), + if sized { 1 } else { 8 }, + "{config}" + ); + } + } + /// A `Date` property carries a marker byte when it is optional; its largest size counts it, /// as its encoding writes it. #[test] From 49473c91d249a5dd4c01aa38c25c088ffde749bc Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Sun, 8 Nov 2026 03:15:37 +0700 Subject: [PATCH 06/11] fix(dpp): encode a private document payload whatever the version of the contract's config A contract keeping a version 0 config can declare a private type, but serialize_specific_version refuses format 3 for it, so its payloads did not encode. DocumentV0::serialize_in_format_3 (crate-visible) writes format 3 whatever the contract or config version; a version 0 config parses every integer as an I64, so the properties come out at the widths largest_private_document_payload_size counts. encode_private_document_payload and decode_private_document_payload no longer take the contract, which only fed the refused version check. A test encodes and decodes a payload under a version 0 config and with sized integers. Co-Authored-By: Claude Opus 5.5 --- .../document_type/private_document.rs | 114 +++++++++++++----- .../rs-dpp/src/document/v0/serialize/mod.rs | 16 +++ .../private_document_envelope_tests.rs | 7 +- 3 files changed, 101 insertions(+), 36 deletions(-) diff --git a/packages/rs-dpp/src/data_contract/document_type/private_document.rs b/packages/rs-dpp/src/data_contract/document_type/private_document.rs index 44cd261c75c..153e6955835 100644 --- a/packages/rs-dpp/src/data_contract/document_type/private_document.rs +++ b/packages/rs-dpp/src/data_contract/document_type/private_document.rs @@ -12,7 +12,6 @@ use crate::data_contract::document_type::accessors::{ DocumentTypeV0Getters, DocumentTypeV2Getters, }; use crate::data_contract::document_type::{property_names, DocumentTypeRef}; -use crate::data_contract::DataContract; use crate::document::serialization_traits::DocumentPlatformConversionMethodsV0; use crate::document::DocumentV0; use crate::ProtocolError; @@ -182,13 +181,12 @@ fn refuse_a_public_type(document_type: DocumentTypeRef) -> Result<(), ProtocolEr } } -/// The payload a private document entry of `document_type` (of `data_contract`) carries for -/// `properties`: the type's properties in the document property encoding, as a format 3 document -/// writes them after its system fields. A value of the wrong type is refused; the schema's -/// bounds are not checked here, so a sender validates `properties` against the type first -/// (`DataContract::validate_document_properties`). +/// The payload a private document entry of `document_type` carries for `properties`: the type's +/// properties in the document property encoding, as a format 3 document writes them after its +/// system fields, whatever the version of its contract's config. A value of the wrong type is +/// refused; the schema's bounds are not checked here, so a sender validates `properties` against +/// the type first (`DataContract::validate_document_properties`). pub fn encode_private_document_payload( - data_contract: &DataContract, document_type: DocumentTypeRef, properties: BTreeMap, ) -> Result, ProtocolError> { @@ -197,11 +195,7 @@ pub fn encode_private_document_payload( properties, ..Default::default() }; - let serialized = document.serialize_specific_version( - document_type, - data_contract, - PRIVATE_DOCUMENT_PAYLOAD_DOCUMENT_FORMAT, - )?; + let serialized = document.serialize_in_format_3(document_type)?; serialized .strip_prefix(private_document_payload_prefix().as_slice()) .map(<[u8]>::to_vec) @@ -214,13 +208,12 @@ pub fn encode_private_document_payload( }) } -/// The properties a private document payload of `document_type` (of `data_contract`) holds. +/// The properties a private document payload of `document_type` holds. /// Only the encoding [`encode_private_document_payload`] gives back is read: a payload that does /// not decode, or that holds anything else, such as bytes after the last property, is refused. /// The schema's bounds are not checked here, so a recipient validates the properties against /// the type before trusting them (`DataContract::validate_document_properties`). pub fn decode_private_document_payload( - data_contract: &DataContract, document_type: DocumentTypeRef, payload: &[u8], platform_version: &PlatformVersion, @@ -230,8 +223,7 @@ pub fn decode_private_document_payload( serialized.extend_from_slice(payload); let properties = DocumentV0::from_bytes(&serialized, document_type, platform_version)?.properties; - if encode_private_document_payload(data_contract, document_type, properties.clone())? != payload - { + if encode_private_document_payload(document_type, properties.clone())? != payload { return Err(ProtocolError::DecodingError( "a private document payload holds bytes its properties do not encode to".to_string(), )); @@ -528,19 +520,18 @@ mod tests { .document_type_for_name("secret") .expect("the secret type"); - let payload = encode_private_document_payload(&contract, secret, largest_values()) - .expect("the values encode"); + let payload = + encode_private_document_payload(secret, largest_values()).expect("the values encode"); assert_eq!( payload.len() as u32, largest_private_document_payload_size(secret).expect("bounded") ); - let decoded = - decode_private_document_payload(&contract, secret, &payload, platform_version) - .expect("the payload decodes"); + let decoded = decode_private_document_payload(secret, &payload, platform_version) + .expect("the payload decodes"); assert_eq!(decoded.get("label"), Some(&Value::Text(wide(10)))); assert_eq!(decoded.get("key"), Some(&Value::Bytes(vec![1; 33]))); assert_eq!( - encode_private_document_payload(&contract, secret, decoded).expect("re-encodes"), + encode_private_document_payload(secret, decoded).expect("re-encodes"), payload ); @@ -551,7 +542,7 @@ mod tests { ("key".to_string(), Value::Bytes(vec![1; 33])), ]); assert_eq!( - encode_private_document_payload(&contract, secret, smallest) + encode_private_document_payload(secret, smallest) .expect("encodes") .len(), 1 + 8 + 33 + 8 @@ -567,17 +558,12 @@ mod tests { let secret = contract .document_type_for_name("secret") .expect("the secret type"); - let payload = - encode_private_document_payload(&contract, secret, largest_values()).expect("encodes"); + let payload = encode_private_document_payload(secret, largest_values()).expect("encodes"); let mut trailing = payload.clone(); trailing.push(0); - assert!( - decode_private_document_payload(&contract, secret, &trailing, platform_version) - .is_err() - ); + assert!(decode_private_document_payload(secret, &trailing, platform_version).is_err()); assert!(decode_private_document_payload( - &contract, secret, &payload[..payload.len() - 1], platform_version @@ -588,15 +574,79 @@ mod tests { .document_type_for_name("note") .expect("the note type"); assert!(matches!( - encode_private_document_payload(&contract, note, BTreeMap::new()), + encode_private_document_payload(note, BTreeMap::new()), Err(ProtocolError::NotSupported(_)) )); assert!(matches!( - decode_private_document_payload(&contract, note, &[0], platform_version), + decode_private_document_payload(note, &[0], platform_version), Err(ProtocolError::NotSupported(_)) )); } + /// A payload is written in format 3 whatever the contract's config: a type of a contract + /// keeping a version 0 config, whose documents are written in format 0, encodes and decodes + /// its payload as well, its integers at the 8 bytes it counts them. + #[test] + fn should_encode_a_payload_whatever_the_version_of_the_contract_config() { + let platform_version = PlatformVersion::latest(); + for config in [ + json!({ "$formatVersion": "0" }), + json!({ "$formatVersion": "1", "sizedIntegerTypes": true }), + ] { + let contract = DataContract::from_value( + platform_value::to_value(json!({ + "$formatVersion": "1", + "id": Identifier::from([7; 32]).to_string(Encoding::Base58), + "ownerId": Identifier::from([8; 32]).to_string(Encoding::Base58), + "version": 1, + "config": config, + "documentSchemas": { + "secret": { + "type": "object", + "private": { "entrySize": 400 }, + "documentsMutable": false, + "canBeDeleted": false, + "properties": { + "small": { + "type": "integer", "minimum": 0, "maximum": 255, + "position": 0 + }, + "label": { "type": "string", "maxLength": 4, "position": 1 } + }, + "required": ["small"], + "additionalProperties": false + } + } + })) + .expect("the contract converts"), + true, + platform_version, + ) + .expect("the contract registers"); + let secret = contract + .document_type_for_name("secret") + .expect("the secret type"); + let properties = BTreeMap::from([ + ("small".to_string(), Value::U64(255)), + ("label".to_string(), Value::Text(wide(4))), + ]); + let payload = encode_private_document_payload(secret, properties) + .unwrap_or_else(|error| panic!("{config}: encodes: {error}")); + assert_eq!( + payload.len() as u32, + largest_private_document_payload_size(secret).expect("bounded"), + "{config}" + ); + let decoded = decode_private_document_payload(secret, &payload, platform_version) + .unwrap_or_else(|error| panic!("{config}: decodes: {error}")); + assert_eq!( + decoded.get("label"), + Some(&Value::Text(wide(4))), + "{config}" + ); + } + } + /// The type's schema validates a payload's properties, before sealing and after opening: /// the largest values pass, and a string over its bound, which decodes, is refused. #[cfg(feature = "validation")] diff --git a/packages/rs-dpp/src/document/v0/serialize/mod.rs b/packages/rs-dpp/src/document/v0/serialize/mod.rs index f2942479bbb..e9b41b7e24c 100644 --- a/packages/rs-dpp/src/document/v0/serialize/mod.rs +++ b/packages/rs-dpp/src/document/v0/serialize/mod.rs @@ -56,6 +56,22 @@ impl DocumentPlatformSerializationMethodsV0 for DocumentV0 { } } +impl DocumentV0 { + /// This document in serialization format 3, whatever the version of its contract or of the + /// contract's config. A private document payload holds a type's properties as format 3 + /// writes them (`encode_private_document_payload`), including for a type whose contract keeps + /// a version 0 config, whose documents [`DocumentPlatformConversionMethodsV0::serialize`] + /// writes in format 0. Format 3 writes each property at its type's width, and a version 0 + /// config parses every integer as an `I64`, so the properties come out as format 0 writes + /// them too. + pub(crate) fn serialize_in_format_3( + &self, + document_type: DocumentTypeRef, + ) -> Result, ProtocolError> { + DocumentV0::serialize_v3(self, document_type) + } +} + impl DocumentPlatformDeserializationMethodsV0 for DocumentV0 { /// Format 0 โ€” implementation in [`v0`]. fn from_bytes_v0( diff --git a/packages/rs-sdk/src/platform/private_document_envelope_tests.rs b/packages/rs-sdk/src/platform/private_document_envelope_tests.rs index bac232c011e..a4ad6ea0250 100644 --- a/packages/rs-sdk/src/platform/private_document_envelope_tests.rs +++ b/packages/rs-sdk/src/platform/private_document_envelope_tests.rs @@ -112,7 +112,7 @@ fn should_carry_the_largest_payload_in_an_entry_of_the_minimum_size() { ("autoAcceptProof".to_string(), Value::Bytes(vec![2; 102])), ("shieldedAddress".to_string(), Value::Bytes(vec![3; 43])), ]); - let payload = encode_private_document_payload(&contract, request, properties).expect("encodes"); + let payload = encode_private_document_payload(request, properties).expect("encodes"); assert_eq!( payload.len(), entry_size - PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN @@ -149,9 +149,8 @@ fn should_carry_the_largest_payload_in_an_entry_of_the_minimum_size() { opened .verify_sender(&PublicKey::from_secret_key(&sender_key), &recipient_key) .expect("from the sender"); - let decoded = - decode_private_document_payload(&contract, request, &opened.payload, platform_version) - .expect("decodes"); + let decoded = decode_private_document_payload(request, &opened.payload, platform_version) + .expect("decodes"); assert_eq!( decoded.get("accountLabel"), Some(&Value::Text("a".repeat(63))) From b0c97cf456c0d5d48da9a7ad93be073e0bcdef50 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Sun, 8 Nov 2026 04:32:24 +0700 Subject: [PATCH 07/11] fix(sdk): constant-time ECDH, readable old and empty-object payloads, and an envelope error type platform-encryption: - The envelope's ECDH multiplies in constant time: secp256k1's shared_secret_point (libsecp256k1's ECDH, ecmult_const) instead of PublicKey::mul_tweak, compressed to the same 33 bytes, so the format and its pinned vectors are unchanged. A wallet's long-lived keys meet attacker-chosen points when it scans. - The envelope has its own PrivateDocumentEnvelopeError; CryptoError is back to its four variants, so its exhaustive matches still compile. - OpenedPrivateDocumentEntry's fields are private behind read-only accessors (and into_payload), so what a caller reads is what verify_sender authenticated. - An entry size below the envelope's 299 bytes is refused as InvalidEntryLength, not as a payload too large; the smallest entry carries an empty payload. dpp: - A payload decodes as a document's reader reads it: a value cut short or a byte after the last property is refused, and a payload written before its type gained optional properties, at the type's end or an object's, reads them as absent. The exact re-encoding check refused such entries, which are immutable. - Encoding refuses a present object holding no member at any depth, which a document's reader reads back as absent. Tests: the MAC with the wrong recipient key, the 298- and 299-byte entries, empty objects (required, optional, nested), and an older payload read under a type that gained a property at its end and in its object. Co-Authored-By: Claude Opus 5.5 --- .../document_type/private_document.rs | 231 ++++++++++++- packages/rs-platform-encryption/src/error.rs | 24 -- packages/rs-platform-encryption/src/lib.rs | 4 +- .../src/private_document_envelope.rs | 318 ++++++++++++------ .../private_document_envelope_tests.rs | 2 +- 5 files changed, 426 insertions(+), 153 deletions(-) diff --git a/packages/rs-dpp/src/data_contract/document_type/private_document.rs b/packages/rs-dpp/src/data_contract/document_type/private_document.rs index 153e6955835..9c129fe8efa 100644 --- a/packages/rs-dpp/src/data_contract/document_type/private_document.rs +++ b/packages/rs-dpp/src/data_contract/document_type/private_document.rs @@ -11,10 +11,12 @@ use crate::data_contract::document_type::accessors::{ DocumentTypeV0Getters, DocumentTypeV2Getters, }; -use crate::data_contract::document_type::{property_names, DocumentTypeRef}; +use crate::data_contract::document_type::property::DocumentProperty; +use crate::data_contract::document_type::{property_names, DocumentPropertyType, DocumentTypeRef}; use crate::document::serialization_traits::DocumentPlatformConversionMethodsV0; use crate::document::DocumentV0; use crate::ProtocolError; +use indexmap::IndexMap; use platform_value::Value; use platform_version::version::PlatformVersion; use std::collections::BTreeMap; @@ -181,16 +183,61 @@ fn refuse_a_public_type(document_type: DocumentTypeRef) -> Result<(), ProtocolEr } } +/// Refuses a present object holding no member, at any depth: the document property encoding +/// writes it, but a document's reader reads an object with no members back as absent, so the +/// payload would not read back as it was written. +fn refuse_present_empty_objects( + fields: &IndexMap, + values: &BTreeMap<&str, &Value>, + path: &str, +) -> Result<(), ProtocolError> { + for (name, field) in fields { + let DocumentPropertyType::Object(members) = &field.property_type else { + continue; + }; + let Some(Value::Map(entries)) = values.get(name.as_str()).copied() else { + continue; + }; + let object_path = if path.is_empty() { + name.clone() + } else { + format!("{path}.{name}") + }; + let present: BTreeMap<&str, &Value> = entries + .iter() + .filter_map(|(key, value)| { + let key = key.as_text()?; + (members.contains_key(key) && !value.is_null()).then_some((key, value)) + }) + .collect(); + if present.is_empty() { + return Err(ProtocolError::NotSupported(format!( + "object {object_path} holds no member: a document reads an object with no members \ + back as absent, so a private document payload cannot carry one" + ))); + } + refuse_present_empty_objects(members, &present, &object_path)?; + } + Ok(()) +} + /// The payload a private document entry of `document_type` carries for `properties`: the type's /// properties in the document property encoding, as a format 3 document writes them after its /// system fields, whatever the version of its contract's config. A value of the wrong type is -/// refused; the schema's bounds are not checked here, so a sender validates `properties` against -/// the type first (`DataContract::validate_document_properties`). +/// refused, and so is a present object holding no member, which would read back as absent; the +/// schema's bounds are not checked here, so a sender validates `properties` against the type +/// first (`DataContract::validate_document_properties`). pub fn encode_private_document_payload( document_type: DocumentTypeRef, properties: BTreeMap, ) -> Result, ProtocolError> { refuse_a_public_type(document_type)?; + let present: BTreeMap<&str, &Value> = properties + .iter() + .filter(|(_, value)| !value.is_null()) + .map(|(name, value)| (name.as_str(), value)) + .collect(); + refuse_present_empty_objects(document_type.properties(), &present, "")?; let document = DocumentV0 { properties, ..Default::default() @@ -208,11 +255,13 @@ pub fn encode_private_document_payload( }) } -/// The properties a private document payload of `document_type` holds. -/// Only the encoding [`encode_private_document_payload`] gives back is read: a payload that does -/// not decode, or that holds anything else, such as bytes after the last property, is refused. -/// The schema's bounds are not checked here, so a recipient validates the properties against -/// the type before trusting them (`DataContract::validate_document_properties`). +/// The properties a private document payload of `document_type` holds, read as a document's +/// reader reads them after its system fields: a value cut short, or a byte after the last +/// property, is refused. An entry is immutable while its type can gain optional properties, at +/// the end of the type or of one of its objects, so a payload written before them ends before +/// them, and reads them as absent. The schema's bounds are not checked here, so a recipient +/// validates the properties against the type before trusting them +/// (`DataContract::validate_document_properties`). pub fn decode_private_document_payload( document_type: DocumentTypeRef, payload: &[u8], @@ -221,14 +270,7 @@ pub fn decode_private_document_payload( refuse_a_public_type(document_type)?; let mut serialized = private_document_payload_prefix().to_vec(); serialized.extend_from_slice(payload); - let properties = - DocumentV0::from_bytes(&serialized, document_type, platform_version)?.properties; - if encode_private_document_payload(document_type, properties.clone())? != payload { - return Err(ProtocolError::DecodingError( - "a private document payload holds bytes its properties do not encode to".to_string(), - )); - } - Ok(properties) + Ok(DocumentV0::from_bytes(&serialized, document_type, platform_version)?.properties) } #[cfg(test)] @@ -647,6 +689,163 @@ mod tests { } } + /// A contract with the private type `secret` of `properties`, `required` of them required. + fn private_type_contract( + properties: serde_json::Value, + required: serde_json::Value, + ) -> DataContract { + contract(1000, properties, required) + } + + /// A present object holding no member, required or optional, at any depth, is refused: a + /// document reads it back as absent. One holding a member encodes and reads back. + #[test] + fn should_refuse_a_present_object_holding_no_member() { + let platform_version = PlatformVersion::latest(); + let contract = private_type_contract( + json!({ + "meta": { + "type": "object", + "properties": { + "flag": { "type": "boolean", "position": 0 }, + "inner": { + "type": "object", + "properties": { "x": { "type": "boolean", "position": 0 } }, + "additionalProperties": false, + "position": 1 + } + }, + "additionalProperties": false, + "position": 0 + }, + "more": { + "type": "object", + "properties": { "y": { "type": "boolean", "position": 0 } }, + "additionalProperties": false, + "position": 1 + } + }), + json!(["meta"]), + ); + let secret = contract + .document_type_for_name("secret") + .expect("the secret type"); + let object = |members: Vec<(&str, Value)>| { + Value::Map( + members + .into_iter() + .map(|(key, value)| (Value::Text(key.to_string()), value)) + .collect(), + ) + }; + for (case, properties) in [ + ("an empty required object", vec![("meta", object(vec![]))]), + ( + "an empty optional object", + vec![ + ("meta", object(vec![("flag", Value::Bool(true))])), + ("more", object(vec![])), + ], + ), + ( + "an empty object inside one", + vec![("meta", object(vec![("inner", object(vec![]))]))], + ), + ] { + let properties = properties + .into_iter() + .map(|(key, value)| (key.to_string(), value)) + .collect(); + assert!( + matches!( + encode_private_document_payload(secret, properties), + Err(ProtocolError::NotSupported(_)) + ), + "{case}" + ); + } + + let properties = BTreeMap::from([( + "meta".to_string(), + object(vec![("inner", object(vec![("x", Value::Bool(false))]))]), + )]); + let payload = + encode_private_document_payload(secret, properties).expect("a member is present"); + let decoded = + decode_private_document_payload(secret, &payload, platform_version).expect("decodes"); + assert_eq!( + encode_private_document_payload(secret, decoded).expect("re-encodes"), + payload + ); + } + + /// An entry is immutable while its type can gain optional properties: a payload written + /// before the type gained one at its end and one at the end of its object reads under the + /// newer type, the new properties absent, and still refuses a byte after its last property. + #[test] + fn should_read_a_payload_written_before_the_type_gained_optional_properties() { + let platform_version = PlatformVersion::latest(); + let meta = |with_member: bool| { + let mut properties = json!({ + "a": { "type": "integer", "minimum": 0, "maximum": 255, "position": 0 } + }); + if with_member { + properties["b"] = json!({ "type": "boolean", "position": 1 }); + } + json!({ + "type": "object", + "properties": properties, + "required": ["a"], + "additionalProperties": false, + "position": 1 + }) + }; + let before = private_type_contract( + json!({ "flag": { "type": "boolean", "position": 0 }, "meta": meta(false) }), + json!(["flag", "meta"]), + ); + let after = private_type_contract( + json!({ + "flag": { "type": "boolean", "position": 0 }, + "meta": meta(true), + "extra": { "type": "boolean", "position": 2 } + }), + json!(["flag", "meta"]), + ); + let properties = BTreeMap::from([ + ("flag".to_string(), Value::Bool(true)), + ( + "meta".to_string(), + Value::Map(vec![(Value::Text("a".to_string()), Value::U64(7))]), + ), + ]); + let written = encode_private_document_payload( + before.document_type_for_name("secret").expect("the type"), + properties, + ) + .expect("encodes"); + + let newer = after.document_type_for_name("secret").expect("the type"); + let read = decode_private_document_payload(newer, &written, platform_version) + .expect("an older payload reads under the newer type"); + assert_eq!(read.get("flag"), Some(&Value::Bool(true))); + assert_eq!(read.get("extra"), None); + assert_eq!( + read.get("meta") + .and_then(|meta| meta.get_optional_value("b").ok().flatten()), + None + ); + + let mut trailing = written.clone(); + trailing.push(0); + assert!(decode_private_document_payload( + before.document_type_for_name("secret").expect("the type"), + &trailing, + platform_version + ) + .is_err()); + } + /// The type's schema validates a payload's properties, before sealing and after opening: /// the largest values pass, and a string over its bound, which decodes, is refused. #[cfg(feature = "validation")] diff --git a/packages/rs-platform-encryption/src/error.rs b/packages/rs-platform-encryption/src/error.rs index fbdac68ce7a..763aaa6ee6b 100644 --- a/packages/rs-platform-encryption/src/error.rs +++ b/packages/rs-platform-encryption/src/error.rs @@ -14,28 +14,4 @@ pub enum CryptoError { #[error("Invalid compact xpub length (DIP-15 requires exactly 69 bytes, got {0})")] InvalidCompactXpubLength(usize), - - #[error("a private document payload of {payload_len} bytes does not fit an entry that holds {capacity}")] - PrivateDocumentPayloadTooLarge { payload_len: usize, capacity: usize }, - - #[error("a private document entry of {0} bytes is shorter than the envelope's 299")] - InvalidPrivateDocumentEntryLength(usize), - - #[error("the ephemeral seed derives no valid secret key; draw another")] - InvalidPrivateDocumentEphemeralSeed, - - #[error("malformed private document entry: {0}")] - MalformedPrivateDocumentEntry(&'static str), - - #[error("private document envelope version {0} is not supported")] - UnsupportedPrivateDocumentEnvelopeVersion(u8), - - #[error("the private document entry names another recipient identity")] - WrongPrivateDocumentRecipient, - - #[error("the private document entry is anonymous: it names no sender to check")] - AnonymousPrivateDocumentSender, - - #[error("the private document entry's sender authentication does not verify")] - PrivateDocumentSenderNotAuthenticated, } diff --git a/packages/rs-platform-encryption/src/lib.rs b/packages/rs-platform-encryption/src/lib.rs index b4785b10095..da3590412cf 100644 --- a/packages/rs-platform-encryption/src/lib.rs +++ b/packages/rs-platform-encryption/src/lib.rs @@ -43,8 +43,8 @@ pub use error::CryptoError; pub use private_document_envelope::{ open_private_document_entry, private_document_outgoing_viewing_key, recover_sent_private_document_entry, seal_private_document_entry, OpenedPrivateDocumentEntry, - PrivateDocumentAuthMode, PrivateDocumentRecipient, PrivateDocumentSender, - PrivateDocumentTarget, PRIVATE_DOCUMENT_ENVELOPE_BODY_HEADER_LEN, + PrivateDocumentAuthMode, PrivateDocumentEnvelopeError, PrivateDocumentRecipient, + PrivateDocumentSender, PrivateDocumentTarget, PRIVATE_DOCUMENT_ENVELOPE_BODY_HEADER_LEN, PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN, PRIVATE_DOCUMENT_ENVELOPE_VERSION, PRIVATE_DOCUMENT_ENVELOPE_WRAPPER_LEN, }; diff --git a/packages/rs-platform-encryption/src/private_document_envelope.rs b/packages/rs-platform-encryption/src/private_document_envelope.rs index 549b51bacb7..c09fb1f2489 100644 --- a/packages/rs-platform-encryption/src/private_document_envelope.rs +++ b/packages/rs-platform-encryption/src/private_document_envelope.rs @@ -54,11 +54,41 @@ use chacha20poly1305::aead::{Aead, KeyInit, Payload}; use chacha20poly1305::{ChaCha20Poly1305, Key, Nonce}; use hmac::{Hmac, Mac}; +use secp256k1::ecdh::shared_secret_point; use secp256k1::ecdsa::{RecoverableSignature, RecoveryId}; -use secp256k1::{Message, PublicKey, Scalar, SecretKey}; +use secp256k1::{Message, PublicKey, SecretKey}; use sha2::{Digest, Sha256}; -use crate::error::CryptoError; +/// Why an entry could not be built, opened, recovered or checked. +#[derive(Debug, PartialEq, Eq, thiserror::Error)] +pub enum PrivateDocumentEnvelopeError { + #[error("a private document payload of {payload_len} bytes does not fit an entry that holds {capacity}")] + PayloadTooLarge { payload_len: usize, capacity: usize }, + + #[error("a private document entry of {0} bytes is shorter than the envelope's 299")] + InvalidEntryLength(usize), + + #[error("the ephemeral seed derives no valid secret key; draw another")] + InvalidEphemeralSeed, + + #[error("a private document ciphertext does not decrypt")] + DecryptionFailed, + + #[error("malformed private document entry: {0}")] + Malformed(&'static str), + + #[error("private document envelope version {0} is not supported")] + UnsupportedVersion(u8), + + #[error("the private document entry names another recipient identity")] + WrongRecipient, + + #[error("the private document entry is anonymous: it names no sender to check")] + AnonymousSender, + + #[error("the private document entry's sender authentication does not verify")] + SenderNotAuthenticated, +} /// The envelope version this module builds and opens. pub const PRIVATE_DOCUMENT_ENVELOPE_VERSION: u8 = 1; @@ -156,30 +186,68 @@ impl PrivateDocumentAuthMode { /// An entry its recipient opened, or its sender recovered. /// /// The sender fields are what the entry claims; [`Self::verify_sender`] checks the claim -/// against the key the sender's identity holds under `sender_key_id`. +/// against the key the sender's identity holds under `sender_key_id`. The fields are read-only, +/// so what a caller reads is what was authenticated. #[derive(Clone, Debug, PartialEq, Eq)] pub struct OpenedPrivateDocumentEntry { + commitment: [u8; 32], + recipient_key_index: Option, + recipient_public_key: PublicKey, + recipient_identity_id: [u8; 32], + auth_mode: PrivateDocumentAuthMode, + sender_identity_id: [u8; 32], + sender_key_id: u32, + payload: Vec, + auth: [u8; AUTH_LEN], + auth_message: [u8; 32], +} + +impl OpenedPrivateDocumentEntry { /// The entry's commitment: two entries with the same one are copies. - pub commitment: [u8; 32], + pub fn commitment(&self) -> &[u8; 32] { + &self.commitment + } + /// Which of the keys given to [`open_private_document_entry`] opened it; `None` when the /// sender recovered it. - pub recipient_key_index: Option, + pub fn recipient_key_index(&self) -> Option { + self.recipient_key_index + } + /// The key the entry is encrypted to. - pub recipient_public_key: PublicKey, - pub recipient_identity_id: [u8; 32], - pub auth_mode: PrivateDocumentAuthMode, + pub fn recipient_public_key(&self) -> &PublicKey { + &self.recipient_public_key + } + + pub fn recipient_identity_id(&self) -> &[u8; 32] { + &self.recipient_identity_id + } + + pub fn auth_mode(&self) -> PrivateDocumentAuthMode { + self.auth_mode + } + /// Zeros when the entry is anonymous. - pub sender_identity_id: [u8; 32], + pub fn sender_identity_id(&self) -> &[u8; 32] { + &self.sender_identity_id + } + /// Zero when the entry is anonymous. - pub sender_key_id: u32, + pub fn sender_key_id(&self) -> u32 { + self.sender_key_id + } + /// The type's properties in the document property encoding, for the type's schema to /// decode and validate. - pub payload: Vec, - auth: [u8; AUTH_LEN], - auth_message: [u8; 32], -} + pub fn payload(&self) -> &[u8] { + &self.payload + } + + /// The payload, taking the entry. + pub fn into_payload(self) -> Vec { + self.payload + } -impl OpenedPrivateDocumentEntry { /// Checks that the key the entry names wrote it: `sender_public_key` is the key the sender /// identity holds under `sender_key_id`, as it was when the entry was written (keys are /// disabled, never removed). A deniable MAC is checked with the recipient's own secret key, @@ -188,30 +256,32 @@ impl OpenedPrivateDocumentEntry { &self, sender_public_key: &PublicKey, recipient_secret_key: &SecretKey, - ) -> Result<(), CryptoError> { + ) -> Result<(), PrivateDocumentEnvelopeError> { match self.auth_mode { - PrivateDocumentAuthMode::Anonymous => Err(CryptoError::AnonymousPrivateDocumentSender), + PrivateDocumentAuthMode::Anonymous => { + Err(PrivateDocumentEnvelopeError::AnonymousSender) + } PrivateDocumentAuthMode::DeniableMac => { - let mac_key = mac_key(&shared_point(recipient_secret_key, sender_public_key)?); + let mac_key = mac_key(&shared_point(recipient_secret_key, sender_public_key)); let mut mac = as Mac>::new_from_slice(&mac_key) .expect("HMAC takes a key of any length"); mac.update(&self.auth_message); mac.verify_slice(&self.auth[..MAC_LEN]) - .map_err(|_| CryptoError::PrivateDocumentSenderNotAuthenticated) + .map_err(|_| PrivateDocumentEnvelopeError::SenderNotAuthenticated) } PrivateDocumentAuthMode::Signature => { let recovery_id = RecoveryId::from_u8_masked( self.auth[0].wrapping_sub(COMPACT_SIGNATURE_HEADER_BASE), ); let signature = RecoverableSignature::from_compact(&self.auth[1..], recovery_id) - .map_err(|_| CryptoError::PrivateDocumentSenderNotAuthenticated)?; + .map_err(|_| PrivateDocumentEnvelopeError::SenderNotAuthenticated)?; let signer = signature .recover_ecdsa(Message::from_digest(self.auth_message)) - .map_err(|_| CryptoError::PrivateDocumentSenderNotAuthenticated)?; + .map_err(|_| PrivateDocumentEnvelopeError::SenderNotAuthenticated)?; if signer == *sender_public_key { Ok(()) } else { - Err(CryptoError::PrivateDocumentSenderNotAuthenticated) + Err(PrivateDocumentEnvelopeError::SenderNotAuthenticated) } } } @@ -239,14 +309,15 @@ pub fn seal_private_document_entry( payload: &[u8], outgoing_viewing_key: &[u8; 32], esk_seed: &[u8; 32], -) -> Result, CryptoError> { - let capacity = entry_size.saturating_sub(PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN); +) -> Result, PrivateDocumentEnvelopeError> { + if entry_size < PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN { + return Err(PrivateDocumentEnvelopeError::InvalidEntryLength(entry_size)); + } + let capacity = entry_size - PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN; let payload_len = u16::try_from(payload.len()) .ok() - .filter(|_| { - entry_size >= PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN && payload.len() <= capacity - }) - .ok_or(CryptoError::PrivateDocumentPayloadTooLarge { + .filter(|_| payload.len() <= capacity) + .ok_or(PrivateDocumentEnvelopeError::PayloadTooLarge { payload_len: payload.len(), capacity, })?; @@ -256,7 +327,7 @@ pub fn seal_private_document_entry( let epk = PublicKey::from_secret_key(&esk).serialize(); let recipient_key = recipient.public_key.serialize(); let key = entry_key( - &shared_point(&esk, recipient.public_key)?, + &shared_point(&esk, recipient.public_key), &epk, &recipient_key, ); @@ -286,7 +357,7 @@ pub fn seal_private_document_entry( match sender { PrivateDocumentSender::Anonymous => {} PrivateDocumentSender::DeniableMac { secret_key, .. } => { - let mac_key = mac_key(&shared_point(secret_key, recipient.public_key)?); + let mac_key = mac_key(&shared_point(secret_key, recipient.public_key)); let mut mac = as Mac>::new_from_slice(&mac_key) .expect("HMAC takes a key of any length"); mac.update(&auth_message); @@ -347,7 +418,7 @@ pub fn open_private_document_entry( target: &PrivateDocumentTarget, recipient_identity_id: &[u8; 32], recipient_secret_keys: &[SecretKey], -) -> Result, CryptoError> { +) -> Result, PrivateDocumentEnvelopeError> { let parts = EntryParts::split(entry)?; let Ok(epk) = PublicKey::from_slice(parts.epk) else { // No key opens an entry whose ephemeral key is not a point. @@ -356,7 +427,7 @@ pub fn open_private_document_entry( for (index, secret_key) in recipient_secret_keys.iter().enumerate() { let recipient_public_key = PublicKey::from_secret_key(secret_key); let recipient_key = recipient_public_key.serialize(); - let key = entry_key(&shared_point(secret_key, &epk)?, parts.epk, &recipient_key); + let key = entry_key(&shared_point(secret_key, &epk), parts.epk, &recipient_key); let Ok(body) = decrypt(&key, parts.commitment, parts.body_ct) else { continue; }; @@ -371,7 +442,7 @@ pub fn open_private_document_entry( Some(index), )?; if opened.recipient_identity_id != *recipient_identity_id { - return Err(CryptoError::WrongPrivateDocumentRecipient); + return Err(PrivateDocumentEnvelopeError::WrongRecipient); } return Ok(Some(opened)); } @@ -385,7 +456,7 @@ pub fn recover_sent_private_document_entry( entry: &[u8], target: &PrivateDocumentTarget, outgoing_viewing_key: &[u8; 32], -) -> Result, CryptoError> { +) -> Result, PrivateDocumentEnvelopeError> { let parts = EntryParts::split(entry)?; let Ok(sender_recovery) = decrypt( &outgoing_cipher_key(outgoing_viewing_key, parts.epk), @@ -394,7 +465,7 @@ pub fn recover_sent_private_document_entry( ) else { return Ok(None); }; - let malformed = || CryptoError::MalformedPrivateDocumentEntry("sender recovery"); + let malformed = || PrivateDocumentEnvelopeError::Malformed("sender recovery"); let recipient_public_key = PublicKey::from_slice(&sender_recovery[..EPHEMERAL_KEY_LEN]).map_err(|_| malformed())?; let esk_seed: [u8; 32] = sender_recovery[EPHEMERAL_KEY_LEN..] @@ -406,7 +477,7 @@ pub fn recover_sent_private_document_entry( } let recipient_key = recipient_public_key.serialize(); let key = entry_key( - &shared_point(&esk, &recipient_public_key)?, + &shared_point(&esk, &recipient_public_key), parts.epk, &recipient_key, ); @@ -426,9 +497,11 @@ struct EntryParts<'a> { } impl<'a> EntryParts<'a> { - fn split(entry: &'a [u8]) -> Result { + fn split(entry: &'a [u8]) -> Result { if entry.len() < PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN { - return Err(CryptoError::InvalidPrivateDocumentEntryLength(entry.len())); + return Err(PrivateDocumentEnvelopeError::InvalidEntryLength( + entry.len(), + )); } let (commitment, rest) = entry.split_at(COMMITMENT_LEN); let (epk, rest) = rest.split_at(EPHEMERAL_KEY_LEN); @@ -449,15 +522,13 @@ fn parse_body( commitment: [u8; 32], recipient_public_key: PublicKey, recipient_key_index: Option, -) -> Result { - let malformed = CryptoError::MalformedPrivateDocumentEntry; +) -> Result { + let malformed = PrivateDocumentEnvelopeError::Malformed; if body.len() < PRIVATE_DOCUMENT_ENVELOPE_BODY_HEADER_LEN { return Err(malformed("body shorter than its header")); } if body[0] != PRIVATE_DOCUMENT_ENVELOPE_VERSION { - return Err(CryptoError::UnsupportedPrivateDocumentEnvelopeVersion( - body[0], - )); + return Err(PrivateDocumentEnvelopeError::UnsupportedVersion(body[0])); } let auth_mode = PrivateDocumentAuthMode::from_byte(body[1]).ok_or(malformed("unknown auth mode"))?; @@ -520,19 +591,21 @@ fn type_name_length(target: &PrivateDocumentTarget) -> [u8; 4] { (target.document_type_name.len() as u32).to_le_bytes() } -fn ephemeral_secret_key(esk_seed: &[u8; 32]) -> Result { +fn ephemeral_secret_key(esk_seed: &[u8; 32]) -> Result { SecretKey::from_secret_bytes(hash(&[DOMAIN_ESK, esk_seed])) - .map_err(|_| CryptoError::InvalidPrivateDocumentEphemeralSeed) + .map_err(|_| PrivateDocumentEnvelopeError::InvalidEphemeralSeed) } -/// `secret_key * public_key`, compressed. -fn shared_point(secret_key: &SecretKey, public_key: &PublicKey) -> Result<[u8; 33], CryptoError> { - let scalar = Scalar::from_be_bytes(secret_key.to_secret_bytes()) - .map_err(|_| CryptoError::MalformedPrivateDocumentEntry("secret key out of range"))?; - public_key - .mul_tweak(&scalar) - .map(|point| point.serialize()) - .map_err(|_| CryptoError::MalformedPrivateDocumentEntry("shared point at infinity")) +/// `secret_key * public_key`, compressed, computed in constant time: the secret keys are a +/// wallet's long-lived keys and the points are an attacker's, so the multiplication must not leak +/// the key through timing. libsecp256k1's ECDH multiplies in constant time; it hands back the +/// point's coordinates, compressed here as `0x02 | (y & 1)` then `x`. +fn shared_point(secret_key: &SecretKey, public_key: &PublicKey) -> [u8; 33] { + let xy = shared_secret_point(public_key, secret_key); + let mut point = [0u8; 33]; + point[0] = 0x02 | (xy[63] & 1); + point[1..].copy_from_slice(&xy[..32]); + point } fn entry_key(shared_point: &[u8; 33], epk: &[u8; 33], recipient_key: &[u8; 33]) -> [u8; 32] { @@ -586,7 +659,11 @@ fn auth_message( ]) } -fn encrypt(key: &[u8; 32], aad: &[u8; 32], plaintext: &[u8]) -> Result, CryptoError> { +fn encrypt( + key: &[u8; 32], + aad: &[u8; 32], + plaintext: &[u8], +) -> Result, PrivateDocumentEnvelopeError> { ChaCha20Poly1305::new(Key::from_slice(key)) .encrypt( Nonce::from_slice(&[0; 12]), @@ -595,10 +672,14 @@ fn encrypt(key: &[u8; 32], aad: &[u8; 32], plaintext: &[u8]) -> Result, aad, }, ) - .map_err(|_| CryptoError::MalformedPrivateDocumentEntry("encryption failed")) + .map_err(|_| PrivateDocumentEnvelopeError::Malformed("encryption failed")) } -fn decrypt(key: &[u8; 32], aad: &[u8; 32], ciphertext: &[u8]) -> Result, CryptoError> { +fn decrypt( + key: &[u8; 32], + aad: &[u8; 32], + ciphertext: &[u8], +) -> Result, PrivateDocumentEnvelopeError> { ChaCha20Poly1305::new(Key::from_slice(key)) .decrypt( Nonce::from_slice(&[0; 12]), @@ -607,7 +688,7 @@ fn decrypt(key: &[u8; 32], aad: &[u8; 32], ciphertext: &[u8]) -> Result, aad, }, ) - .map_err(|_| CryptoError::DecryptionFailed) + .map_err(|_| PrivateDocumentEnvelopeError::DecryptionFailed) } #[cfg(test)] @@ -683,20 +764,24 @@ mod tests { let opened = open(&entry, &[secret_key(3), secret_key(2)]).expect("the second key opens it"); - assert_eq!(opened.recipient_key_index, Some(1)); - assert_eq!(opened.recipient_public_key, public_key(2)); - assert_eq!(opened.recipient_identity_id, RECIPIENT_IDENTITY); - assert_eq!(opened.auth_mode, PrivateDocumentAuthMode::DeniableMac); - assert_eq!(opened.sender_identity_id, SENDER_IDENTITY); - assert_eq!(opened.sender_key_id, 4); - assert_eq!(opened.payload, payload()); + assert_eq!(opened.recipient_key_index(), Some(1)); + assert_eq!(opened.recipient_public_key(), &public_key(2)); + assert_eq!(opened.recipient_identity_id(), &RECIPIENT_IDENTITY); + assert_eq!(opened.auth_mode(), PrivateDocumentAuthMode::DeniableMac); + assert_eq!(opened.sender_identity_id(), &SENDER_IDENTITY); + assert_eq!(opened.sender_key_id(), 4); + assert_eq!(opened.payload(), payload().as_slice()); opened .verify_sender(&public_key(1), &secret_key(2)) .expect("the sender's key wrote the MAC"); assert!(matches!( opened.verify_sender(&public_key(5), &secret_key(2)), - Err(CryptoError::PrivateDocumentSenderNotAuthenticated) + Err(PrivateDocumentEnvelopeError::SenderNotAuthenticated) + )); + assert!(matches!( + opened.verify_sender(&public_key(1), &secret_key(3)), + Err(PrivateDocumentEnvelopeError::SenderNotAuthenticated) )); } @@ -713,13 +798,13 @@ mod tests { 9, ); let opened = open(&entry, &[secret_key(2)]).expect("it opens"); - assert_eq!(opened.auth_mode, PrivateDocumentAuthMode::Signature); + assert_eq!(opened.auth_mode(), PrivateDocumentAuthMode::Signature); opened .verify_sender(&public_key(1), &secret_key(2)) .expect("the sender's key signed it"); assert!(matches!( opened.verify_sender(&public_key(5), &secret_key(2)), - Err(CryptoError::PrivateDocumentSenderNotAuthenticated) + Err(PrivateDocumentEnvelopeError::SenderNotAuthenticated) )); } @@ -728,13 +813,13 @@ mod tests { fn should_open_an_anonymous_entry_without_a_sender() { let entry = seal(&PrivateDocumentSender::Anonymous, 9); let opened = open(&entry, &[secret_key(2)]).expect("it opens"); - assert_eq!(opened.auth_mode, PrivateDocumentAuthMode::Anonymous); - assert_eq!(opened.sender_identity_id, [0; 32]); - assert_eq!(opened.sender_key_id, 0); - assert_eq!(opened.payload, payload()); + assert_eq!(opened.auth_mode(), PrivateDocumentAuthMode::Anonymous); + assert_eq!(opened.sender_identity_id(), &[0; 32]); + assert_eq!(opened.sender_key_id(), 0); + assert_eq!(opened.payload(), payload().as_slice()); assert!(matches!( opened.verify_sender(&public_key(1), &secret_key(2)), - Err(CryptoError::AnonymousPrivateDocumentSender) + Err(PrivateDocumentEnvelopeError::AnonymousSender) )); } @@ -784,7 +869,7 @@ mod tests { let entry = seal(&deniable_mac_sender(&sender_key), 9); assert!(matches!( open_private_document_entry(&entry, &target(), &[0xC0; 32], &[secret_key(2)]), - Err(CryptoError::WrongPrivateDocumentRecipient) + Err(PrivateDocumentEnvelopeError::WrongRecipient) )); } @@ -799,15 +884,17 @@ mod tests { recover_sent_private_document_entry(&entry, &target(), &outgoing_viewing_key()) .expect("well formed") .expect("the sender built it"); - assert_eq!(recovered.recipient_key_index, None); - assert_eq!(recovered.recipient_public_key, public_key(2)); - assert_eq!(recovered.payload, payload()); + assert_eq!(recovered.recipient_key_index(), None); + assert_eq!(recovered.recipient_public_key(), &public_key(2)); + assert_eq!(recovered.payload(), payload().as_slice()); + let opened = open(&entry, &[secret_key(2)]).expect("it opens"); assert_eq!( - recovered, OpenedPrivateDocumentEntry { - recipient_key_index: None, - ..open(&entry, &[secret_key(2)]).expect("it opens") - } + recipient_key_index: Some(0), + ..recovered.clone() + }, + opened, + "the sender recovers what the recipient opens" ); let other_sender = private_document_outgoing_viewing_key(&[0x1F; 32]); @@ -825,40 +912,51 @@ mod tests { ); } - /// An entry holds a payload of at most its size minus 299 bytes. + /// An entry holds a payload of at most its size minus 299 bytes: a larger payload is refused, + /// an entry smaller than the envelope is refused for its size, and the smallest entry, 299 + /// bytes, carries an empty payload. #[test] fn should_refuse_a_payload_the_entry_cannot_hold() { assert_eq!(PRIVATE_DOCUMENT_ENVELOPE_WRAPPER_LEN, 162); assert_eq!(PRIVATE_DOCUMENT_ENVELOPE_BODY_HEADER_LEN, 137); assert_eq!(PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN, 299); - for (entry_size, payload_len, capacity) in [ - (ENTRY_SIZE, LARGEST_PAYLOAD + 1, LARGEST_PAYLOAD), - (298, 0, 0), - ] { - assert!( - matches!( - seal_private_document_entry( - &target(), - entry_size, - &PrivateDocumentRecipient { - identity_id: RECIPIENT_IDENTITY, - public_key: &public_key(2), - }, - &PrivateDocumentSender::Anonymous, - &vec![1; payload_len], - &outgoing_viewing_key(), - &[9; 32], - ), - Err(CryptoError::PrivateDocumentPayloadTooLarge { payload_len: refused, capacity: held }) - if refused == payload_len && held == capacity - ), - "{payload_len} bytes in {entry_size}" - ); - } - assert!(matches!( + let seal_into = |entry_size: usize, payload: &[u8]| { + seal_private_document_entry( + &target(), + entry_size, + &PrivateDocumentRecipient { + identity_id: RECIPIENT_IDENTITY, + public_key: &public_key(2), + }, + &PrivateDocumentSender::Anonymous, + payload, + &outgoing_viewing_key(), + &[9; 32], + ) + }; + assert_eq!( + seal_into(ENTRY_SIZE, &vec![1; LARGEST_PAYLOAD + 1]), + Err(PrivateDocumentEnvelopeError::PayloadTooLarge { + payload_len: LARGEST_PAYLOAD + 1, + capacity: LARGEST_PAYLOAD, + }) + ); + assert_eq!( + seal_into(298, &[]), + Err(PrivateDocumentEnvelopeError::InvalidEntryLength(298)) + ); + let smallest = seal_into(299, &[]).expect("an empty payload fills the smallest entry"); + assert_eq!(smallest.len(), 299); + assert_eq!( + open(&smallest, &[secret_key(2)]) + .expect("it opens") + .payload(), + &[] as &[u8] + ); + assert_eq!( open_private_document_entry(&[0; 298], &target(), &RECIPIENT_IDENTITY, &[]), - Err(CryptoError::InvalidPrivateDocumentEntryLength(298)) - )); + Err(PrivateDocumentEnvelopeError::InvalidEntryLength(298)) + ); } /// A body no sender of this version writes is refused once it decrypts: another version, @@ -879,7 +977,7 @@ mod tests { other_version[0] = 2; assert!(matches!( parse(&other_version), - Err(CryptoError::UnsupportedPrivateDocumentEnvelopeVersion(2)) + Err(PrivateDocumentEnvelopeError::UnsupportedVersion(2)) )); for (position, value) in [ (1, 3u8), // auth mode @@ -893,7 +991,7 @@ mod tests { assert!( matches!( parse(&body), - Err(CryptoError::MalformedPrivateDocumentEntry(_)) + Err(PrivateDocumentEnvelopeError::Malformed(_)) ), "byte {position}" ); diff --git a/packages/rs-sdk/src/platform/private_document_envelope_tests.rs b/packages/rs-sdk/src/platform/private_document_envelope_tests.rs index a4ad6ea0250..f27c0d23c6c 100644 --- a/packages/rs-sdk/src/platform/private_document_envelope_tests.rs +++ b/packages/rs-sdk/src/platform/private_document_envelope_tests.rs @@ -149,7 +149,7 @@ fn should_carry_the_largest_payload_in_an_entry_of_the_minimum_size() { opened .verify_sender(&PublicKey::from_secret_key(&sender_key), &recipient_key) .expect("from the sender"); - let decoded = decode_private_document_payload(request, &opened.payload, platform_version) + let decoded = decode_private_document_payload(request, opened.payload(), platform_version) .expect("decodes"); assert_eq!( decoded.get("accountLabel"), From fad9c53947d919bfeee4e35ff1de79a6dfb9f0ef Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Sun, 8 Nov 2026 04:51:53 +0700 Subject: [PATCH 08/11] fix(dpp): refuse a private payload whose objects hold bytes their members do not read The document reader reads an object's whole length-framed body but not whether its members used all of it, so a payload written under a version of a private type with more object members, read with an older type, lost them silently and validated. decode_private_document_payload now walks the payload's object frames first (refuse_unread_object_bytes): values are read by the reader's own read_optionally_from, only the frames are opened here, and an object with bytes left over is refused, so a reader with a stale contract refetches it. Optional members missing at an object's or the type's end still read as absent, and the shipped reader is unchanged. A test writes under a type that gained a member in its object and a property at its end, and checks the older type refuses both payloads while the newer reads them. Co-Authored-By: Claude Opus 5.5 --- .../document_type/private_document.rs | 128 +++++++++++++++++- 1 file changed, 122 insertions(+), 6 deletions(-) diff --git a/packages/rs-dpp/src/data_contract/document_type/private_document.rs b/packages/rs-dpp/src/data_contract/document_type/private_document.rs index 9c129fe8efa..a63c3bae5c4 100644 --- a/packages/rs-dpp/src/data_contract/document_type/private_document.rs +++ b/packages/rs-dpp/src/data_contract/document_type/private_document.rs @@ -17,9 +17,11 @@ use crate::document::serialization_traits::DocumentPlatformConversionMethodsV0; use crate::document::DocumentV0; use crate::ProtocolError; use indexmap::IndexMap; +use integer_encoding::VarIntReader; use platform_value::Value; use platform_version::version::PlatformVersion; use std::collections::BTreeMap; +use std::io::{BufReader, Read}; use std::num::NonZeroU32; /// What a document type's `private` keyword declares (`{ "entrySize": n }`). Built only by the @@ -255,19 +257,90 @@ pub fn encode_private_document_payload( }) } +/// Walks `fields` over `buf` as a document's reader frames them, and refuses an object whose +/// body holds bytes its members do not read. The reader reads an object's whole length-framed +/// body but not whether its members used all of it, so a payload written under a version of the +/// type with more members than the reader's would lose them silently. Each value is read by +/// the reader's own `read_optionally_from`; only the object frames are opened here. Optional +/// members missing at the end of an object, or of the type, are absent, as the reader reads them. +fn refuse_unread_object_bytes( + fields: &IndexMap, + buf: &mut BufReader<&[u8]>, + top_level: bool, +) -> Result<(), ProtocolError> { + let unread = |path: &str| { + ProtocolError::DecodingError(format!( + "the object {path} of a private document payload holds bytes its members do not \ + read: the payload was written under a version of the type with more members; \ + refetch the contract" + )) + }; + for (name, field) in fields { + // A private type refuses `requiredSince`, so a property is required at every version. + let required = if top_level { + field.required && !field.transient + } else { + field.required + }; + let DocumentPropertyType::Object(members) = &field.property_type else { + let (_, finished) = field.property_type.read_optionally_from(buf, required)?; + if finished { + return Ok(()); + } + continue; + }; + if !required { + let mut marker = [0u8; 1]; + if buf.read(&mut marker).map_err(|_| unread(name))? == 0 { + return Ok(()); + } + if marker[0] == 0 { + continue; + } + } + let object_len: usize = buf.read_varint().map_err(|_| { + ProtocolError::DecodingError(format!( + "the object {name} of a private document payload has no length" + )) + })?; + let mut body = Vec::new(); + buf.by_ref() + .take(object_len as u64) + .read_to_end(&mut body) + .map_err(|_| unread(name))?; + if body.len() != object_len { + return Err(ProtocolError::DecodingError(format!( + "the object {name} of a private document payload is cut short" + ))); + } + let mut object = BufReader::new(body.as_slice()); + refuse_unread_object_bytes(members, &mut object, false)?; + if object.read(&mut [0u8; 1]).map_err(|_| unread(name))? > 0 { + return Err(unread(name)); + } + } + Ok(()) +} + /// The properties a private document payload of `document_type` holds, read as a document's -/// reader reads them after its system fields: a value cut short, or a byte after the last -/// property, is refused. An entry is immutable while its type can gain optional properties, at -/// the end of the type or of one of its objects, so a payload written before them ends before -/// them, and reads them as absent. The schema's bounds are not checked here, so a recipient -/// validates the properties against the type before trusting them -/// (`DataContract::validate_document_properties`). +/// reader reads them after its system fields: a value cut short, a byte after the last property, +/// or a byte inside an object its members do not read, is refused. An entry is immutable while +/// its type can gain optional properties, at the end of the type or of one of its objects, so a +/// payload written before them ends before them and reads them as absent, while one written after +/// them is refused by a reader that does not know them, which should refetch the contract. The +/// schema's bounds are not checked here, so a recipient validates the properties against the type +/// before trusting them (`DataContract::validate_document_properties`). pub fn decode_private_document_payload( document_type: DocumentTypeRef, payload: &[u8], platform_version: &PlatformVersion, ) -> Result, ProtocolError> { refuse_a_public_type(document_type)?; + refuse_unread_object_bytes( + document_type.properties(), + &mut BufReader::new(payload), + true, + )?; let mut serialized = private_document_payload_prefix().to_vec(); serialized.extend_from_slice(payload); Ok(DocumentV0::from_bytes(&serialized, document_type, platform_version)?.properties) @@ -844,6 +917,49 @@ mod tests { platform_version ) .is_err()); + + // The other way round: a payload written after the type gained them, read with the + // older type, holds members that type does not know. Inside the object, where the + // document reader would drop them silently, or at the type's end, it is refused, so a + // reader holding a stale contract refetches it rather than read part of the entry. + let older = before.document_type_for_name("secret").expect("the type"); + for (case, properties) in [ + ( + "a member the object gained", + BTreeMap::from([ + ("flag".to_string(), Value::Bool(true)), + ( + "meta".to_string(), + Value::Map(vec![ + (Value::Text("a".to_string()), Value::U64(7)), + (Value::Text("b".to_string()), Value::Bool(true)), + ]), + ), + ]), + ), + ( + "a property the type gained", + BTreeMap::from([ + ("flag".to_string(), Value::Bool(true)), + ( + "meta".to_string(), + Value::Map(vec![(Value::Text("a".to_string()), Value::U64(7))]), + ), + ("extra".to_string(), Value::Bool(true)), + ]), + ), + ] { + let newer_payload = + encode_private_document_payload(newer, properties).expect("encodes"); + assert!( + decode_private_document_payload(newer, &newer_payload, platform_version).is_ok(), + "{case}: the newer type reads it" + ); + assert!( + decode_private_document_payload(older, &newer_payload, platform_version).is_err(), + "{case}: the older type refuses it" + ); + } } /// The type's schema validates a payload's properties, before sealing and after opening: From e13eb1bac5b95e4675f62ec9175582a40657868d Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Sun, 8 Nov 2026 05:14:36 +0700 Subject: [PATCH 09/11] test(dpp): isolate a private payload's unread object bytes from the top-level trailing check The newer-payload case for an object's added member is now written under a type that gained only that member, so no top-level byte is left over for the document reader's own trailing check: the older type refuses it only through refuse_unread_object_bytes. The top-level addition stays a separate case. Co-Authored-By: Claude Opus 5.5 --- .../document_type/private_document.rs | 21 ++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/packages/rs-dpp/src/data_contract/document_type/private_document.rs b/packages/rs-dpp/src/data_contract/document_type/private_document.rs index a63c3bae5c4..5bd0ce61c69 100644 --- a/packages/rs-dpp/src/data_contract/document_type/private_document.rs +++ b/packages/rs-dpp/src/data_contract/document_type/private_document.rs @@ -921,11 +921,21 @@ mod tests { // The other way round: a payload written after the type gained them, read with the // older type, holds members that type does not know. Inside the object, where the // document reader would drop them silently, or at the type's end, it is refused, so a - // reader holding a stale contract refetches it rather than read part of the entry. + // reader holding a stale contract refetches it rather than read part of the entry. The + // object's case is written under a type that gained only the object's member, so no + // top-level byte is left over for the reader's own trailing check to catch. let older = before.document_type_for_name("secret").expect("the type"); - for (case, properties) in [ + let object_only = private_type_contract( + json!({ "flag": { "type": "boolean", "position": 0 }, "meta": meta(true) }), + json!(["flag", "meta"]), + ); + let object_only = object_only + .document_type_for_name("secret") + .expect("the type"); + for (case, writer, properties) in [ ( "a member the object gained", + object_only, BTreeMap::from([ ("flag".to_string(), Value::Bool(true)), ( @@ -939,6 +949,7 @@ mod tests { ), ( "a property the type gained", + newer, BTreeMap::from([ ("flag".to_string(), Value::Bool(true)), ( @@ -950,10 +961,10 @@ mod tests { ), ] { let newer_payload = - encode_private_document_payload(newer, properties).expect("encodes"); + encode_private_document_payload(writer, properties).expect("encodes"); assert!( - decode_private_document_payload(newer, &newer_payload, platform_version).is_ok(), - "{case}: the newer type reads it" + decode_private_document_payload(writer, &newer_payload, platform_version).is_ok(), + "{case}: the writer's type reads it" ); assert!( decode_private_document_payload(older, &newer_payload, platform_version).is_err(), From bcc9b6a99891d51ccf962db6959ff1f4cd45efd5 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Sun, 8 Nov 2026 05:38:51 +0700 Subject: [PATCH 10/11] fix(sdk): build the envelope without getrandom, and check decoded values in the payload tests - platform-encryption takes chacha20poly1305 with only its alloc feature: the envelope supplies its own seed and nonces, so the default getrandom is unused and kept standalone wasm32 builds from compiling. - The seal docs name the refusal as it is, PrivateDocumentEnvelopeError::InvalidEphemeralSeed. - Tests compare what was decoded with what was written: every property of the sealed DashPay-shaped payload, the integer under each contract config, and an over-long label that reads back whole and is refused by the schema after decoding. Co-Authored-By: Claude Opus 5.5 --- .../document_type/private_document.rs | 22 +++++++++++++++++-- packages/rs-platform-encryption/Cargo.toml | 4 +++- .../src/private_document_envelope.rs | 2 +- .../private_document_envelope_tests.rs | 6 ++--- 4 files changed, 27 insertions(+), 7 deletions(-) diff --git a/packages/rs-dpp/src/data_contract/document_type/private_document.rs b/packages/rs-dpp/src/data_contract/document_type/private_document.rs index 5bd0ce61c69..754022a5561 100644 --- a/packages/rs-dpp/src/data_contract/document_type/private_document.rs +++ b/packages/rs-dpp/src/data_contract/document_type/private_document.rs @@ -759,6 +759,13 @@ mod tests { Some(&Value::Text(wide(4))), "{config}" ); + assert_eq!( + decoded + .get("small") + .map(|small| small.to_integer::().expect("an integer")), + Some(255), + "{config}" + ); } } @@ -993,10 +1000,21 @@ mod tests { ) .expect("validation runs") }; - assert!(validate(largest_values()).is_valid()); + let secret = contract + .document_type_for_name("secret") + .expect("the secret type"); + let round_trip = |properties: BTreeMap| { + let payload = encode_private_document_payload(secret, properties).expect("encodes"); + decode_private_document_payload(secret, &payload, platform_version).expect("decodes") + }; + assert!(validate(round_trip(largest_values())).is_valid()); + // The codec does not check bounds: a label over its bound is written and read back + // whole, and the schema refuses what the recipient decoded. let mut too_long = largest_values(); too_long.insert("label".to_string(), Value::Text(wide(11))); - assert!(!validate(too_long).is_valid()); + let decoded = round_trip(too_long); + assert_eq!(decoded.get("label"), Some(&Value::Text(wide(11)))); + assert!(!validate(decoded).is_valid()); } /// Integers take the width the contract's documents store them in: with sized integer diff --git a/packages/rs-platform-encryption/Cargo.toml b/packages/rs-platform-encryption/Cargo.toml index 4f3a689792c..369b0d94e88 100644 --- a/packages/rs-platform-encryption/Cargo.toml +++ b/packages/rs-platform-encryption/Cargo.toml @@ -14,7 +14,9 @@ description = "Cryptographic utilities for Dash Platform (DIP-15 DashPay encrypt secp256k1 = { version = "0.33.1", features = ["std", "recovery"] } aes = "0.8" cbc = "0.1" -chacha20poly1305 = "0.10" +# The envelope supplies its own seed and nonces, so no `getrandom`: standalone wasm32 builds +# without a JavaScript randomness backend still compile. +chacha20poly1305 = { version = "0.10", default-features = false, features = ["alloc"] } hmac = "0.12" sha2 = "0.10" thiserror = "1.0" diff --git a/packages/rs-platform-encryption/src/private_document_envelope.rs b/packages/rs-platform-encryption/src/private_document_envelope.rs index c09fb1f2489..495a5b29382 100644 --- a/packages/rs-platform-encryption/src/private_document_envelope.rs +++ b/packages/rs-platform-encryption/src/private_document_envelope.rs @@ -300,7 +300,7 @@ pub fn private_document_outgoing_viewing_key(wallet_secret: &[u8; 32]) -> [u8; 3 /// `esk_seed` must be 32 fresh random bytes for every entry built, never reused, not even on a /// retry: the entry's keys are derived from it, and a zero nonce is safe only because each key /// encrypts once. A seed whose hash is not a valid secret key (a chance of about 2^-128) is -/// refused with `InvalidPrivateDocumentEphemeralSeed`; draw another. +/// refused with [`PrivateDocumentEnvelopeError::InvalidEphemeralSeed`]; draw another. pub fn seal_private_document_entry( target: &PrivateDocumentTarget, entry_size: usize, diff --git a/packages/rs-sdk/src/platform/private_document_envelope_tests.rs b/packages/rs-sdk/src/platform/private_document_envelope_tests.rs index f27c0d23c6c..d0edc5c1d3c 100644 --- a/packages/rs-sdk/src/platform/private_document_envelope_tests.rs +++ b/packages/rs-sdk/src/platform/private_document_envelope_tests.rs @@ -112,7 +112,7 @@ fn should_carry_the_largest_payload_in_an_entry_of_the_minimum_size() { ("autoAcceptProof".to_string(), Value::Bytes(vec![2; 102])), ("shieldedAddress".to_string(), Value::Bytes(vec![3; 43])), ]); - let payload = encode_private_document_payload(request, properties).expect("encodes"); + let payload = encode_private_document_payload(request, properties.clone()).expect("encodes"); assert_eq!( payload.len(), entry_size - PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN @@ -152,7 +152,7 @@ fn should_carry_the_largest_payload_in_an_entry_of_the_minimum_size() { let decoded = decode_private_document_payload(request, opened.payload(), platform_version) .expect("decodes"); assert_eq!( - decoded.get("accountLabel"), - Some(&Value::Text("a".repeat(63))) + decoded, properties, + "every property reads back as it was sealed" ); } From 488066dce7b61ce8cf624395a24b3d111cb684fa Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Sun, 8 Nov 2026 09:41:13 +0700 Subject: [PATCH 11/11] feat(sdk): verify a signed entry without a recipient key, and prepare scan keys once - OpenedPrivateDocumentEntry::verify_sender takes the recipient's secret key as an Option: a deniable MAC needs it (refused with RecipientSecretKeyRequired without), a signature only the sender's key, so a sender checks its own recovered entry with None. - PrivateDocumentRecipientKeys derives and serializes each of a wallet's decryption keys once, for a scan opening many entries, in their order; open_private_document_entry prepares them for one entry. Tests: a signed entry verifies with None, on both sides; a MAC without the recipient key is refused; prepared keys open every entry as the function does and report the same index. Co-Authored-By: Claude Opus 5.5 --- packages/rs-platform-encryption/src/lib.rs | 6 +- .../src/private_document_envelope.rs | 178 +++++++++++++----- .../private_document_envelope_tests.rs | 5 +- 3 files changed, 141 insertions(+), 48 deletions(-) diff --git a/packages/rs-platform-encryption/src/lib.rs b/packages/rs-platform-encryption/src/lib.rs index da3590412cf..4cf5a00c44e 100644 --- a/packages/rs-platform-encryption/src/lib.rs +++ b/packages/rs-platform-encryption/src/lib.rs @@ -44,7 +44,7 @@ pub use private_document_envelope::{ open_private_document_entry, private_document_outgoing_viewing_key, recover_sent_private_document_entry, seal_private_document_entry, OpenedPrivateDocumentEntry, PrivateDocumentAuthMode, PrivateDocumentEnvelopeError, PrivateDocumentRecipient, - PrivateDocumentSender, PrivateDocumentTarget, PRIVATE_DOCUMENT_ENVELOPE_BODY_HEADER_LEN, - PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN, PRIVATE_DOCUMENT_ENVELOPE_VERSION, - PRIVATE_DOCUMENT_ENVELOPE_WRAPPER_LEN, + PrivateDocumentRecipientKeys, PrivateDocumentSender, PrivateDocumentTarget, + PRIVATE_DOCUMENT_ENVELOPE_BODY_HEADER_LEN, PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN, + PRIVATE_DOCUMENT_ENVELOPE_VERSION, PRIVATE_DOCUMENT_ENVELOPE_WRAPPER_LEN, }; diff --git a/packages/rs-platform-encryption/src/private_document_envelope.rs b/packages/rs-platform-encryption/src/private_document_envelope.rs index 495a5b29382..7ecfb08d198 100644 --- a/packages/rs-platform-encryption/src/private_document_envelope.rs +++ b/packages/rs-platform-encryption/src/private_document_envelope.rs @@ -88,6 +88,9 @@ pub enum PrivateDocumentEnvelopeError { #[error("the private document entry's sender authentication does not verify")] SenderNotAuthenticated, + + #[error("a deniable MAC is checked with the recipient's secret key, and none was given")] + RecipientSecretKeyRequired, } /// The envelope version this module builds and opens. @@ -251,17 +254,21 @@ impl OpenedPrivateDocumentEntry { /// Checks that the key the entry names wrote it: `sender_public_key` is the key the sender /// identity holds under `sender_key_id`, as it was when the entry was written (keys are /// disabled, never removed). A deniable MAC is checked with the recipient's own secret key, - /// the one that opened the entry; a signature needs only the sender's key. + /// the one that opened the entry, and is refused with `RecipientSecretKeyRequired` without + /// it; a signature needs only the sender's key, so a sender checks its own recovered entry + /// with `None`. pub fn verify_sender( &self, sender_public_key: &PublicKey, - recipient_secret_key: &SecretKey, + recipient_secret_key: Option<&SecretKey>, ) -> Result<(), PrivateDocumentEnvelopeError> { match self.auth_mode { PrivateDocumentAuthMode::Anonymous => { Err(PrivateDocumentEnvelopeError::AnonymousSender) } PrivateDocumentAuthMode::DeniableMac => { + let recipient_secret_key = recipient_secret_key + .ok_or(PrivateDocumentEnvelopeError::RecipientSecretKeyRequired)?; let mac_key = mac_key(&shared_point(recipient_secret_key, sender_public_key)); let mut mac = as Mac>::new_from_slice(&mac_key) .expect("HMAC takes a key of any length"); @@ -405,48 +412,85 @@ pub fn seal_private_document_entry( Ok(entry) } -/// Opens `entry` of the private document type `target` with the first of -/// `recipient_secret_keys` it is encrypted to, for the identity `recipient_identity_id`. -/// -/// `Ok(None)` when it is for none of the keys, the case of nearly every entry a wallet scans: -/// a key whose decryption fails, or whose commitment does not match, is passed over for the -/// next. An entry that opens but is malformed, or names another recipient identity, is refused -/// with an error. The sender is not yet checked: see -/// [`OpenedPrivateDocumentEntry::verify_sender`]. +/// A wallet's decryption keys, prepared to open many entries: each key's public key is derived +/// and serialized once, rather than for every entry a scan tries, which for nearly every entry +/// opens none. The keys keep their order, which [`OpenedPrivateDocumentEntry::recipient_key_index`] +/// reports. +pub struct PrivateDocumentRecipientKeys { + keys: Vec<(SecretKey, PublicKey, [u8; 33])>, +} + +impl PrivateDocumentRecipientKeys { + pub fn new(secret_keys: &[SecretKey]) -> Self { + Self { + keys: secret_keys + .iter() + .map(|secret_key| { + let public_key = PublicKey::from_secret_key(secret_key); + (*secret_key, public_key, public_key.serialize()) + }) + .collect(), + } + } + + /// Opens `entry` of the private document type `target` with the first of these keys it is + /// encrypted to, for the identity `recipient_identity_id`. + /// + /// `Ok(None)` when it is for none of the keys, the case of nearly every entry a wallet scans: + /// a key whose decryption fails, or whose commitment does not match, is passed over for the + /// next. An entry that opens but is malformed, or names another recipient identity, is + /// refused with an error. The sender is not yet checked: see + /// [`OpenedPrivateDocumentEntry::verify_sender`]. + pub fn open( + &self, + entry: &[u8], + target: &PrivateDocumentTarget, + recipient_identity_id: &[u8; 32], + ) -> Result, PrivateDocumentEnvelopeError> { + let parts = EntryParts::split(entry)?; + let Ok(epk) = PublicKey::from_slice(parts.epk) else { + // No key opens an entry whose ephemeral key is not a point. + return Ok(None); + }; + for (index, (secret_key, recipient_public_key, recipient_key)) in + self.keys.iter().enumerate() + { + let key = entry_key(&shared_point(secret_key, &epk), parts.epk, recipient_key); + let Ok(body) = decrypt(&key, parts.commitment, parts.body_ct) else { + continue; + }; + if commitment(&key, target, recipient_key, &body) != *parts.commitment { + continue; + } + let opened = parse_body( + &body, + target, + *parts.commitment, + *recipient_public_key, + Some(index), + )?; + if opened.recipient_identity_id != *recipient_identity_id { + return Err(PrivateDocumentEnvelopeError::WrongRecipient); + } + return Ok(Some(opened)); + } + Ok(None) + } +} + +/// [`PrivateDocumentRecipientKeys::open`] with keys prepared for this one entry; a scan of many +/// entries prepares them once instead. pub fn open_private_document_entry( entry: &[u8], target: &PrivateDocumentTarget, recipient_identity_id: &[u8; 32], recipient_secret_keys: &[SecretKey], ) -> Result, PrivateDocumentEnvelopeError> { - let parts = EntryParts::split(entry)?; - let Ok(epk) = PublicKey::from_slice(parts.epk) else { - // No key opens an entry whose ephemeral key is not a point. - return Ok(None); - }; - for (index, secret_key) in recipient_secret_keys.iter().enumerate() { - let recipient_public_key = PublicKey::from_secret_key(secret_key); - let recipient_key = recipient_public_key.serialize(); - let key = entry_key(&shared_point(secret_key, &epk), parts.epk, &recipient_key); - let Ok(body) = decrypt(&key, parts.commitment, parts.body_ct) else { - continue; - }; - if commitment(&key, target, &recipient_key, &body) != *parts.commitment { - continue; - } - let opened = parse_body( - &body, - target, - *parts.commitment, - recipient_public_key, - Some(index), - )?; - if opened.recipient_identity_id != *recipient_identity_id { - return Err(PrivateDocumentEnvelopeError::WrongRecipient); - } - return Ok(Some(opened)); - } - Ok(None) + PrivateDocumentRecipientKeys::new(recipient_secret_keys).open( + entry, + target, + recipient_identity_id, + ) } /// Recovers `entry` of the private document type `target` that the holder of @@ -773,16 +817,20 @@ mod tests { assert_eq!(opened.payload(), payload().as_slice()); opened - .verify_sender(&public_key(1), &secret_key(2)) + .verify_sender(&public_key(1), Some(&secret_key(2))) .expect("the sender's key wrote the MAC"); assert!(matches!( - opened.verify_sender(&public_key(5), &secret_key(2)), + opened.verify_sender(&public_key(5), Some(&secret_key(2))), Err(PrivateDocumentEnvelopeError::SenderNotAuthenticated) )); assert!(matches!( - opened.verify_sender(&public_key(1), &secret_key(3)), + opened.verify_sender(&public_key(1), Some(&secret_key(3))), Err(PrivateDocumentEnvelopeError::SenderNotAuthenticated) )); + assert_eq!( + opened.verify_sender(&public_key(1), None), + Err(PrivateDocumentEnvelopeError::RecipientSecretKeyRequired) + ); } /// A signed entry is checked against the sender's key alone. @@ -800,12 +848,22 @@ mod tests { let opened = open(&entry, &[secret_key(2)]).expect("it opens"); assert_eq!(opened.auth_mode(), PrivateDocumentAuthMode::Signature); opened - .verify_sender(&public_key(1), &secret_key(2)) + .verify_sender(&public_key(1), Some(&secret_key(2))) .expect("the sender's key signed it"); assert!(matches!( - opened.verify_sender(&public_key(5), &secret_key(2)), + opened.verify_sender(&public_key(5), Some(&secret_key(2))), Err(PrivateDocumentEnvelopeError::SenderNotAuthenticated) )); + // A signature needs no recipient key: the sender checks its own recovered entry with + // `None`, and the recipient may too. + opened + .verify_sender(&public_key(1), None) + .expect("the signature needs only the sender's key"); + recover_sent_private_document_entry(&entry, &target(), &outgoing_viewing_key()) + .expect("well formed") + .expect("the sender built it") + .verify_sender(&public_key(1), None) + .expect("the sender checks its recovered entry with its own key alone"); } /// An anonymous entry names no sender, and there is nothing to check. @@ -818,11 +876,43 @@ mod tests { assert_eq!(opened.sender_key_id(), 0); assert_eq!(opened.payload(), payload().as_slice()); assert!(matches!( - opened.verify_sender(&public_key(1), &secret_key(2)), + opened.verify_sender(&public_key(1), Some(&secret_key(2))), Err(PrivateDocumentEnvelopeError::AnonymousSender) )); } + /// Keys prepared once open every entry of a scan as the single-entry function does, and keep + /// their order in the index they report. + #[test] + fn should_open_entries_with_keys_prepared_once() { + let sender_key = secret_key(1); + let keys = [secret_key(3), secret_key(2)]; + let prepared = PrivateDocumentRecipientKeys::new(&keys); + let entries = [ + seal(&deniable_mac_sender(&sender_key), 9), + seal(&PrivateDocumentSender::Anonymous, 10), + ]; + for entry in &entries { + let opened = prepared + .open(entry, &target(), &RECIPIENT_IDENTITY) + .expect("well formed") + .expect("for the second key"); + assert_eq!(opened.recipient_key_index(), Some(1)); + assert_eq!( + Some(opened), + open(entry, &keys), + "prepared keys open the entry as the function does" + ); + } + let others = PrivateDocumentRecipientKeys::new(&[secret_key(4)]); + assert_eq!( + others + .open(&entries[0], &target(), &RECIPIENT_IDENTITY) + .expect("well formed"), + None + ); + } + /// Nearly every entry a wallet scans is for someone else: it is passed over, not refused. #[test] fn should_pass_over_an_entry_for_other_keys() { diff --git a/packages/rs-sdk/src/platform/private_document_envelope_tests.rs b/packages/rs-sdk/src/platform/private_document_envelope_tests.rs index d0edc5c1d3c..71452a9f365 100644 --- a/packages/rs-sdk/src/platform/private_document_envelope_tests.rs +++ b/packages/rs-sdk/src/platform/private_document_envelope_tests.rs @@ -147,7 +147,10 @@ fn should_carry_the_largest_payload_in_an_entry_of_the_minimum_size() { .expect("well formed") .expect("for the recipient"); opened - .verify_sender(&PublicKey::from_secret_key(&sender_key), &recipient_key) + .verify_sender( + &PublicKey::from_secret_key(&sender_key), + Some(&recipient_key), + ) .expect("from the sender"); let decoded = decode_private_document_payload(request, opened.payload(), platform_version) .expect("decodes");