Struct themis::secure_session::SecureSession

pub struct SecureSession { /* fields omitted */ }

Secure Session context.

This is the Secure Session object used for secure data exchange.

Secure Session only provides security services and doesn’t do actual network communication. In fact, Secure Session is decoupled and independent from any networking implementation. It is your responsibility to provide a network transport for Secure Session using the SecureSessionTransport trait. There are two types of APIs available: callback API and buffer-aware API. You can choose whatever API is more suitable for your application, or you can even mix them when appropriate.

Callback API

With the callback API you delegate network communication to Secure Session. In order to use it you have to implement the send_data and receive_data callbacks of SecureSessionTransport. Then you use connect and negotiate methods to negotiate and establish connection. After that send and receive methods can be used for data exchange. Secure Session will synchronously call the provided transport methods when necessary to perform network communication.

The documentation contains an example of a server using the callback API.

Buffer-aware API

With the buffer-aware API you are responsible for transporting Secure Session messages between peers. Secure Session does not use send_data and receive_data callbacks in this mode. Instead the connect_request and negotiate_reply methods return and receive data buffers that have to be exchanged between peers via some external transport (e.g., TLS). Similarly, wrap and unwrap methods are used to encrypt and decrypt data exchange messages after the connection has been negotiated. They too accept plaintext messages and return encrypted containers or vice versa.

The documentation contains an example of a client using the buffer-aware API.

Methods

impl SecureSession

pub fn new(
    id: impl AsRef<[u8]>,
    key: &EcdsaPrivateKey,
    transport: impl SecureSessionTransport + 'static
) -> Result<Self>

Creates a new Secure Session.

ID is an arbitrary non-empty byte sequence used to identify this peer.

pub fn is_established(&self) -> bool

Returns true if this Secure Session may be used for data transfer.

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

Returns ID of the remote peer.

Returns None if the connection has not been established yet and there is no peer.

pub fn connect(&mut self) -> Result<()>

Initiates connection to the remote peer.

This is the first method to call for the client, it sends a connection request to the server. Afterwards call negotiate until the connection is established. That is, until the state_changed callback of your SecureSessionTransport tells you that the connection is Established, or until is_established on this Secure Session returns true.

This method is a part of callback API and requires send_data method of SecureSessionTransport to be implemented.

pub fn negotiate(&mut self) -> Result<()>

Continues connection negotiation.

This method performs one step of connection negotiation. This is the first method to call for the server, the client calls it after the initial connect. Both peers shall then repeatedly call this method until the connection is established (see connect for details).

This method is a part of callback API and requires send_data and receive_data methods of SecureSessionTransport to be implemented.

pub fn send(&mut self, message: impl AsRef<[u8]>) -> Result<()>

Sends a message to the remote peer.

This method will fail if a secure connection has not been established yet. See connect and negotiate methods for establishing a connection.

This method is a part of callback API and requires send_data method of SecureSessionTransport to be implemented.

pub fn receive(&mut self, max_len: usize) -> Result<Vec<u8>>

Receives a message from the remote peer.

Maximum length of the message is specified by the parameter.

This method will fail if a secure connection has not been established yet. See connect and negotiate methods for establishing a connection.

This method is a part of callback API and requires receive_data method of SecureSessionTransport to be implemented.

pub fn connect_request(&mut self) -> Result<Vec<u8>>

Initiates connection to the remote peer, returns connection message.

This is the first method to call for the client, it returns you a message that you must transfer to the server. The server then shall give the message to its negotiate_reply method which returns a reply that must be transferred back to this Secure Session and passed to its negotiate_reply method. Continue passing these message around until the connection is established. That is, until the state_changed callback of your SecureSessionTransport tells you that the connection is Established, or until is_established on this Secure Session returns true, or until negotiate_reply returns an empty message.

pub fn negotiate_reply(&mut self, wrapped: impl AsRef<[u8]>) -> Result<Vec<u8>>

Continues connection negotiation with given message.

This method performs one step of connection negotiation. The server should call this method first with a message received from client’s connect_request. Its result is another negotiation message that should be transferred to the client. The client then calls this method on a message and forwards the resulting message to the server. If the returned message is empty then negotiation is complete and the Secure Session is ready to be used.

pub fn wrap(&mut self, message: impl AsRef<[u8]>) -> Result<Vec<u8>>

Encrypts a message and returns it.

The message can be transferred to the remote peer and decrypted there with unwrap.

Messages are independent and can be exchanged out of order. You can encrypt multiple messages then decrypt them in any order or don’t decrypt some of them at all.

This method will fail if a secure connection has not been established yet. See connect_request and negotiate_reply methods for establishing a connection.

pub fn unwrap(&mut self, wrapped: impl AsRef<[u8]>) -> Result<Vec<u8>>

Decrypts a message and returns it.

Decrypts a message previously wrapped by the remote peer.

This method will fail if a secure connection has not been established yet. See connect_request and negotiate_reply methods for establishing a connection.

Trait Implementations

impl Send for SecureSession

impl Debug for SecureSession

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

Formats the value using the given formatter.