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.
Additional documentation and class reference can be found in the Wiki section of the repository.
Install the gem
gem install encryption
or add it to your Gemfile
gem 'encryption'
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 # true
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 # true
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
end
The encryption
gem also provides a DSL for asymmetric encryption.
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' )
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.
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 )
This gem is distributed under The MIT License.
Itay Grudev <itay(at)grudev...com>