Deprecate old Secure Cell API

[ilammy]

Following changes in #634 and #635, mark almost all Secure Cell API as deprecated. Provide inline replacement instructions where relevant. Suppress deprecation warnings in our own code that tests old API usage and has to rely on public constants which we cannot make private now.

Migration instructions

Constructors

Instead of using new SecureCell(...) and SecureCell.MODE... constants. Use SecureCell.ModeWithKey(...) factory methods now.

The following constructors are deprecated:

• new SecureCell(int mode) (no key specified)
• new SecureCell(byte[] key) (uses Seal mode)
• new SecureCell(byte[] key, int mode)

Use an appropriate replacement instead:

• SecureCell.SealWithKey(byte[] key)
• SecureCell.TokenProtectWithKey(byte[] key)
• SecureCell.ContextImprintWithKey(byte[] key)

Note that these factory methods return instances of interfaces like SecureCell.Seal, not SecureCell. You may need to update your fields and variable types. Encryption API is also different and not compatible, you will need to update method call sites too.

⚠️ Insecure ‘password’ API

The following constructors are not secure when used with short passwords:

• new SecureCell(String password) (uses Seal mode)
• new SecureCell(String password, int mode)

They are deprecated and you are strongly discouraged from using them. (You are safe only if the passwords are long enough, around 50+ characters.)

If you have to use passphrases that need to be remembered by humans, consider using new passphrase API instead (#635):

• SecureCell.SealWithPassphrase(String passphrase)

JavaThemis 0.13 supports passphrase API only in Seal mode. Other modes support only symmetric keys at the moment.

If you can store the encryption secret on electronic media, you’d be better off using symmetric key API. See #634 for an overview of updated API.

Note that new passphrase API is not compatible with the deprecated ‘password’ constructors. You will not be able to use new API to decrypt data encrypted by old API and vice versa. If you wish to switch the API, old data has to be decrypted with old API and reencrypted with the new one.

Encryption methods

All protect and unprotect methods of SecureCell class are deprecated. Use appropriate encrypt and decrypt methods of interfaces like SecureCell.Seal instead.

Easier encryption

Encryption API for Seal and Context Imprint mode now returns encrypted data directly. You no longer have to extract it out of SecureCellData object:

// Old:
byte[] encrypted = cell.protect(context, message).getProtectedData();

// NEW:
byte[] encrypted = cell.encrypt(message, context);

⚠️ Please note that new API accepts message and context in different order (context comes last).

Easier decryption

Decryption with new API no longer requires construction of SecureCellData object:

// Old:
byte[] decrypted = cell.unprotect(context, new SecureCellData(message, null));

// NEW:
byte[] decrypted = cell.decrypt(message, context);

Context is optional and changed ordering

New API accepts message and context in different order: context comes last.

If you do not use associated context, the argument can be omitted entirely.

// Old:
byte[] encrypted = cell.protect(null, message).getProtectedData();

// NEW:
byte[] encrypted = cell.encrypt(message);

⛔️ No inline key switching

The methods that accept a key as the first argument do not have direct counterpart in the new API:

• protect(byte[] key, byte[] context, byte[] data)
• unprotect(byte[] key, byte[] context, SecureCellData protected)

You will have to construct a new Secure Cell object to use a different key.

⛔️ No context as string

The methods that accept associated context as a String do not have direct counterpart in the new API:

• protect(String context, byte[] data)
• unprotect(String context, SecureCellData protected)

If you need compatibility, you can use new API with the context string converted to UTF-16 with getBytes("UTF-16").

⚠️ Insecure ‘password’ API

The methods that accept a ‘password’ string as the first argument are not secure when used with short passwords, similar to related constructors (see above). Consider user new passphrase API or symmetric keys instead.

Do not use the following methods:

• protect(String password, String context, byte[] data)
• unprotect(String password, String context, SecureCellData protected)

Checklist

• Dependencies are merged: Update JavaThemis Secure Cell API #634, Secure Cell passphrase API: JavaThemis #635, this PR is rebased
• Change is covered by automated tests
• The coding guidelines are followed
• Public API has proper documentation
• Example projects and code samples are up-to-date (will do separately)
• Changelog is updated

[ilammy]

This PR is now ready for review.

[vixentael]

Suggested change

	- `new SecureCell(String password)` ⚠️ **not secure**
	- `new SecureCell(String password)` ⚠️ **not recommended, insecure**

[vixentael]

👍