Struct diem_types::network_address::encrypted::EncNetworkAddress

pub struct EncNetworkAddress { /* fields omitted */ }

An encrypted NetworkAddress.

Threat Model

Encrypting the on-chain network addresses is purely a defense-in-depth mitigation to minimize attack surface and reduce DDoS attacks on the validators by restricting the visibility of their public-facing network addresses only to other validators.

These encrypted network addresses are intended to be stored on-chain under each validator’s advertised network addresses in their ValidatorConfigs. All validators share the secret shared_val_netaddr_key, though each validator’s addresses are encrypted using a per-validator derived_key.

Account Key

derived_key := HKDF-SHA3-256::extract_and_expand(
    salt=HKDF_SALT,
    ikm=shared_val_netaddr_key,
    info=account_address,
    output_length=32,
)

where HKDF-SHA3-256::extract_and_expand is HKDF extract-and-expand with SHA3-256, HKDF_SALT is a constant salt for application separation, shared_val_netaddr_key is the shared secret distributed amongst all the validators, and account_address is the specific validator’s AccountAddress.

We use per-validator derived_keys to limit the “blast radius” of nonce reuse to each validator, i.e., a validator that accidentally reuses a nonce will only leak information about their network addresses or derived_key.

Encryption

A raw network address, addr, is then encrypted using AES-256-GCM like:

enc_addr := AES-256-GCM::encrypt(
    key=derived_key,
    nonce=nonce,
    ad=key_version,
    message=addr,
)

where nonce is a 96-bit integer as described below, key_version is the key version as a u32 big-endian integer, addr is the serialized NetworkAddress, and enc_addr is the encrypted network address concatenated with the 16-byte authentication tag.

Nonce

nonce := seq_num || addr_idx

where seq_num is the seq_num field as a u64 big-endian integer and addr_idx is the index of the encrypted network address in the list of network addresses as a u32 big-endian integer.

Sequence Number

In order to reduce the probability of nonce reuse, validators should use the sequence number of the rotation transaction in the seq_num field.

Key Rotation

The EncNetworkAddress struct contains a key_version field, which identifies the specific shared_val_netaddr_key used to encrypt/decrypt the EncNetworkAddress.

Implementations

impl EncNetworkAddress

pub fn encrypt(
    addr: NetworkAddress,
    shared_val_netaddr_key: &Key,
    key_version: KeyVersion,
    account: &AccountAddress,
    seq_num: u64,
    addr_idx: u32
) -> Result<Self, ParseError>

Panics

encrypt will panic if addr length > 64 GiB.

pub fn decrypt(
    self,
    shared_val_netaddr_key: &Key,
    account: &AccountAddress,
    addr_idx: u32
) -> Result<NetworkAddress, ParseError>

pub fn key_version(&self) -> KeyVersion

pub fn seq_num(&self) -> u64

Trait Implementations

impl Clone for EncNetworkAddress

fn clone(&self) -> EncNetworkAddress

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EncNetworkAddress

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for EncNetworkAddress

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl PartialEq<EncNetworkAddress> for EncNetworkAddress

fn eq(&self, other: &EncNetworkAddress) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &EncNetworkAddress) -> bool

This method tests for !=.

impl Serialize for EncNetworkAddress

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.

impl Eq for EncNetworkAddress

impl StructuralEq for EncNetworkAddress

impl StructuralPartialEq for EncNetworkAddress