Struct magic_wormhole::Wormhole

pub struct Wormhole {
    pub verifier: Box<Key>,
    pub our_version: Box<dyn Any + Send + Sync>,
    pub peer_version: Value,
    /* private fields */
}

Establishing Wormhole connection

You can send and receive arbitrary messages in form of byte slices over it, using Wormhole::send and Wormhole::receive. Everything else (including encryption) will be handled for you.

To create a wormhole, use the Wormhole::connect_without_code, Wormhole::connect_with_code etc. methods, depending on which values you have. Typically, the sender side connects without a code (which will create one), and the receiver side has one (the user entered it, who got it from the sender).

Clean shutdown

TODO

Fields

verifier: Box<Key>

If you’re paranoid, let both sides check that they calculated the same verifier.

PAKE hardens a standard key exchange with a password (“password authenticated”) in order to mitigate potential man in the middle attacks that would otherwise be possible. Since the passwords usually are not of hight entropy, there is a low-probability possible of an attacker guessing the password correctly, enabling them to MitM the connection.

Not only is that probability low, but they also have only one try per connection and a failed attempts will be noticed by both sides. Nevertheless, comparing the verifier mitigates that attack vector.

our_version: Box<dyn Any + Send + Sync>

Our “app version” information that we sent. See the [peer_version] for more information.

peer_version: Value

Protocol version information from the other side. This is bound by the AppID’s protocol and thus shall be handled on a higher level (e.g. by the file transfer API).

Implementations

impl Wormhole

pub async fn connect_without_code(
    config: AppConfig<impl Serialize + Send + Sync + 'static>,
    code_length: usize
) -> Result<(WormholeWelcome, impl Future<Output = Result<Self, WormholeError>>), WormholeError>

Generate a code and connect to the rendezvous server.

Returns

A tuple with a WormholeWelcome and a std::future::Future that will do the rest of the client-client handshake and yield the Wormhole object on success.

pub async fn connect_with_code(
    config: AppConfig<impl Serialize + Send + Sync + 'static>,
    code: Code
) -> Result<(WormholeWelcome, Self), WormholeError>

Connect to a peer with a code.

pub async fn connect_with_seed()

TODO

pub async fn connect_custom(
    server: RendezvousServer,
    appid: AppID,
    password: String,
    app_versions: impl Serialize + Send + Sync + 'static
) -> Result<Self, WormholeError>

Do only the client-client part of the connection setup

The rendezvous server must already have an opened mailbox.

Panics

If the RendezvousServer is not properly initialized, i.e. if the mailbox is not open.

pub async fn send(&mut self, plaintext: Vec<u8>) -> Result<(), WormholeError>

Send an encrypted message to peer

pub async fn send_json<T: Serialize>(
    &mut self,
    message: &T
) -> Result<(), WormholeError>

Serialize and send an encrypted message to peer

This will serialize the message as json string, which is most commonly used by upper layer protocols. The serialization may not fail

Panics

If the serialization fails

pub async fn receive(&mut self) -> Result<Vec<u8>, WormholeError>

Receive an encrypted message from peer

pub async fn receive_json<T>(
    &mut self
) -> Result<Result<T, Error>, WormholeError> where
    T: for<'a> Deserialize<'a>, 

Receive an encrypted message from peer

This will deserialize the message as json string, which is most commonly used by upper layer protocols. We distinguish between the different layers on which a serialization error happened, hence the double Result.

pub async fn close(self) -> Result<(), WormholeError>

pub fn appid(&self) -> &AppID

The AppID this wormhole is bound to. This determines the upper-layer protocol. Only wormholes with the same value can talk to each other.

pub fn key(&self) -> &Key<WormholeKey>

The symmetric encryption key used by this connection. Can be used to derive sub-keys for different purposes.

Trait Implementations

impl Debug for Wormhole

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

Formats the value using the given formatter.