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:
- If
peer_public_key
parameter is set to NULL, Secure Message will work in sign/verify mode and use signed message container. - If
peer_public_key
parameter is set to real public key, Secure Message will work in encrypt/decrypt mode and use encrypted message container.
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:
- seal: Themis takes care of everything, you encrypt and decrypt your container.
- token-protect: Length-preserving cipher. Themis automatically derives additional cryptographic material from user's context. Uses auth tag to authenticate decryption, auth tag is returned in separate buffer (as tokens) and can be stored separately. Requires some effort from the user.
- context-imprint: Length-preserving cipher without extra cryptomaterial and auth tag. Convenient, less demanding, but less secure.
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.