The new API has more obvious naming and should be harder to misuse,
with encrypt/decrypt and sign/verify API clearly named and separated.

A common mistake with the old API was for users to accidentally using
sign/verify API instead of encryption by not providing a private key.
New API features more strict checks and prevents this kind of mistakes.

Currently the new API is implemented using the old functions (as they
are intended to be used). We'll switch the implementations in the next
commit and then deprecate the old API.

"char" may be signed or unsigned depending on a platform. Thus it is
necessary to cast it as "uint8_t" explicitly.

This effectively moves themis_secure_message_{wrap,unwrap} code to
these specific functions. However, with changes and simplifications.
For example, verification and decryption no longer has to guess the
type of the container: we now expect only encrypted containers when
decrypting and signed containers for verification.

Initially I wanted to reimplement themis_secure_message_{wrap,unwrap}
in terms of the new functions, however their behavior has several
idiosyncrasies so the old functions are still there with the same
implementation. For example, if the provided keys are invalid then
in in encrypt/decrypt mode the old API returns THEMIS_INVALID_PARAM
but in sign/verify mode it returns THEMIS_FAIL. The new API returns
THEMIS_INVALID_PARAM consistently (as it is evident from the tests).

Leave a comment in the code for developers so that they don't try
to (incorrectly) reimplement, for example, unwrap with decrypt and
verify or vice versa.

Actually mark the old functions them with a deprecation attribute. This
will produce warnings during compilation which should prompt the users
to migrate to the new API.

Add an exception to our test code which still needs to test the old API.
We treat warnings as errors and don't want to fail the build.

Bring in the updates in ThemisPP, we're gonna need them now to avoid
merge conflicts in the future.

C++ methods are already using the new names so just replace the calls
with the new ones and we're done here.

Rust methods already use new names so we only have to change the
implementation. It's quite repetetive and verbose but meh... we have
to call different functions with different interfaces. (It may be
possible to avoid some of the copypasta with macros but I doubt they
will be more maintainable than this.)

Java binding actually fails to build on CI due to deprecation warnings
from the core library so we have to make these changes anyway.

Current JNI interface is not flexible enough with a single boolean
flag. Replace the flag with an integer action mode, provide and use
the constants in Java code. JNI interface is an implementation detail
so we can make this change freely.

Easy as with C++: just use the new functions and we're done.
All object methods already have proper names.

Co-Authored-By: ilammy <a.lozovsky@gmail.com>

These functions should be useful for Themis users so make them
available. We're going to use them internally as well to validate
key inputs where appropriate.

Note that in Rust we no longer need to link against Soter because the
functions are now exported from Themis. Also, drop the long and detalied
rant about pointer alignment. It's not very realistic to do anything
about it and it does not cause any trouble yet. I guess we can let it
pass until we encounter SIGBUS in the wild. Just assume that the
pointers are correctly aligned (and try to keep them aligned in Rust).

Add key validation to the new Secure Message API in Themis Core. Now the
functions validate the key checksums and make sure that correct private
and public keys are used. This should avoid unexpected behavior when
a private key is used instead of a public one or vice versa.

Add validation and human-friendly error messages to ThemisPP if the
user passes incorrect keys to constructor.

Add key validation to JavaScript wrapper as well. This is similar to
ThemisPP but we use NAN's error reporting instead of C++ exceptions.

All language wrappers actually have a separate module named "keygen" or
something like that. However, the core library keeps key generation
routines in secure_message.c which is weird. Move key generation and
validation into a separate source file at least. C does not have modules
per se, but this makes much easier to locate keygen functions.

Put reusable code there and keep business logic of key validation
in Secure Message. Later we will be able to reuse the key validation
routines for Secure Session.

Put reusable code there and keep business logic of key validation
in Secure Message. Later we will be able to reuse the key validation
routines for Secure Session.

These checks are now performed by valid_{private,public}_key() calls.
We don't need to explicitly check for NULL and empty from now on.

The users may actually be interested in the status code returned
for key validation so provide a separate function that returns more
detailed information about the keys.

Check for the key kind in themis_is_valid_key(), it's not just keys
using Soter containers. For example, Secure Session messages use them
too and they are not keys.

Also use the correct tag field instead of the whole struct. Do not
cause unnecessary undefined behavior.

Use "asym" as a part of their names because there are three kinds of
keys visible for Themis users:

  - ECDSA asymmetric keys for Secure Message and Secure Session
  - RSA asymmetric keys for Secure Message (and maybe Secure Session)
  - symmetric (AES) keys derived from master key for Secure Cell

Let's clearly state that we dead with asymmetric keys here.