Struct magic_wormhole::Wormhole
source · pub struct Wormhole {
pub verifier: Box<Key>,
pub our_version: Box<dyn Any + Send + Sync>,
pub peer_version: Value,
/* private fields */
}
Expand description
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§
source§impl Wormhole
impl Wormhole
sourcepub async fn connect_without_code(
config: AppConfig<impl Serialize + Send + Sync + 'static>,
code_length: usize
) -> Result<(WormholeWelcome, impl Future<Output = Result<Self, WormholeError>>), WormholeError>
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.
sourcepub async fn connect_with_code(
config: AppConfig<impl Serialize + Send + Sync + 'static>,
code: Code
) -> Result<(WormholeWelcome, Self), WormholeError>
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.
sourcepub async fn connect_with_seed()
pub async fn connect_with_seed()
TODO
sourcepub async fn connect_custom(
server: RendezvousServer,
appid: AppID,
password: String,
app_versions: impl Serialize + Send + Sync + 'static
) -> Result<Self, WormholeError>
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.
sourcepub async fn send(&mut self, plaintext: Vec<u8>) -> Result<(), WormholeError>
pub async fn send(&mut self, plaintext: Vec<u8>) -> Result<(), WormholeError>
Send an encrypted message to peer
sourcepub async fn send_json<T: Serialize>(
&mut self,
message: &T
) -> Result<(), WormholeError>
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
sourcepub async fn receive(&mut self) -> Result<Vec<u8>, WormholeError>
pub async fn receive(&mut self) -> Result<Vec<u8>, WormholeError>
Receive an encrypted message from peer
sourcepub async fn receive_json<T>(
&mut self
) -> Result<Result<T, Error>, WormholeError>where
T: for<'a> Deserialize<'a>,
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>
sourcepub fn appid(&self) -> &AppID
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.
sourcepub fn key(&self) -> &Key<WormholeKey>
pub fn key(&self) -> &Key<WormholeKey>
The symmetric encryption key used by this connection. Can be used to derive sub-keys for different purposes.