Struct Portal

Source
pub struct Portal {
    pub id: String,
    pub direction: Direction,
    pub exchange: PortalKeyExchange,
    pub state: Option<Spake2<Ed25519Group>>,
    /* private fields */
}
Expand description

The primary interface into the library.

Fields§

§id: String§direction: Direction§exchange: PortalKeyExchange§state: Option<Spake2<Ed25519Group>>

Implementations§

Source§

impl Portal

Source

pub fn init( direction: Direction, id: String, password: String, ) -> Result<Portal, Box<dyn Error>>

Initialize a new portal request

§Example
use portal_lib::{Portal,Direction};

// the shared password should be secret and hard to guess/crack
// see the portal-client as an example of potential usage
let id = String::from("my client ID");
let password = String::from("testpasswd");
let portal = Portal::init(Direction::Receiver, id, password).unwrap();
Source

pub fn handshake<P: Read + Write>( &mut self, peer: &mut P, ) -> Result<(), Box<dyn Error>>

Negotiate a secure connection over the insecure channel by performing the portal handshake. Subsequent communication will be encrypted.

§Example
use std::net::TcpStream;
use portal_lib::{Portal,Direction};

let mut portal = Portal::init(Direction::Sender, "id".into(), "password".into()).unwrap();
let mut stream = TcpStream::connect("127.0.0.1:34254").unwrap();

// conduct the handshake with the peer
portal.handshake(&mut stream).unwrap();
Source

pub fn outgoing<'a, W>( &mut self, peer: &mut W, info: &'a TransferInfo, ) -> Result<impl Iterator<Item = (&'a PathBuf, &'a Metadata)>, Box<dyn Error>>
where W: Write,

As the sender, communicate a TransferInfo struct to the receiver so that they may confirm/deny the transfer. Returns an iterator over the fullpath + Metadata to pass to send_file(). Allows the user to send multiple files in one session.

§Example
use std::path::Path;
use std::error::Error;
use std::net::TcpStream;
use portal_lib::{Portal, Direction, TransferInfoBuilder};

fn my_send() -> Result<(), Box<dyn Error>> {
    // Securely generate/exchange ID & Password with peer out-of-band
    let id = String::from("id");
    let password = String::from("password");

    // Connect to the relay
    let mut portal = Portal::init(Direction::Sender,"id".into(), "password".into())?;
    let mut stream = TcpStream::connect("127.0.0.1:34254")?;

    // The handshake must be performed first, otherwise
    // there is no shared key to encrypt the file with
    portal.handshake(&mut stream)?;

    // Add any files/directories
    let info = TransferInfoBuilder::new()
        .add_file(Path::new("/etc/passwd"))?
        .finalize();

    // Optional: implement a custom callback to display how much
    // has been transferred
    fn progress(transferred: usize) {
        println!("sent {:?} bytes", transferred);
    }

    // Send every file in TransferInfo
    for (fullpath, metadata) in portal.outgoing(&mut stream, &info)? {
        portal.send_file(&mut stream, fullpath, Some(progress))?;
    }
    Ok(())
}
Source

pub fn incoming<R, V>( &mut self, peer: &mut R, verify: Option<V>, ) -> Result<impl Iterator<Item = Metadata>, Box<dyn Error>>
where R: Read, V: Fn(&TransferInfo) -> bool,

As the receiver, receive a TransferInfo struct which will be passed to your optional verify callback. And may be used to confirm/deny the transfer. Returns an iterator over the Metadata of incoming files.

§Example
use std::path::Path;
use std::error::Error;
use std::net::TcpStream;
use portal_lib::{Portal, Direction, TransferInfo};

fn my_recv() -> Result<(), Box<dyn Error>> {

    // Securely generate/exchange ID & Password with peer out-of-band
    let id = String::from("id");
    let password = String::from("password");

    // Connect to the relay
    let mut portal = Portal::init(Direction::Sender, id, password)?;
    let mut stream = TcpStream::connect("127.0.0.1:34254")?;

    // The handshake must be performed first, otherwise
    // there is no shared key to encrypt the file with
    portal.handshake(&mut stream)?;

    // Optional: User callback to confirm/deny a transfer. If
    // none is provided, this will default accept the incoming file.
    // Return true to accept, false to reject the transfer.
    fn confirm_download(_info: &TransferInfo) -> bool { true }

    // Optional: implement a custom callback to display how much
    // has been transferred
    fn progress(transferred: usize) {
        println!("received {:?} bytes", transferred);
    }

    // Decide where downloads should go
    let my_downloads = Path::new("/tmp");

    // Receive every file in TransferInfo
    for metadata in portal.incoming(&mut stream, Some(confirm_download))? {
        portal.recv_file(&mut stream, my_downloads, Some(&metadata), Some(progress))?;
    }
    Ok(())
}
Source

pub fn send_file<W, D>( &mut self, peer: &mut W, path: &PathBuf, callback: Option<D>, ) -> Result<usize, Box<dyn Error>>
where W: Write, D: Fn(usize),

Send a given file over the portal. Must be called after performing the handshake or this method will return an error.

§Example
use std::path::Path;
use std::net::TcpStream;
use portal_lib::{Portal,Direction};

let mut portal = Portal::init(Direction::Sender,"id".into(), "password".into()).unwrap();
let mut stream = TcpStream::connect("127.0.0.1:34254").unwrap();

// The handshake must be performed first, otherwise
// there is no shared key to encrypt the file with
portal.handshake(&mut stream);

// Optional: implement a custom callback to display how much
// has been transferred
fn progress(transferred: usize) {
    println!("sent {:?} bytes", transferred);
}

// Begin sending the file
let file = Path::new("/etc/passwd").to_path_buf();
portal.send_file(&mut stream, &file, Some(progress));
Source

pub fn recv_file<R, D>( &mut self, peer: &mut R, outdir: &Path, expected: Option<&Metadata>, display: Option<D>, ) -> Result<Metadata, Box<dyn Error>>
where R: Read, D: Fn(usize),

Receive the next file over the portal. Must be called after performing the handshake or this method will return an error.

§Example
use std::path::Path;
use std::net::TcpStream;
use portal_lib::{Portal,Direction};

let mut portal = Portal::init(Direction::Sender,"id".into(), "password".into()).unwrap();
let mut stream = TcpStream::connect("127.0.0.1:34254").unwrap();

// The handshake must be performed first, otherwise
// there is no shared key to encrypt the file with
portal.handshake(&mut stream);

// Optional: implement a custom callback to display how much
// has been transferred
fn progress(transferred: usize) {
    println!("received {:?} bytes", transferred);
}

// Begin receiving the file into /tmp
portal.recv_file(&mut stream, Path::new("/tmp"), None, Some(progress));
Source

pub fn get_direction(&self) -> Direction

Returns a copy of the Portal::Direction associated with this Portal request

Source

pub fn set_direction(&mut self, direction: Direction)

Sets the Portal::Direction associated with this Poral request

Source

pub fn get_id(&self) -> &String

Returns a reference to the ID associated with this Portal request

Source

pub fn set_id(&mut self, id: String)

Sets the ID associated with this Poral request

Source

pub fn get_key(&self) -> &Option<Vec<u8>>

Returns a reference to the key associated with this Portal request

Source

pub fn set_key(&mut self, key: Vec<u8>)

Sets the ID associated with this Poral request

Trait Implementations§

Source§

impl Debug for Portal

Source§

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

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

impl PartialEq for Portal

Source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Source§

impl Eq for Portal

Source§

impl StructuralPartialEq for Portal

Auto Trait Implementations§

§

impl Freeze for Portal

§

impl RefUnwindSafe for Portal

§

impl Send for Portal

§

impl Sync for Portal

§

impl Unpin for Portal

§

impl UnwindSafe for Portal

Blanket Implementations§

Source§

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

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

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

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

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

Source§

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

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

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

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 for T

Source§

type Output = T

Should always be Self
Source§

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

Source§

type Error = Infallible

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

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

Performs the conversion.
Source§

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

Source§

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

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

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

Performs the conversion.
Source§

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

Source§

fn vzip(self) -> V