Objects reference

There are three main crypto-objects in our library:

Secure Message

Secure Message is a sequence-independent, stateless, contextless messaging system. Works best for cases which don't require frequent sequential message exchange, APIs, low-bandwidth contexts.

Available modes: - sign/verify: message is signed by signature algorithm (ECDSA by default) and packed in special container. - encrypt/decrypt: message will be encrypted by randomly generated key (in RSA) or derived by ECDH (in ECDSA) symmetric algorithm with secure cell in seal mode.

Secure Message mode is selected by key parameters of themis_secure_message_wrap function or it's high-level representation in your language:

Using Secure Message is simple: - each party initializes the smessage object with it's private key and peer's public key. - then parties exchange messages and encrypt/decrypt them.

Secure Session

Secure Session is a sequence and session dependent, stateful messaging system. Works best for RPC, IPC, message and data exchange, socket-like datagram and event-passing layouts.

Possible usage scenarios: - A drop-in replacement for SSL/TLS - Protecting long-lived peer-to-peer message exchange - Secure data exchange with each piece of data bound to specific session (channel) context

Secure Session works in two stages: - session negotiation: getting the keys, exchanging of cryptographic material, generating ephemeral keys. - data exchange: exchanging messages.

Secure Session is separated from network layer, and works in two modes: - wrap/unwrap (callback API) - encrypt/decrypt (buffer API)

We suggest you dig a little bit of theory on Secure Session to understand various strategies better, or simply pick default behavior from examples and go on - they all are built safe.

Secure Cell

a multi-mode protected data container, can be used on files, SQL records, structured data records.

Available modes:

Key generation

Themis's objects rely on key generation / storage. Themis service object skeygen upon calling themis_gen_key_pair with algorithm parameter ("EC" or "RSA") generates a pair of keys, which exports via export_private_key() and export_public_key() functions.