pub struct NetworkAddress(_);
Expand description

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§

source§

impl NetworkAddress

source

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

source

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

source

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

source

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

source

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",
);
source

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());
source

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

Retrieves the IP address from the network address

source

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.

source

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

A function to rotate public keys for NoiseIK protocols

source

pub fn mock() -> Self

Trait Implementations§

source§

impl Arbitrary for NetworkAddress

§

type Parameters = ()

The type of parameters that arbitrary_with accepts for configuration of the generated Strategy. Parameters must implement Default.
§

type Strategy = BoxedStrategy<NetworkAddress>

The type of Strategy used to generate values of type Self.
source§

fn arbitrary_with(_args: Self::Parameters) -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self). The strategy is passed the arguments given in args. Read more
§

fn arbitrary() -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self). Read more
source§

impl Clone for NetworkAddress

source§

fn clone(&self) -> NetworkAddress

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for NetworkAddress

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

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

Deserialize this value from the given Serde deserializer. Read more
source§

impl Display for NetworkAddress

source§

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

Formats the value using the given formatter. Read more
source§

impl From<Protocol> for NetworkAddress

source§

fn from(proto: Protocol) -> NetworkAddress

Converts to this type from the input type.
source§

impl From<SocketAddr> for NetworkAddress

source§

fn from(sockaddr: SocketAddr) -> NetworkAddress

Converts to this type from the input type.
source§

impl FromStr for NetworkAddress

§

type Err = ParseError

The associated error which can be returned from parsing.
source§

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

Parses a string s to return a value of this type. Read more
source§

impl Hash for NetworkAddress

source§

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

Feeds this value into the given Hasher. Read more
1.3.0 · source§

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

Feeds a slice of this type into the given Hasher. Read more
source§

impl IntoIterator for NetworkAddress

§

type Item = Protocol

The type of the elements being iterated over.
§

type IntoIter = IntoIter<<NetworkAddress as IntoIterator>::Item, Global>

Which kind of iterator are we turning this into?
source§

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value. Read more
source§

impl PartialEq<NetworkAddress> for NetworkAddress

source§

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

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

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Serialize for NetworkAddress

source§

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

Serialize this value into the given Serde serializer. Read more
source§

impl ToSocketAddrs for NetworkAddress

§

type Iter = IntoIter<SocketAddr, Global>

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

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

Converts this object to an iterator of resolved SocketAddrs. Read more
source§

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

§

type Error = EmptyError

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl Eq for NetworkAddress

source§

impl StructuralEq for NetworkAddress

source§

impl StructuralPartialEq for NetworkAddress

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

const: unstable · source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

const: unstable · source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> CallHasher for Twhere T: Hash + ?Sized,

§

fn get_hash<H, B>(value: &H, build_hasher: &B) -> u64where H: Hash + ?Sized, B: BuildHasher,

source§

impl<Q, K> Equivalent<K> for Qwhere Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

source§

fn equivalent(&self, key: &K) -> bool

Compare self to key and return true if they are equal.
source§

impl<T> From<T> for T

const: unstable · source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

const: unstable · source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same<T> for T

§

type Output = T

Should always be Self
source§

impl<T> TestOnlyHash for Twhere T: Serialize + ?Sized,

source§

fn test_only_hash(&self) -> HashValue

Generates a hash used only for tests.
source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for Twhere T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
const: unstable · source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
const: unstable · source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

§

fn vzip(self) -> V

source§

impl<T> DeserializeOwned for Twhere T: for<'de> Deserialize<'de>,