Python

Installation

To install Themis for python, type:

pip install pythemis

and add

import pythemis;

to your code.

Usage

Key Pair Generation

Themis supports Elliptic Curve and RSA algorithms for asymmetric cryptography

obj = pythemis.skeygen.themis_gen_key_pair("EC"); # or themis_gen_key_pair("RSA") for RSA
private_key = obj.export_private_key();
public_key = obj.export_public_key();

Secure Message

For detailed explanation of Secure Message, see corresponding page in Objects guide

Initialize encrypter:

smessage=pythemis.smessage.smessage(private_key,peer_public_key);

Encrypt message:

try:
    encrypted_message = smessage.wrap(message);
except pythemis.themis_exception as e:
    e;

Decrypt message:

try:
    message = smessage.unwrap(encrypted_message);
except pythemis.themis_exception as e:
    e;

Secure Cell

All Secure Cell modes has an optional parameter context. For detailed explanation of various modes and their strengths and weaknesses, see objects guide and cryptosystem description for Secure Cell.

Seal Mode

Initialize encrypter/decrypter

enc_dec = pythemis.scell.scell(password);

Encrypt

encrypted_message = enc_dec.encrypt(message, context);

Decrypt

message = enc_dec.decrypt(encrypted_message, context);

Token-protect Mode

Initialize encrypter/decrypter

enc_dec = pythemis.scell.auto_split(password);

Encrypt

encrypted_message, additional_auth_data = enc_dec.encrypt(message, context);

Decrypt

message = enc_dec.decrypt(encrypted_message, additional_auth_data, context);

Context-Imprint Mode

Initialize encrypter/decrypter

enc_dec = pythemis.scell.user_split(password);

Encrypt

encrypted_message = enc_dec.encrypt(message, context);

Decrypt

message = enc_dec.decrypt(encrypted_message, context);

Secure Session

Secure Session can be used in two ways: - send/recieve - when communication flow is fully controled by secure session object - wrap/unwrap - when communication controled by user

Secure Session has two parties - called client and server for simplicity, but they could more precisely be called initiator and acceptor - they only differ in who starts the communication.

Secure Session relies on user passing a number of callback functions to send/receive messages, retrieve keys from local storage (see more at Secure Session cryptosystem description).

send/receive

Initialize callbacks class

class transport(object):
   def __init__(self, ...)
       #init commication channel with peer

   def send(self, message):
       # send message to peer

   def receive(self, buffer_length):
   #wait and receive buffer_length bytes from peer 
    return accepted message

   def get_pub_key_by_id(self, user_id):
       #retreive public key for peer user_id from trusted storage (file, db etc.)    
    return public_key
Secure Session client

First, initialize session:

 session=pythemis.session.session(client_id, client_private_key, transport); # transport - created callback object
 session.connect(); # this call say that it is client
 while !(session.is_established()):
   session.receive();

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

To send message over established session, use:

session.send(message);

To receive message from session:

message=ssession.receive()
Secure Session server

First, initialize session:

 session=pythemis.session.session(server_id, server_private_key, transport); # transport - created callback object
 #there is not connect() method call - it is server.
 while !(session.is_established():
   session.receive();

Sending/receiving message works same as in client

wrap/unwrap

Initialize callbacks class:

class pub_keys_storage(object):
   def __init__(self, ...)
       #initialise trusted public keys storage

   def get_pub_key_by_id(self, user_id):
       #retreive public key for peer user_id from trusted storage (file, db etc.)    
       return public_key
Secure Session client

First, initialization:

session=pythemis.session.session(client_id, client_private_key, transport); # transport - created callback object
encrypted_message = session.connect_request(); # this call define client part
#send encrypted_message to server
#receive encrypted_message from server
message = session.unwrap(encrypted_message);
while !message.is_control:
  # send message to server
  message = session.receive();

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

To encrypt outgoing message use:

encrypted_message = session.wrap(message);
#send encrypted_message to peer by any prefered method

To decrypt received message use:

#receive encrypted_message from peer 
message = session.unwrap(encrypted_message)
Secure Session server

First, initialize everything:

session=pythemis.session.session(server_id, server_private_key, transport); # transport - created callback object
#there is not connection_request method call - it is a server
#receive encrypted_message form 
message = session.unwrap(encrypted_message);
while message.is_control:
  # send message to peer
  message = session.receive();

Secure session is ready.

Send/receive works same way as client's example above.