Struct themis::secure_comparator::SecureComparator

pub struct SecureComparator { /* fields omitted */ }

Secure Comparison context.

Please see module-level documentation for examples.

Methods

impl SecureComparator

pub fn new() -> Self

Prepares a new comparison.

Panics

May panic on internal unrecoverable errors (e.g., out-of-memory).

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

Collects the data to be compared.

Note that there is no way to remove data. If even a single byte is mismatched by the peers then the comparison will always return false. In this case you will need to recreate a SecureComparator to make a new comparison.

You can use this method only before the comparison has been started. That is, append_secret is safe to call only before begin_compare or proceed_compare. It will fail with an error if you try to append more data when you’re in the middle of a comparison or after it has been completed.

Examples

You can pass in anything convertible into a byte slice: a byte slice or an array, a Vec<u8>, or a String.

use themis::secure_comparator::SecureComparator;

let mut comparison = SecureComparator::new();

comparison.append_secret(b"byte string")?;
comparison.append_secret(&[1, 2, 3, 4, 5])?;
comparison.append_secret(vec![6, 7, 8, 9])?;
comparison.append_secret(format!("owned string"))?;

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

Starts comparison on the client returning the first message.

This method should be called by the client which initiates the comparison. Make sure you have appended all the data you need before you call this method.

The resulting message should be transferred to the remote peer and passed to the proceed_compare of its SecureComparator. The remote peer should have also appended all the data by this point.

Examples

Please see module-level documentation for examples.

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

Continues comparison process with given message.

This method should be called by the responding server with a message received from the client. It returns another message which should be passed back to the client and put into its proceed_compare method (that is, this method again). The client then should do the same. The process repeats at both sides until is_complete signals that the comparison is complete.

Both peers should have appended all the compared data before using this method, and no additional data may be appended while the comparison is underway.

Examples

Please see module-level documentation for examples.

pub fn is_complete(&self) -> bool

Checks if this comparison is complete.

Comparison that failed irrecoverably due to an error is also considered complete.

Examples

Typically you would use this method to terminate the comparison loop. Please see module-level documentation for examples.

It is safe to call this method at any point, even if the comparison has not been initiated yet (in which case it is obviously not complete):

use themis::secure_comparator::SecureComparator;

let mut comparison = SecureComparator::new();

assert!(!comparison.is_complete());

pub fn result(&self) -> Result<bool>

Returns the result of comparison.

Let it be a surprise: true if data has been found equal on both peers, false otherwise. Or an error if you call this method too early, or if a real error has happened during the comparison.

Examples

You should call this method only after the comparison is complete.

use themis::secure_comparator::SecureComparator;

let mut comparison = SecureComparator::new();

comparison.append_secret(b"999-04-1234")?;

assert!(comparison.result().is_err());

// Perform comparison
while !comparison.is_complete() {
    // ...
}

assert!(comparison.result().is_ok());

Trait Implementations

impl Default for SecureComparator

fn default() -> Self

Returns the "default value" for a type.

impl Send for SecureComparator

impl Debug for SecureComparator

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

Formats the value using the given formatter.