Secure Cell passphrase API: JavaThemis

[ilammy]

With preparatory changes in #634, this PR adds actual passphrase API as described in RFC 3.9.

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

import com.cossacklabs.themis.SecureCell

val cell = SecureCell.SealWithPassphrase("secret")

val message = "precious message".toByteArray()

val encrypted = cell.encrypt(message)
val decrypted = cell.decrypt(encrypted)

assertArrayEquals(decrypted, message)

And the same API in Java:

import com.cossacklabs.themis.SecureCell;

SecureCell.Seal cell = SecureCell.SealWithPassphrase("secret");

byte[] message = "precious message".getBytes(StandardCharsets.UTF_8);

byte[] encrypted = cell.encrypt(message);
byte[] decrypted = cell.decrypt(encrypted);

assertArrayEquals(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:

import com.cossacklabs.themis.SecureCell
import com.cossacklabs.themis.SymmetricKey

// Generate a new key if you don't have one:
val masterKey = SymmetricKey()
// Or use an existing value that you store somewhere:
val masterKey = Base64.Decoder.decode("b0gyNlM4LTFKRDI5anFIRGJ4SmQyLGE7MXN5YWUzR2U=")

val cell = SecureCell.SealWithKey(masterKey)

val message = "precious message".toByteArray()

val encrypted = cell.encrypt(message)
val decrypted = cell.decrypt(encrypted)

assertArrayEquals(decrypted, message)

Unicode considerations

Note that passphrase API uses UTF-8 by default for compatibility with other platforms. If you need to use a different encoding, there are variety of interfaces to allow that:

• SecureCell#SealWithPassphrase(String) — use UTF-8, the default
• SecureCell#SealWithPassphrase(String, Charset) — use the specified charset
• SecureCell#SealWithPassphrase(byte[]) — in case you already have it encoded

Technical notes

There are no deviations from RFC 3.9 with respect to passphrase API.

We introduce a new helper – PassphraseBytes – and extend the JNI API to support passphrases.

Checklist

• Dependencies are merged: Update JavaThemis Secure Cell API #634, this PR is rebased
• Change is covered by automated tests
• Benchmark results are attached (no JVM benches)
• The coding guidelines are followed
• Public API has proper documentation
• Example projects and code samples are up-to-date (later)
• Changelog is updated

[ilammy]

Whew, this PR is ready for review now.

[Lagovas]

lgtm

[vixentael]

cipher!

[vixentael]

so here we test that this method will fail if receive inconsistent string and encoding?

[ilammy]

so here we test that this method will fail if receive inconsistent string and encoding?

Yeah, that's the idea behind this test.

PassphraseBytes#encodePassphrase is not directly tested, but here we ensure that it's actually used, not String#getBytes (which would have turned "пароль" into "??????" here). Encoding conversion happy path is indirectly verified by other passphrase tests.