Secure Message

Secure Message is a lightweight service that can help deliver some message or data to your peer in a secure manner. It provides a simple way to protect your messages and bind them to the credentials of the communicating peers through the use of strong cryptography. It adds data confidentiality, integrity, and authenticity to your message in a single go (single function call).

Some of the features of Secure Message are: strong data encryption, message integrity and authentication, key generation (both RSA and ECC), stateless, easy-to-use API.

Secure Message assumes that peers have each other's public key that they trust. Then they can freely exchange any messages with a high level of security and little overhead.

Secure Message comes in two flavours: signed message (integrity and authenticity) and encrypted message (confidentiality, integrity, and authenticity).

Signed message

Signed message is useful for cases where you don't need data confidentiality. It allows the receiver to verify the origin and integrity of the data while still allowing intermediate nodes to process it accordingly (for example, route data based on its type).

Encrypted message

Encrypted message is useful when you need the full stack of protection for your data — in most cases, you will be using this flavour. The encrypted message currently uses Secure Cell in Seal mode for data protection.

KDF (key derivation function)

Themis Secure Message uses PBKDF2 and RFC 6189 p 4.5.1 as KDFs, and static salt under the hood.

Implementation details

As described above, Secure Message may be used in two modes:

  1. sign/verify (integrity and authenticity only) mode;
  2. encrypt/decrypt (confidentiality, integrity and authenticity; authenticity is provided through the use of EC cryptography) mode.

In sign/verify mode the message will be signed by the appropriate signature algorithm (ECDSA by default) and packed into THEMIS_SIGNED_MESSAGE_CONTAINER.

In encrypt/decrypt mode the message will be encrypted by a randomly generated symmetric key (in RSA) or derived by ECDH (in ECDSA). All the additional necessary data for encryption will be derived by Themis and packed into the THEMIS_ENCRYPTED_MESSAGE_CONTAINER.

The Secure Message interface is described in src/themis/secure_message.h.

If you need sign/verify mode of Secure Message then use the following API. Note that it either uses private key for signing messages or public key for verifying signatures.

themis_status_t themis_secure_message_sign(
        const uint8_t*  private_key,
        size_t          private_key_length,
        const uint8_t*  message,
        size_t          message_length,
        uint8_t*        signed_message,
        size_t*         signed_message_length);

themis_status_t themis_secure_message_verify(
        const uint8_t*  public_key,
        size_t          public_key_length,
        const uint8_t*  signed_message,
        size_t          signed_message_length,
        uint8_t*        message,
        size_t*         message_length);

For encrypt/decrypt mode of Secure Message, use the following API instead. It requires both private and public keys to be available for both parties.

themis_status_t themis_secure_message_encrypt(
        const uint8_t*  private_key,
        size_t          private_key_length,
        const uint8_t*  public_key,
        size_t          public_key_length,
        const uint8_t*  message,
        size_t          message_length,
        uint8_t*        encrypted_message,
        size_t*         encrypted_message_length);

themis_status_t themis_secure_message_decrypt(
        const uint8_t*  private_key,
        size_t          private_key_length,
        const uint8_t*  public_key,
        size_t          public_key_length,
        const uint8_t*  encrypted_message,
        size_t          encrypted_message_length,
        uint8_t*        message,
        size_t*         message_length);

NOTE: The current implementations of verify and decrypt do not signal about extra data at the end of the wrapped message. Extra data is silently ignored and only the correctly signed or encrypted data is returned.

Thread Safety

Themis as a library is safe to use from multiple threads for Secure Message. However, access to individual shared objects may need to be synchronized by your application locks. Read more in the documentation section on thread safety.

Themis Server Simulator

Themis Server Simulator

Themis Server is an interactive simulator that can be used as a remote debugging server for Themis. It is aimed at helping engineers understand Themis. It can come in handy if you're just starting out with this encryption library.

It can come in handy if you're just starting out with Themis. Using the Themis Serer, you can avoid spending a lot of time and effort building your own client and server, making sure you get the keys right, etc. Using a simple 'remote party simulator' you can try out Secure Message (and Secure Session) in an interactive mode and use copying and pasting to test encryption/decryption of containers with Secure Cell.