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 4c7760730e2..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 @@ -11,8 +11,17 @@ 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 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 @@ -151,6 +160,192 @@ 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() + ))), + } +} + +/// 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, 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() + }; + let serialized = document.serialize_in_format_3(document_type)?; + 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(), + ) + }) +} + +/// 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, 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) +} + #[cfg(test)] mod tests { use super::*; @@ -429,6 +624,399 @@ 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(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(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(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(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(secret, largest_values()).expect("encodes"); + + let mut trailing = payload.clone(); + trailing.push(0); + assert!(decode_private_document_payload(secret, &trailing, platform_version).is_err()); + assert!(decode_private_document_payload( + 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(note, BTreeMap::new()), + Err(ProtocolError::NotSupported(_)) + )); + assert!(matches!( + 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}" + ); + assert_eq!( + decoded + .get("small") + .map(|small| small.to_integer::().expect("an integer")), + Some(255), + "{config}" + ); + } + } + + /// 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 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. 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"); + 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)), + ( + "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", + newer, + 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(writer, properties).expect("encodes"); + assert!( + 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(), + "{case}: the older type refuses it" + ); + } + } + + /// 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") + }; + 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))); + 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 /// 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. 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-platform-encryption/Cargo.toml b/packages/rs-platform-encryption/Cargo.toml index 32c8f7a74ab..369b0d94e88 100644 --- a/packages/rs-platform-encryption/Cargo.toml +++ b/packages/rs-platform-encryption/Cargo.toml @@ -11,9 +11,12 @@ 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" +# 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" @@ -21,4 +24,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/lib.rs b/packages/rs-platform-encryption/src/lib.rs index 747c0528d0f..4cf5a00c44e 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, PrivateDocumentEnvelopeError, PrivateDocumentRecipient, + 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 new file mode 100644 index 00000000000..7ecfb08d198 --- /dev/null +++ b/packages/rs-platform-encryption/src/private_document_envelope.rs @@ -0,0 +1,1129 @@ +//! 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::ecdh::shared_secret_point; +use secp256k1::ecdsa::{RecoverableSignature, RecoveryId}; +use secp256k1::{Message, PublicKey, SecretKey}; +use sha2::{Digest, Sha256}; + +/// 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, + + #[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. +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`. 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 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 fn recipient_key_index(&self) -> Option { + self.recipient_key_index + } + + /// The key the entry is encrypted to. + 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 fn sender_identity_id(&self) -> &[u8; 32] { + &self.sender_identity_id + } + + /// Zero when the entry is anonymous. + 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 fn payload(&self) -> &[u8] { + &self.payload + } + + /// The payload, taking the entry. + pub fn into_payload(self) -> Vec { + self.payload + } + + /// 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, 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: 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"); + mac.update(&self.auth_message); + mac.verify_slice(&self.auth[..MAC_LEN]) + .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(|_| PrivateDocumentEnvelopeError::SenderNotAuthenticated)?; + let signer = signature + .recover_ecdsa(Message::from_digest(self.auth_message)) + .map_err(|_| PrivateDocumentEnvelopeError::SenderNotAuthenticated)?; + if signer == *sender_public_key { + Ok(()) + } else { + Err(PrivateDocumentEnvelopeError::SenderNotAuthenticated) + } + } + } + } +} + +/// 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 [`PrivateDocumentEnvelopeError::InvalidEphemeralSeed`]; 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, 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(|_| payload.len() <= capacity) + .ok_or(PrivateDocumentEnvelopeError::PayloadTooLarge { + 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) +} + +/// 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> { + PrivateDocumentRecipientKeys::new(recipient_secret_keys).open( + entry, + target, + recipient_identity_id, + ) +} + +/// 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, PrivateDocumentEnvelopeError> { + 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 = || 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..] + .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(PrivateDocumentEnvelopeError::InvalidEntryLength( + 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 = 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(PrivateDocumentEnvelopeError::UnsupportedVersion(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(|_| PrivateDocumentEnvelopeError::InvalidEphemeralSeed) +} + +/// `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] { + 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, PrivateDocumentEnvelopeError> { + ChaCha20Poly1305::new(Key::from_slice(key)) + .encrypt( + Nonce::from_slice(&[0; 12]), + Payload { + msg: plaintext, + aad, + }, + ) + .map_err(|_| PrivateDocumentEnvelopeError::Malformed("encryption failed")) +} + +fn decrypt( + key: &[u8; 32], + aad: &[u8; 32], + ciphertext: &[u8], +) -> Result, PrivateDocumentEnvelopeError> { + ChaCha20Poly1305::new(Key::from_slice(key)) + .decrypt( + Nonce::from_slice(&[0; 12]), + Payload { + msg: ciphertext, + aad, + }, + ) + .map_err(|_| PrivateDocumentEnvelopeError::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().as_slice()); + + opened + .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), Some(&secret_key(2))), + Err(PrivateDocumentEnvelopeError::SenderNotAuthenticated) + )); + assert!(matches!( + 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. + #[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), Some(&secret_key(2))) + .expect("the sender's key signed it"); + assert!(matches!( + 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. + #[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().as_slice()); + assert!(matches!( + 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() { + 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(PrivateDocumentEnvelopeError::WrongRecipient) + )); + } + + /// 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().as_slice()); + let opened = open(&entry, &[secret_key(2)]).expect("it opens"); + assert_eq!( + OpenedPrivateDocumentEntry { + 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]); + 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: 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); + 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(PrivateDocumentEnvelopeError::InvalidEntryLength(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(PrivateDocumentEnvelopeError::UnsupportedVersion(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(PrivateDocumentEnvelopeError::Malformed(_)) + ), + "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..71452a9f365 --- /dev/null +++ b/packages/rs-sdk/src/platform/private_document_envelope_tests.rs @@ -0,0 +1,161 @@ +//! 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(request, properties.clone()).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), + Some(&recipient_key), + ) + .expect("from the sender"); + let decoded = decode_private_document_payload(request, opened.payload(), platform_version) + .expect("decodes"); + assert_eq!( + decoded, properties, + "every property reads back as it was sealed" + ); +}