Secure Session: the establishment of a session between two peers, within which the data can be securely exchanged with higher security guarantees. EC + ECDH, AES container.

Quickstart

Requirements

In addition to the common set of build tools, Themis currently requires either the OpenSSL or LibreSSL package with the developer version of the package (as it provides header files). In either case, we strongly recommend you using the most recent version of these packages.

Keypair generation interface

alg_t_p - template argument that sets the algorithm to be used. Value themispp::EC for Elliptic Curve or themispp::RSA for RSA

gen() - Generates key pair.

get_priv() - Returns generated private key.

get_pub() - Returns generated public key.

Example

// or themispp::secure_key_pair_generator_t<themispp::RSA> for RSAthemispp::secure_key_pair_generator_t<themispp::EC>g;std::vector<uint8_t>private_key=g.get_priv();std::vector<uint8_t>pub_key=g.get_pub();

Secure Message

The Secure Message functions provide a sequence-independent, stateless, contextless messaging system. This may be preferred in cases that don't require frequent sequential message exchange and/or in low-bandwidth contexts. It is secure enough for exchanging messages from time to time, but if you'd like to have Perfect Forward Secrecy and higher security guarantees, please consider using Secure Session instead.

The Secure Message functions offer two modes of operation:

In Sign/Verify mode, the message is signed using the sender's private key and is verified by the receiver using the sender's public key. The message is packed into a suitable container and ECDSA is used by default to sign the message (when RSA key is used, RSA+PSS+PKCS#7 digital signature is used).

In Encrypt/Decrypt mode, the message will be encrypted with a randomly generated key (in RSA) or a key derived by ECDH (in ECDSA), via symmetric algorithm with Secure Cell in seal mode (keys are 256 bits long).

Secure Cell

The Secure Сell functions provide the means of protection for arbitrary data contained in stores, such as database records or filesystem files. These functions provide both strong symmetric encryption and data authentication mechanisms.

The general approach is that given:

input: some source data to protect;

key: a password;

context: plus an optional "context information";

Secure Cell functions will produce:

cell: the encrypted data;

authentication tag: some authentication data.

The purpose of the optional "context information" (i.e. a database row number or filename) is to establish a secure association between this context and the protected data. In short, even when the password is known, if the context is incorrect, the decryption will fail.

The purpose of using the authentication data is to validate that given a correct password (and context), the decrypted data is indeed the same as the original source data.

The authentication data must be stored somewhere. The most convenient way is to simply append it to the encrypted data, but this is not always possible due to the storage architecture of your application. The Secure Cell functions offer variants that address this issue in different ways.

The encryption algorithm used by Secure Cell (by default) is AES-256. The length of the generated authentication data is 16 bytes.

Secure Cell is available in 3 modes:

Seal mode: the mode that is the most secure and easy to use. This is your best choice most of the time.

Token protect mode: the mode that is the most secure and easy to use. Also your best choice most of the time.

Context imprint mode: length-preserving version of Secure Cell with no additional data stored. Should be used carefully.

You can learn more about the underlying considerations, limitations, and features.

Secure Session

Secure Session is a sequence- and session- dependent, stateful messaging system. It is suitable for protecting long-lived peer-to-peer message exchanges where the secure data exchange is bound to a specific session context.

Secure Session operates in two stages: session negotiation where the keys are established and cryptographic material is exchanged to generate ephemeral keys and data exchange the where exchanging of messages can be carried out between peers.

Secure Session Workflow

Secure Session can be used in two ways:
- send/receive - when communication flow is fully controlled by the Secure Session object.
- wrap/unwrap - when communication is controlled by the user.

Secure Session has two parties that are called client and server for the sake of simplicity, but they could be more precisely called initiator and acceptor - the only difference between them is in who starts the communication.

Secure Session relies on the user's passing a number of callback functions to send/receive messages - and the keys are retrieved from local storage (see more in Secure Session cryptosystem description).

Secure Session client

First, initialise session:

transportt;themispp::secure_session_tsession(client_id,client_private_key,&t);// t - created transport callback object// this call say that it is clientsession.connect();while!(session.is_established()):session.receive();

After the loop finishes, Secure Session is established and is ready to be used.

To send a message over established session, use:

session.send(message);

To receive the message from session:

std::vector<uint8_t>message=ssession.receive();

Secure Session server

First, initialise session:

transportt;themispp::secure_session_tsession(server_id,server_private_key,&t);// t - created transport callback object// there is not connect() method call - it is server.while!(session.is_established()):session.receive();

Sending/receiving message works in a manner similar to the client side.

Secure Session server

First, initialise everything:

pub_key_storaget;themispp::secure_session_tsession(client_id,client_private_key,&t);//t - created transport callback object// there is not connection_request method call - it is a serverwhile(!session.is_established()){// receive message from serverstd::vector<uint8_t>answer_message=session.unwrap(message);// send answer_message to server}

Secure Session is ready.
Send/receive works in the same way as the client's example above. See the full example available in docs/examples/c++.

Secure Comparator is transport-agnostic and only requires the user(s) to pass messages in a certain sequence. The protocol itself is ingrained into the functions and requires minimal integration efforts from the developer.

Secure Comparator workflow

Secure Comparator has two parties — called client and server — the only difference between them is in who starts the comparison.

Secure Comparator client and server

std::stringshared_secret("shared_secret");themispp::secure_comparator_tclient(STR_2_VEC(shared_secret));themispp::secure_comparator_tserver(STR_2_VEC(shared_secret));std::vector<uint8_t>buf;// this defines client callbuf=client.init();// checks in a loop, imagine sending `buf` from client to server and backbuf=server.proceed(buf);buf=client.proceed(buf);buf=server.proceed(buf);buf=client.proceed(buf);boolresult_client=client.get();boolresult_server=server.get();

After the loop finishes, the comparison is over and its result can be checked by calling: comparator.get().