Skip to main content

Crate platform_encryption

Crate platform_encryption 

Source
Expand description

Cryptographic utilities for Dash Platform (DIP-15)

This crate implements the Diffie-Hellman key exchange and encryption/decryption operations as specified in DIP-15 for secure communication between Dash identities.

The DIP-15 surface is split by concern:

  • [ecdh] — ECDH shared-secret derivation.
  • [aes] — AES-256-CBC primitives shared by the encrypted fields.
  • [compact_xpub] — the 69-byte compact xpub (encryptedPublicKey) + its encryption.
  • [account_label] — encryptedAccountLabel.
  • [contact_info] — contactInfo (encToUserId + privateData).
  • [account_reference] — the masked accountReference.
  • [private_document_envelope] — the standard private document envelope (version 1).
  • [shielded_address]: encryptedShieldedAddress and the per-contact index rule.
  • [error] — the shared CryptoError.

Every public item is re-exported at the crate root, so the API is flat (platform_encryption::derive_shared_key_ecdh, etc.) regardless of module.

Structs§

CompactXpub
The three components of a DIP-15 compact extended public key.
OpenedPrivateDocumentEntry
An entry its recipient opened, or its sender recovered.
PrivateDocumentRecipient
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.
PrivateDocumentRecipientKeys
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.
PrivateDocumentTarget
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.

Enums§

CryptoError
Errors that can occur during cryptographic operations
PrivateDocumentAuthMode
The authentication an opened entry carries.
PrivateDocumentEnvelopeError
Why an entry could not be built, opened, recovered or checked.
PrivateDocumentSender
How an entry tells its recipient who wrote it.

Constants§

ACCOUNT_REFERENCE_VERSION_SHIFT
Bit position of the rotation version in a masked accountReference: the top 4 bits carry the version, the low 28 bits the masked account index.
COMPACT_XPUB_LEN
Length of the DIP-15 compact extended-public-key plaintext, in bytes.
ENCRYPTED_SHIELDED_ADDRESS_LEN
encryptedShieldedAddress as this module writes it: a 16-byte IV followed by the three AES blocks a 43-byte address pads to. The contract also admits 80 bytes, kept for a later encoding, which decrypt_shielded_address refuses.
PRIVATE_DOCUMENT_ENVELOPE_BODY_HEADER_LEN
The bytes of the body before the payload.
PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN
Every byte of an entry besides its payload: 299. An entry holds a payload of at most its size minus this.
PRIVATE_DOCUMENT_ENVELOPE_VERSION
The envelope version this module builds and opens.
PRIVATE_DOCUMENT_ENVELOPE_WRAPPER_LEN
The bytes around the encrypted body: the commitment, the ephemeral key, the body’s tag and the sender-recovery ciphertext.
SHIELDED_ADDRESS_LEN
A raw shielded payment address: an 11-byte diversifier followed by a 32-byte diversified transmission key.
SHIELDED_DIVERSIFIER_INDEX_LEN
A diversifier index: an 88-bit little-endian integer.
SHIELDED_FULL_VIEWING_KEY_LEN
A raw full viewing key of a shielded account: ak || nk || rivk.

Functions§

account_reference_version
Rotation version of a masked accountReference. Unlike unmask_account_reference it needs no secret: the version bits are not masked, so any party can tell whether a request is a re-key (version > 0).
calculate_account_reference
Calculate the masked DIP-15 accountReference: result = (version << 28) | (ASK28 ^ (account_index & 0x0FFF_FFFF)).
compact_xpub_bytes
Assemble the DIP-15 compact extended-public-key plaintext from its three components. Thin wrapper over CompactXpub::to_bytes kept for call sites that have the components loose rather than in a struct.
decrypt_account_label
Decrypt an account label from DashPay (DIP-15)
decrypt_aes_256_cbc
Decrypt data using CBC-AES-256
decrypt_enc_to_user_id
Decrypt a 32-byte contactInfo.encToUserId ciphertext (inverse of encrypt_enc_to_user_id).
decrypt_extended_public_key
Decrypt an extended public key from DashPay contact requests (DIP-15)
decrypt_private_data
Decrypt a contactInfo.privateData blob (inverse of encrypt_private_data).
decrypt_shielded_address
Decrypt a contact request’s encryptedShieldedAddress to the 43 bytes it carries.
derive_shared_key_ecdh
Derive a shared secret key using ECDH as specified in DIP-15
encrypt_account_label
Encrypt an account label for DashPay (DIP-15)
encrypt_aes_256_cbc
Encrypt data using CBC-AES-256
encrypt_enc_to_user_id
Encrypt a 32-byte identity id with AES-256-ECB (DIP-15 contactInfo.encToUserId).
encrypt_extended_public_key
Encrypt an extended public key for DashPay contact requests (DIP-15)
encrypt_private_data
Encrypt a contactInfo.privateData plaintext (the DIP-15 var-int encoding, built by the wallet’s encode_private_data) as IV(16) ‖ AES-256-CBC(plaintext) — the same prepended-IV layout encryptedPublicKey uses (DIP-15 doesn’t pin the layout for this field; we adopt the same convention).
encrypt_shielded_address
Encrypt a shielded payment address as a contact request’s encryptedShieldedAddress: the IV, then the address under AES-256-CBC with the request’s DIP-15 shared key, the key that encrypts its encryptedPublicKey.
is_shielded_contact_index
Whether a diversifier index lies in the per-contact range (2^87 and above), where only shielded_contact_index places addresses. An index below it is a profile address or one the wallet uses for itself, never one given to a contact.
open_private_document_entry
PrivateDocumentRecipientKeys::open with keys prepared for this one entry; a scan of many entries prepares them once instead.
parse_compact_xpub
Parse a DIP-15 compact extended-public-key plaintext into a CompactXpub.
private_document_outgoing_viewing_key
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.
private_document_signing_data
What the sender of a signed entry signs, m above: an identity signer signs it as data, that is its double SHA-256. The fields are the entry’s, recipient included, so it is computed before sealing.
recover_private_document_signer
The key a compact signature of signing_data recovers to, refused with SenderNotAuthenticated when it is no signature. A signer checks its own signature with it before sealing.
recover_sent_private_document_entry
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.
seal_private_document_entry
Builds an entry of entry_size bytes carrying payload to recipient, for the private document type target.
shielded_contact_index
The diversifier index of the shielded address a contact request carries, from the request’s unique key:
shielded_contact_index_key
The key a shielded account derives its per-contact indices under: HMAC-SHA256(key = "DashPay/shielded/contact-index-key/v1", msg = full viewing key).
sign_private_document_signing_data
Signs signing_data with secret_key as a Dash identity signer does: a recoverable ECDSA signature of its double SHA-256, in the compact form.
unmask_account_reference
Recover (version, account_index) from a masked accountReference. Inverse of calculate_account_reference for the same (sender_secret_key, compact_xpub) — only the original sender can un-mask (the PRF key is their ECDH private key). Used on re-send to read the previous rotation version.