Secure Cell passphrase API: ThemisPP

[ilammy]

Add support of Secure Cell passphrase API to ThemisPP. The API draft is described in RFC 3.1.

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:

#include <themispp/secure_cell.hpp>

auto cell = themispp::secure_cell_seal_with_passphrase("secret");

uint8_t message[] = "precious message";

std::vector<uint8_t> encrypted = cell.encrypt(message);
std::vector<uint8_t> decrypted = cell.decrypt(encrypted);

EXPECT_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 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:

#include <themispp/secure_keygen.hpp>

// Get a new key if you don't have one already:
std::vector<uint8_t> master_key = themispp::gen_sym_key();
// Or use an existing value that you store somewhere:
std::vector<uint8_t> master_key = base64::decode("b0gyNlM4LTFKRDI5anFIRGJ4SmQyLGE7MXN5YWUzR2U=");

auto cell = themispp::secure_cell_seal_with_key(master_key);

uint8_t message[] = "precious message";

std::vector<uint8_t> encrypted = cell.encrypt(message);
std::vector<uint8_t> decrypted = cell.decrypt(encrypted);

EXPECT_EQ(decrypted, message);

⚠️ NOTE: themispp::secure_cell_seal_t types are deprecated. Please use less ambiguous themispp::secure_cell_seal_with_key instead.

Other breaking changes

New Token Protect API

Previously Token Protect API was used like this:

auto cell = themispp::secure_cell_token_protect_t(master_key);

auto encrypted = cell.encrypt(message);
auto token = cell.get_token();

// ...

cell.set_token(token);
auto decrypted = cell.decrypt(encrypted);

This API was not thread-safe and prone to mistakes such as forgetting to set (or update) the authentication token before decryption.

New API provides much simpler and safer interface:

auto cell = themispp::secure_cell_token_protect_with_key(master_key);

// Since C++17:
auto [encrypted, token] = cell.encrypt(message);

// Since C++11:
std::vector<uint8_t> encrypted, token;
std::tie(encrypted, token) = cell.encrypt(message);

// C++03:
typedef themispp::secure_cell_token_protect_with_key::output_pair token_pair;
token_pair result = cell.encrypt(message);
// Access result.encrypted() and result.token()

// ...

auto decrypted = cell.decrypt(encrypted, token);

Note that APIs are incompatible and you will need to update encryption/decryption call sites during migration. Simply renaming Secure Cell classes will not be enough.

Iterator pair support

New API does not support iterator pairs (aka ranges or spans) directly for maintainability reasons. Avoiding direct iterator pair support allows us to have much fewer method overloads and keeps the code signficantly easier to follow.

If you have been using iterator pairs:

auto cell = themispp::secure_cell_seal_t(key_begin, key_end);

then you need to wrap them in themispp::input_buffer() with new API:

auto cell = themispp::secure_cell_seal_with_key(themispp::input_buffer(key_begin, key_end));

This is actual for all Secure Cell modes and all methods (construction, encryption, decryption).

Technical notes

As the saying goes, no battle plan survives contact with the enemy and this case is no exception. The implementation looks a little bit different from what is prescribed by the RFCs. However, user API says the same. Well, in fact, I consider C++ as a language to be hostile actor so this is more or less expected outcome.

This pull request is the most complex, the most unreadable, ridden with bugs and undefined behavior, and unpleasant in general of them all. In short, your typical C++ code. I started with C++ to run away from it as fast possible (as a side effect, it should run as fast as possible too).

I do not expect you to review it quickly. Take your time. Just open it up when you want to have your fix of suffering for the day or something.

Rant full of profanity

Why do you have to write all those input_buffer again and again – or pull in Boost monsters to avoid copying the code – instead of simply saying impl AsRef<[u8]>? *weeps in Rust*

Why do you have to have a PhD to write generic library code in C++? And it’s not PhD in math as you‘d probably need for Haskell. A PhD in law and criminal psychopathology will be much more appropriate here.

This is what happens to a language if a committee starts piling features onto features without ever deprecating anything. And in case your opponent attempts a counterargument you simply need to throw you hands up in the air and repeat “...but backwards compatibility!” and “undefined behavior!” until they go away.

Bjarne said that “there are two kinds of languages: the ones people complain about and the ones nobody uses”. So apparently they decided to design a language as bitchworthy as possible to get the adoption as high as C++ has.

But at least I‘m happy with this code. I really am. This is probably some kind of a Stockholm syndrome. Like, ‘clever’ languages like C++ reward ‘clever’ code. You get an immense sense of accomplishment once your tests actually compile and work the way you want to. This is where ‘boring’ languages like, say, Go or Java are different. C++ rewards you for writing clever, beautiful code. The only moment a program in Go is going to reward you is when the damn code does what it‘s supposed to be doing. Unfulfilling, boring, ugly as hell, but that‘s what people need – working code – as opposed to beautiful code that pleases the compiler. I‘m sorry I‘m weak before the machines but that‘s how it is.

I hope I don‘t have to touch this code again with a three-meter pole for the next year.

Whew! I feel a little bit better. Let’s do business now...

There‘s like 2.6k lines of code here. A significant part of them is documentation comments, copypasta in tests, dumb glue FFI code to interface with Themis Core, and a whole bunch of C++ magic to make all this work somehow. You‘ll probably have a better code review experience if you walk through it commit by commit.

Organizational notes

🚧 This branch depends on #577 so it has to wait before it is merged. To get better diffs the PR is targeted to a temporary branch which has to be removed before this PR is merged.

Once dependencies are merged, do the following:

• rebase ilammy:kdf/c++ onto cossacklabs:master
• retarget this PR to master
• delete ilammy/kdf/core

Follow the order. If the base branch is deleted early then this PR might get autoclosed.

Checklist

• Change is covered by automated tests
• Benchmark results are attached (pls no, I don‘t want to bench wrappers this month)
• The coding guidelines are followed
• Public API has proper documentation
• Example projects and code samples are updated
• Changelog is updated

[Lagovas]

lgtm

[ilammy]

PR #577 has been merged. I've rebased and retargeted this PR to master with no changes.