Ruby

Installation

To install Themis for ruby, type:

gem install rubythemis

and add

require 'rubythemis';

to your code.

Usage

Key Pair Generation

Themis supports Elliptic Curve and RSA algorithms for asymmetric cryptography

generator = Themis::SKeyPairGen.new
private_key, public_key generator.ec # or generator.rsa

Secure Message

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

Initialize encrypter:

smessage = Themis::Smessage.new(private_key, peer_public_key)

Encrypt message:

encrypted_message = smessage.wrap(message)
rescue ThemisError => e:
# error occured

Decrypt message:

encrypted_message = smessage.unwrap(message)
rescue ThemisError => e:
# error occured

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

scell_full = Themis::Scell.new(key, Themis::Scell::FULL_MODE)

Encrypt

encrypted_message = scell_full.encrypt(message, context)

Decrypt

decrypted_message = scell_full.decrypt(encrypted_message, context)

Token-protect Mode

Initialize encrypter/decrypter

scell_auto_split = Themis::Scell.new(key, Themis::Scell::AUTO_SPLIT_MODE)

Encrypt

encrypted_message, additional_auth_data  = scell_auto_split.encrypt(message, context)

Decrypt

decrypted_message = scell_auto_split.decrypt([encrypted_message, additional_auth_data], context)

Context-Imprint Mode

Initialize encrypter/decrypter

scell_user_split = Themis::Scell.new(key, Themis::Scell::USER_SPLIT_MODE)

Encrypt

encrypted_message = scell_user_split.encrypt(message, context)

Decrypt

decrypted_message = scell_user_split.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

NOTE: We consider wrap/unwrap more fit for typical ruby frameworks (we've taken a look at Ruby on Rails and Eventmachine), so present examples for wrap/unwrap only. However, if you find that fully-automatic send/receive might be a good use case for anything, let us know.

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).

wrap/unwrap

Initialize callbacks class:

class Callbacks_for_themis < Themis::Callbacks
    def get_pub_key_by_id(id)
        # retrieve public_key for id from trusted storafe (file, db etc.)
        return public_key
    end
end
Secure Session client

First, initialization:

@callbacks = Callbacks_for_themis.new
@session = Themis::Ssession.new(id, private_key, @callbacks)
# key method call - it is a client
connect_request = @session.connect_request() 
#send connect_request to server
#receive message from server
res, message = @session.unwrap(message)
  while res==Themis::SEND_AS_IS:
    # send message to server
  end

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 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.

@callbacks = Callbacks_for_themis.new
@session = Themis::Ssession.new(id, private_key, @callbacks)
#there is not connect_request call - it is a server
#receive message from client
res, message = @session.unwrap(message)
  while res==Themis::SEND_AS_IS:
    # send message to client
  end

Secure session is ready.

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