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.