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 maskedaccountReference. - [
private_document_envelope] — the standard private document envelope (version 1). - [
shielded_address]:encryptedShieldedAddressand the per-contact index rule. - [
error] — the sharedCryptoError.
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§
- Compact
Xpub - The three components of a DIP-15 compact extended public key.
- Opened
Private Document Entry - An entry its recipient opened, or its sender recovered.
- Private
Document Recipient - 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.
- Private
Document Recipient Keys - 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_indexreports. - Private
Document Target - 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§
- Crypto
Error - Errors that can occur during cryptographic operations
- Private
Document Auth Mode - The authentication an opened entry carries.
- Private
Document Envelope Error - Why an entry could not be built, opened, recovered or checked.
- Private
Document Sender - How an entry tells its recipient who wrote it.
Constants§
- ACCOUNT_
REFERENCE_ VERSION_ SHIFT - Bit position of the rotation
versionin a maskedaccountReference: 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 encryptedShieldedAddressas 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, whichdecrypt_shielded_addressrefuses.- 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
versionof a maskedaccountReference. Unlikeunmask_account_referenceit 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_byteskept 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.encToUserIdciphertext (inverse ofencrypt_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.privateDatablob (inverse ofencrypt_private_data). - decrypt_
shielded_ address - Decrypt a contact request’s
encryptedShieldedAddressto 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.privateDataplaintext (the DIP-15 var-int encoding, built by the wallet’sencode_private_data) asIV(16) ‖ AES-256-CBC(plaintext)— the same prepended-IV layoutencryptedPublicKeyuses (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 itsencryptedPublicKey. - is_
shielded_ contact_ index - Whether a diversifier index lies in the per-contact range (2^87 and above), where
only
shielded_contact_indexplaces 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::openwith 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,
mabove: an identity signer signs it as data, that is its double SHA-256. The fields are the entry’s,recipientincluded, so it is computed before sealing. - recover_
private_ document_ signer - The key a compact signature of
signing_datarecovers to, refused withSenderNotAuthenticatedwhen it is no signature. A signer checks its own signature with it before sealing. - recover_
sent_ private_ document_ entry - Recovers
entryof the private document typetargetthat the holder ofoutgoing_viewing_keybuilt, 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_sizebytes carryingpayloadtorecipient, for the private document typetarget. - 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_datawithsecret_keyas 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 maskedaccountReference. Inverse ofcalculate_account_referencefor 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.