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 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 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.
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.
The unwrapping mode is activated by parsing the wrapped_message header.
NOTE: The current verify implementation doesn't signal about appending extra data to the end of a signed message and returns correct signed data, excluding the extra data at the end.