Trait zcash_note_encryption::Domain

pub trait Domain {
    type EphemeralSecretKey: ConstantTimeEq;
    type EphemeralPublicKey;
    type PreparedEphemeralPublicKey;
    type SharedSecret;
    type SymmetricKey: AsRef<[u8]>;
    type Note;
    type Recipient;
    type DiversifiedTransmissionKey;
    type IncomingViewingKey;
    type OutgoingViewingKey;
    type ValueCommitment;
    type ExtractedCommitment;
    type ExtractedCommitmentBytes: Eq + for<'a> From<&'a Self::ExtractedCommitment>;
    type Memo;

    // Required methods
    fn derive_esk(note: &Self::Note) -> Option<Self::EphemeralSecretKey>;
    fn get_pk_d(note: &Self::Note) -> Self::DiversifiedTransmissionKey;
    fn prepare_epk(
        epk: Self::EphemeralPublicKey
    ) -> Self::PreparedEphemeralPublicKey;
    fn ka_derive_public(
        note: &Self::Note,
        esk: &Self::EphemeralSecretKey
    ) -> Self::EphemeralPublicKey;
    fn ka_agree_enc(
        esk: &Self::EphemeralSecretKey,
        pk_d: &Self::DiversifiedTransmissionKey
    ) -> Self::SharedSecret;
    fn ka_agree_dec(
        ivk: &Self::IncomingViewingKey,
        epk: &Self::PreparedEphemeralPublicKey
    ) -> Self::SharedSecret;
    fn kdf(
        secret: Self::SharedSecret,
        ephemeral_key: &EphemeralKeyBytes
    ) -> Self::SymmetricKey;
    fn note_plaintext_bytes(
        note: &Self::Note,
        memo: &Self::Memo
    ) -> NotePlaintextBytes;
    fn derive_ock(
        ovk: &Self::OutgoingViewingKey,
        cv: &Self::ValueCommitment,
        cmstar_bytes: &Self::ExtractedCommitmentBytes,
        ephemeral_key: &EphemeralKeyBytes
    ) -> OutgoingCipherKey;
    fn outgoing_plaintext_bytes(
        note: &Self::Note,
        esk: &Self::EphemeralSecretKey
    ) -> OutPlaintextBytes;
    fn epk_bytes(epk: &Self::EphemeralPublicKey) -> EphemeralKeyBytes;
    fn epk(
        ephemeral_key: &EphemeralKeyBytes
    ) -> Option<Self::EphemeralPublicKey>;
    fn cmstar(note: &Self::Note) -> Self::ExtractedCommitment;
    fn parse_note_plaintext_without_memo_ivk(
        &self,
        ivk: &Self::IncomingViewingKey,
        plaintext: &[u8]
    ) -> Option<(Self::Note, Self::Recipient)>;
    fn parse_note_plaintext_without_memo_ovk(
        &self,
        pk_d: &Self::DiversifiedTransmissionKey,
        plaintext: &NotePlaintextBytes
    ) -> Option<(Self::Note, Self::Recipient)>;
    fn extract_memo(&self, plaintext: &NotePlaintextBytes) -> Self::Memo;
    fn extract_pk_d(
        out_plaintext: &OutPlaintextBytes
    ) -> Option<Self::DiversifiedTransmissionKey>;
    fn extract_esk(
        out_plaintext: &OutPlaintextBytes
    ) -> Option<Self::EphemeralSecretKey>;
}

Trait that encapsulates protocol-specific note encryption types and logic.

This trait enables most of the note encryption logic to be shared between Sapling and Orchard, as well as between different implementations of those protocols.

Required Associated Types

type EphemeralSecretKey: ConstantTimeEq

type EphemeralPublicKey

type PreparedEphemeralPublicKey

type SharedSecret

type SymmetricKey: AsRef<[u8]>

type Note

type Recipient

type DiversifiedTransmissionKey

type IncomingViewingKey

type OutgoingViewingKey

type ValueCommitment

type ExtractedCommitment

type ExtractedCommitmentBytes: Eq + for<'a> From<&'a Self::ExtractedCommitment>

type Memo

Required Methods

fn derive_esk(note: &Self::Note) -> Option<Self::EphemeralSecretKey>

Derives the EphemeralSecretKey corresponding to this note.

Returns None if the note was created prior to ZIP 212, and doesn’t have a deterministic EphemeralSecretKey.

fn get_pk_d(note: &Self::Note) -> Self::DiversifiedTransmissionKey

Extracts the DiversifiedTransmissionKey from the note.

fn prepare_epk( epk: Self::EphemeralPublicKey ) -> Self::PreparedEphemeralPublicKey

Prepare an ephemeral public key for more efficient scalar multiplication.

fn ka_derive_public( note: &Self::Note, esk: &Self::EphemeralSecretKey ) -> Self::EphemeralPublicKey

Derives EphemeralPublicKey from esk and the note’s diversifier.

fn ka_agree_enc( esk: &Self::EphemeralSecretKey, pk_d: &Self::DiversifiedTransmissionKey ) -> Self::SharedSecret

Derives the SharedSecret from the sender’s information during note encryption.

fn ka_agree_dec( ivk: &Self::IncomingViewingKey, epk: &Self::PreparedEphemeralPublicKey ) -> Self::SharedSecret

Derives the SharedSecret from the recipient’s information during note trial decryption.

fn kdf( secret: Self::SharedSecret, ephemeral_key: &EphemeralKeyBytes ) -> Self::SymmetricKey

Derives the SymmetricKey used to encrypt the note plaintext.

secret is the SharedSecret obtained from Self::ka_agree_enc or Self::ka_agree_dec.

ephemeral_key is the byte encoding of the EphemeralPublicKey used to derive secret. During encryption it is derived via Self::epk_bytes; during trial decryption it is obtained from ShieldedOutput::ephemeral_key.

fn note_plaintext_bytes( note: &Self::Note, memo: &Self::Memo ) -> NotePlaintextBytes

Encodes the given Note and Memo as a note plaintext.

fn derive_ock( ovk: &Self::OutgoingViewingKey, cv: &Self::ValueCommitment, cmstar_bytes: &Self::ExtractedCommitmentBytes, ephemeral_key: &EphemeralKeyBytes ) -> OutgoingCipherKey

Derives the OutgoingCipherKey for an encrypted note, given the note-specific public data and an OutgoingViewingKey.

fn outgoing_plaintext_bytes( note: &Self::Note, esk: &Self::EphemeralSecretKey ) -> OutPlaintextBytes

Encodes the outgoing plaintext for the given note.

fn epk_bytes(epk: &Self::EphemeralPublicKey) -> EphemeralKeyBytes

Returns the byte encoding of the given EphemeralPublicKey.

fn epk(ephemeral_key: &EphemeralKeyBytes) -> Option<Self::EphemeralPublicKey>

Attempts to parse ephemeral_key as an EphemeralPublicKey.

Returns None if ephemeral_key is not a valid byte encoding of an EphemeralPublicKey.

fn cmstar(note: &Self::Note) -> Self::ExtractedCommitment

Derives the ExtractedCommitment for this note.

fn parse_note_plaintext_without_memo_ivk( &self, ivk: &Self::IncomingViewingKey, plaintext: &[u8] ) -> Option<(Self::Note, Self::Recipient)>

Parses the given note plaintext from the recipient’s perspective.

The implementation of this method must check that:

• The note plaintext version is valid (for the given decryption domain’s context, which may be passed via self).
• The note plaintext contains valid encodings of its various fields.
• Any domain-specific requirements are satisfied.

&self is passed here to enable the implementation to enforce contextual checks, such as rules like ZIP 212 that become active at a specific block height.

Panics

Panics if plaintext is shorter than COMPACT_NOTE_SIZE.

fn parse_note_plaintext_without_memo_ovk( &self, pk_d: &Self::DiversifiedTransmissionKey, plaintext: &NotePlaintextBytes ) -> Option<(Self::Note, Self::Recipient)>

Parses the given note plaintext from the sender’s perspective.

The implementation of this method must check that:

• The note plaintext version is valid (for the given decryption domain’s context, which may be passed via self).
• The note plaintext contains valid encodings of its various fields.
• Any domain-specific requirements are satisfied.

&self is passed here to enable the implementation to enforce contextual checks, such as rules like ZIP 212 that become active at a specific block height.

fn extract_memo(&self, plaintext: &NotePlaintextBytes) -> Self::Memo

Extracts the memo field from the given note plaintext.

Compatibility

&self is passed here in anticipation of future changes to memo handling, where the memos may no longer be part of the note plaintext.

fn extract_pk_d( out_plaintext: &OutPlaintextBytes ) -> Option<Self::DiversifiedTransmissionKey>

Parses the DiversifiedTransmissionKey field of the outgoing plaintext.

Returns None if out_plaintext does not contain a valid byte encoding of a DiversifiedTransmissionKey.

fn extract_esk( out_plaintext: &OutPlaintextBytes ) -> Option<Self::EphemeralSecretKey>

Parses the EphemeralSecretKey field of the outgoing plaintext.

Returns None if out_plaintext does not contain a valid byte encoding of an EphemeralSecretKey.

Implementors