Struct diem_types::network_address::NetworkAddress
source · 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:
- Resolve the DNS name “example.com” to an ip address,
addr
. - Open a TCP connection to
(addr, 6180)
. - 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. - 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
Protocol
s 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
impl NetworkAddress
pub fn as_slice(&self) -> &[Protocol]
pub fn push(self, proto: Protocol) -> Self
pub fn extend_from_slice(self, protos: &[Protocol]) -> Self
sourcepub fn encrypt(
self,
shared_val_netaddr_key: &Key,
key_version: KeyVersion,
account: &AccountAddress,
seq_num: u64,
addr_idx: u32
) -> Result<EncNetworkAddress, ParseError>
pub fn encrypt( self, shared_val_netaddr_key: &Key, key_version: KeyVersion, account: &AccountAddress, seq_num: u64, addr_idx: u32 ) -> Result<EncNetworkAddress, ParseError>
sourcepub fn append_prod_protos(
self,
network_pubkey: PublicKey,
handshake_version: u8
) -> Self
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",
);
sourcepub fn is_diemnet_addr(&self) -> bool
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());
sourcepub fn find_ip_addr(&self) -> Option<IpAddr>
pub fn find_ip_addr(&self) -> Option<IpAddr>
Retrieves the IP address from the network address
sourcepub fn find_noise_proto(&self) -> Option<PublicKey>
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.
sourcepub fn rotate_noise_public_key(
&mut self,
to_replace: &PublicKey,
new_public_key: &PublicKey
)
pub fn rotate_noise_public_key( &mut self, to_replace: &PublicKey, new_public_key: &PublicKey )
A function to rotate public keys for NoiseIK
protocols
pub fn mock() -> Self
Trait Implementations§
source§impl Arbitrary for NetworkAddress
impl Arbitrary for NetworkAddress
§type Parameters = ()
type Parameters = ()
arbitrary_with
accepts for configuration
of the generated Strategy
. Parameters must implement Default
.§type Strategy = BoxedStrategy<NetworkAddress>
type Strategy = BoxedStrategy<NetworkAddress>
Strategy
used to generate values of type Self
.source§fn arbitrary_with(_args: Self::Parameters) -> Self::Strategy
fn arbitrary_with(_args: Self::Parameters) -> Self::Strategy
source§impl Clone for NetworkAddress
impl Clone for NetworkAddress
source§fn clone(&self) -> NetworkAddress
fn clone(&self) -> NetworkAddress
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Debug for NetworkAddress
impl Debug for NetworkAddress
source§impl<'de> Deserialize<'de> for NetworkAddress
impl<'de> Deserialize<'de> for NetworkAddress
source§fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>where
D: Deserializer<'de>,
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>where D: Deserializer<'de>,
source§impl Display for NetworkAddress
impl Display for NetworkAddress
source§impl From<Protocol> for NetworkAddress
impl From<Protocol> for NetworkAddress
source§fn from(proto: Protocol) -> NetworkAddress
fn from(proto: Protocol) -> NetworkAddress
source§impl From<SocketAddr> for NetworkAddress
impl From<SocketAddr> for NetworkAddress
source§fn from(sockaddr: SocketAddr) -> NetworkAddress
fn from(sockaddr: SocketAddr) -> NetworkAddress
source§impl FromStr for NetworkAddress
impl FromStr for NetworkAddress
source§impl Hash for NetworkAddress
impl Hash for NetworkAddress
source§impl IntoIterator for NetworkAddress
impl IntoIterator for NetworkAddress
source§impl PartialEq<NetworkAddress> for NetworkAddress
impl PartialEq<NetworkAddress> for NetworkAddress
source§fn eq(&self, other: &NetworkAddress) -> bool
fn eq(&self, other: &NetworkAddress) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl Serialize for NetworkAddress
impl Serialize for NetworkAddress
source§impl ToSocketAddrs for NetworkAddress
impl ToSocketAddrs for NetworkAddress
§type Iter = IntoIter<SocketAddr, Global>
type Iter = IntoIter<SocketAddr, Global>
source§fn to_socket_addrs(&self) -> Result<Self::Iter, Error>
fn to_socket_addrs(&self) -> Result<Self::Iter, Error>
SocketAddr
s. Read moreimpl Eq for NetworkAddress
impl StructuralEq for NetworkAddress
impl StructuralPartialEq for NetworkAddress
Auto Trait Implementations§
impl RefUnwindSafe for NetworkAddress
impl Send for NetworkAddress
impl Sync for NetworkAddress
impl Unpin for NetworkAddress
impl UnwindSafe for NetworkAddress
Blanket Implementations§
source§impl<Q, K> Equivalent<K> for Qwhere
Q: Eq + ?Sized,
K: Borrow<Q> + ?Sized,
impl<Q, K> Equivalent<K> for Qwhere Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,
source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.