This project is currently stable, but will no longer be maintained.
Encryption
A simple to use wrapper of the Ruby OpenSSL Cipher library for Ruby and Rails applications. This gem provides an easy to use interface for symmetrical and asymmetrical encryption using RSA.
Documentation
Additional documentation and class reference can be found in the Wiki section of the repository.
Installation
Install the gem
gem install encryptionor add it to your Gemfile
gem 'encryption'Symmetric encryption
Using the global instance of the Encryption class
A simple example of how this gem works:
Encryption.key = 'A very long encryption key'
data = 'secret data'
encrypted_str = Encryption.encrypt( data )
Encryption.decrypt( encrypted_str ) == data # trueUsing your own instance of the Encryption class
If you need a separate instance with custom settings, different than the global Encryption instance, here is how you can do it:
encryptor = Encryption::Symmetric.new
encryptor.key = 'A very long encryption key'
data = 'secret data'
encrypted_str = encryptor.encrypt( data )
encryptor.decrypt( encrypted_str ) == data # trueConfiguration
For symmetric encryption/decryption you need to set an encryption key. You can also optionally set an initialization vector and a cipher.
Encryption.key - Your encryption key
Encryption.iv # Optional - Encryption initialization vector. Defaults to the character "\0" (Optional)
Encryption.cipher # Optional - Your encryption algorithm. Defaults to aes-256-cbc (Optional)
Running openssl list-cipher-commands in the terminal or calling OpenSSL::Cipher.ciphers in Ruby, which list all available ciphers.
You can configure both the global instance and a other instances with a block like this:
Encryption.config do |e|
e.key = 'Don't look!'
e.iv = 'This is probably the easiest way to use OpenSSL in Ruby'
e.cipher = 'camellia-128-ecb' # if you're feeling adventurous
endAsymmetric encryption (public/private key encryption)
The encryption gem also provides a DSL for asymmetric encryption.
Generating keypair
keypair = Encryption::Keypair.new # Accepts two optional arguments: size = 2048, password = nil
keypair.public_key # Instance of Encryption::PublicKey
keypair.private_key # Instance of Encryption::PrivateKey
# Or you can use this shorter version
public_key, private_key = Encryption::Keypair.generate( 2048 )
# You can dump keys to string
private_key.to_s
# or export them to PEM format
private_key.to_pem
# and optionally encrypt them with a passphrase
private_key.to_pem( 'passphrase' )Encryption::PublicKey and Encryption::PrivateKey
Both classes have the same methods:
# Import an existing key
Encryption::PrivateKey.new( filename[, password] ) # Import from file
Encryption::PrivateKey.new( string[, password] ) # Import from string
# Encrypt / Decrypt data
public_key = Encryption::PublicKey.new( 'existing key' )
public_key.encrypt( 'some secret data' )
public_key.decrypt( "some encrypted data" )Note: You can use both the public and the private key to encrypt or decrypt data.
Helpers
String helper
The gem adds the encrypt and decrypt methods to the String performing symmetric encryption. You can use them as follows:
# With the global Encryption instance
'Hello'.encrypt
'Hello'.encrypt!
'h3LL0'.decrypt
'h3LL0'.decrypt!
# With custom settings (and custom encryptor instance)
'secret'.encrypt( key: 'encryption key', iv: 'initialization vector', cipher: 'encryption cipher', encode: true )
# Note the encode option which will result in a base64 encoded string
'encrypted data'.decrypt( encoded: true ) # Will decrypt a base64 encoded string
# Or with a custom encryptor
encryptor = Encryption::Symmetric.new
encryptor.key = 'encryption key'
'secret data'.encrypt( encryptor: encryptor )License
This gem is distributed under The MIT License.
Author
Itay Grudev <itay(at)grudev...com>