Struct diem_types::network_address::NetworkAddress

pub struct NetworkAddress(_);

Overview

Diem NetworkAddress is a compact, efficient, self-describing and future-proof network address represented as a stack of protocols. Essentially libp2p’s multiaddr but using bcs to describe the binary format.

Most validators will advertise a network address like:

/dns/example.com/tcp/6180/ln-noise-ik/<x25519-pubkey>/ln-handshake/1

Unpacking, the above effectively means:

1. Resolve the DNS name “example.com” to an ip address, addr.
2. Open a TCP connection to (addr, 6180).
3. Perform a Noise IK handshake and assume the peer’s static pubkey is <x25519-pubkey>. After this step, we will have a secure, authenticated connection with the peer.
4. Perform a DiemNet version negotiation handshake (version 1).

Self-describing, Upgradable

One key concept behind NetworkAddress is that it is fully self-describing, which allows us to easily “pre-negotiate” protocols while also allowing for future upgrades. For example, it is generally unsafe to negotiate a secure transport in-band. Instead, with NetworkAddress we can advertise (via discovery) the specific secure transport protocol and public key that we support (and even advertise multiple incompatible versions). When a peer wishes to establish a connection with us, they already know which secure transport protocol to use; in this sense, the secure transport protocol is “pre-negotiated” by the dialier selecting which advertised protocol to use.

Each network address is encoded with the length of the encoded NetworkAddress and then the serialized protocol slices to allow for transparent upgradeability. For example, if the current software cannot decode a NetworkAddress within a Vec<NetworkAddress> it can still decode the underlying Vec<u8> and retrieve the remaining Vec<NetworkAddress>.

Transport

In addition, NetworkAddress is integrated with the DiemNet concept of a Transport, which takes a NetworkAddress when dialing and peels off Protocols to establish a connection and perform initial handshakes. Similarly, the Transport takes NetworkAddress to listen on, which tells it what protocols to expect on the socket.

Example

An example of a serialized NetworkAddress:

// human-readable format:
//
//   "/ip4/10.0.0.16/tcp/80"
//
// serialized NetworkAddress:
//
//      [ 09 02 00 0a 00 00 10 05 80 00 ]
//          \  \  \  \           \  \
//           \  \  \  \           \  '-- u16 tcp port
//            \  \  \  \           '-- uvarint protocol id for /tcp
//             \  \  \  '-- u32 ipv4 address
//              \  \  '-- uvarint protocol id for /ip4
//               \  '-- uvarint number of protocols
//                '-- length of encoded network address

use diem_types::network_address::NetworkAddress;
use bcs;
use std::{str::FromStr, convert::TryFrom};

let addr = NetworkAddress::from_str("/ip4/10.0.0.16/tcp/80").unwrap();
let actual_ser_addr = bcs::to_bytes(&addr).unwrap();

let expected_ser_addr: Vec<u8> = [9, 2, 0, 10, 0, 0, 16, 5, 80, 0].to_vec();

assert_eq!(expected_ser_addr, actual_ser_addr);

Implementations

impl NetworkAddress

pub fn as_slice(&self) -> &[Protocol]

pub fn push(self, proto: Protocol) -> Self

pub fn extend_from_slice(self, protos: &[Protocol]) -> Self

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

See EncNetworkAddress::encrypt.

pub fn append_prod_protos(
    self,
    network_pubkey: PublicKey,
    handshake_version: u8
) -> Self

Given a base NetworkAddress, append production protocols and return the modified NetworkAddress.

Example

use diem_crypto::{traits::ValidCryptoMaterialStringExt, x25519};
use diem_types::network_address::NetworkAddress;
use std::str::FromStr;

let pubkey_str = "080e287879c918794170e258bfaddd75acac5b3e350419044655e4983a487120";
let pubkey = x25519::PublicKey::from_encoded_string(pubkey_str).unwrap();
let addr = NetworkAddress::from_str("/dns/example.com/tcp/6180").unwrap();
let addr = addr.append_prod_protos(pubkey, 0);
assert_eq!(
    addr.to_string(),
    "/dns/example.com/tcp/6180/ln-noise-ik/080e287879c918794170e258bfaddd75acac5b3e350419044655e4983a487120/ln-handshake/0",
);

pub fn is_diemnet_addr(&self) -> bool

Check that a NetworkAddress looks like a typical DiemNet address with associated protocols.

“typical” DiemNet addresses begin with a transport protocol:

"/ip4/<addr>/tcp/<port>" or "/ip6/<addr>/tcp/<port>" or "/dns4/<domain>/tcp/<port>" or "/dns6/<domain>/tcp/<port>" or "/dns/<domain>/tcp/<port>" or cfg!(test) "/memory/<port>"

followed by transport upgrade handshake protocols:

"/ln-noise-ik/<pubkey>/ln-handshake/<version>"

Example

use diem_types::network_address::NetworkAddress;
use std::str::FromStr;

let addr_str = "/ip4/1.2.3.4/tcp/6180/ln-noise-ik/080e287879c918794170e258bfaddd75acac5b3e350419044655e4983a487120/ln-handshake/0";
let addr = NetworkAddress::from_str(addr_str).unwrap();
assert!(addr.is_diemnet_addr());

pub fn find_ip_addr(&self) -> Option<IpAddr>

Retrieves the IP address from the network address

pub fn find_noise_proto(&self) -> Option<PublicKey>

A temporary, hacky function to parse out the first /ln-noise-ik/<pubkey> from a NetworkAddress. We can remove this soon, when we move to the interim “monolithic” transport model.

pub fn rotate_noise_public_key(
    &mut self,
    to_replace: &PublicKey,
    new_public_key: &PublicKey
)

A function to rotate public keys for NoiseIK protocols

Trait Implementations

impl Clone for NetworkAddress

fn clone(&self) -> NetworkAddress

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for NetworkAddress

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for NetworkAddress

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

Deserialize this value from the given Serde deserializer.

impl Display for NetworkAddress

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

Formats the value using the given formatter.

impl From<Protocol> for NetworkAddress

fn from(proto: Protocol) -> NetworkAddress

Performs the conversion.

impl From<SocketAddr> for NetworkAddress

fn from(sockaddr: SocketAddr) -> NetworkAddress

Performs the conversion.

impl FromStr for NetworkAddress

type Err = ParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for NetworkAddress

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl IntoIterator for NetworkAddress

type Item = Protocol

The type of the elements being iterated over.

type IntoIter = IntoIter<Self::Item>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq<NetworkAddress> for NetworkAddress

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

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

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

This method tests for !=.

impl Serialize for NetworkAddress

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

Serialize this value into the given Serde serializer.

impl ToSocketAddrs for NetworkAddress

type Iter = IntoIter<SocketAddr>

Returned iterator over socket addresses which this type may correspond to.

fn to_socket_addrs(&self) -> Result<Self::Iter, Error>

Converts this object to an iterator of resolved SocketAddrs.

impl TryFrom<Vec<Protocol, Global>> for NetworkAddress

type Error = EmptyError

The type returned in the event of a conversion error.

fn try_from(value: Vec<Protocol>) -> Result<Self, Self::Error>

Performs the conversion.

impl Eq for NetworkAddress

impl StructuralEq for NetworkAddress

impl StructuralPartialEq for NetworkAddress