Secure Cell passphrase API: RustThemis

[ilammy]

Add support of Secure Cell passphrase API to RustThemis. The API is described in RFC 3.8.

This only adds new API with its documentation. Existing API docs and tests for symmetric key API need an update to avoid using passphrases there. Since this PR is already massive, those changes will be submitted separately.

User notes

Passphrase-based interface of Secure Cell allows you to use short and memorable passphrases to secure your data. While symmetric keys are more secure, they are also longer and much harder for humans to remember.

Here is how you can use passphrases with Secure Cell in Rust:

use themis::secure_cell::SecureCell;

let cell = SecureCell::with_passphrase("secret")?.seal();

let message = b"precious message";

let encrypted = cell.encrypt(&message)?;
let decrypted = cell.decrypt(&encrypted)?;

assert_eq!(decrypted, message);

Passphrase API accepts passphrases as relatively short strings, suitable for human memory. Master key API uses randomly generated, long binary keys, which are more suitable for machines to remember. However, they are also much more efficient and generally more secure due to considerable length. You should prefer to use keys over passphrases if there are no humans involved. The interface is almost the same:

use themis::secure_cell::SecureCell;
use themis::keys::SymmetricKey;

// Generate a new key if you don't have one:
let master_key = SymmetricKey::new();
// Or use an existing value that you store somewhere:
let master_key = base64::decode("b0gyNlM4LTFKRDI5anFIRGJ4SmQyLGE7MXN5YWUzR2U=")?;

let cell = SecureCell::with_key(&master_key)?.seal();

let message = b"precious message";

let encrypted = cell.encrypt(&message)?;
let decrypted = cell.decrypt(&encrypted)?;

assert_eq!(decrypted, message);

Technical notes

There are no significant deviations from RFC 3.8.

The code sample is updated to be similar to other languages where it's a showcase for Secure Cell API rather than a copy of integration test tool. Secure Cell is not really designed for generic file encryption so we'd rather not give a wrong idea.

Checklist

• Change is covered by automated tests
• Benchmark results are attached (only Core)
• The coding guidelines are followed
• Public API has proper documentation
• Example projects and code samples are up-to-date
• Changelog is updated

[ilammy]

This PR attempts to beat the usual pattern “more tests than code” by probably having more API docs than tests or code 😂 At least, they took comparable amount of time to porting SwiftThemis tests to Rust.