Underlock

Underlock makes it dead simple to encrypt and decrypt your data and files. It comes with little to no dependencies and has a very small API surface.

Installation

Add this line to your application's Gemfile:

gem 'underlock'

And then execute:

$ bundle

Or install it yourself as:

$ gem install underlock

Initialization

Underlock::Base.configure do |config|
  config.public_key  = File.read('./key.pub')
  config.private_key = File.read('./key.priv')
  config.cipher      = OpenSSL::Cipher.new('aes-256-gcm')
end

For the

config.cipher

OpenSSL::Cipher.ciphers

Important Note: Choose your algorithm carefully and stick to it. It'll kind of suck to be not able to decrypt your encrypted data.

Generating Public/Private keypair

key = OpenSSL::PKey::RSA.new 4096
puts key.to_pem
puts key.public_key.to_pem

Usage

Encrypting Strings/Text

irb> Underlock::Base.encrypt("super secret message")
=> #<:encryptedentity:0x007fef2e4b8320>

Underlock::EncryptedEntity

encrypted_entity.value
encrypted_entity.key
encrypted_entity.iv # iv stands for initialization vector

You should persist or store the

key

iv

value

Decrypting Strings/Text

• Create an instance of

  Underlock::EncryptedEntity

  , use the

  key

  and

  iv

  collected in the previous steps.

irb> encrypted_entity = Underlock::EncryptedEntity.new(value: value, key: key, iv: iv)

• Decrypt using one of the following methods:

irb> encrypted_entity.decrypt

irb> Underlock::Base.decrypt(encrypted_entity)

Encrypting Files

To encrypt files, instead of passing a

String

File

Underlock::Base.encrypt

irb> file = File.open('/path/to/your/secret/file.txt')
irb> Underlock::Base.encrypt(file)
=> #<:encryptedentity:0x007fef2e4b8320>

The return value is an instance of

Underlock::EncryptedEntity

encrypted_entity.encrypted_file
encrypted_entity.key
encrypted_entity.iv # iv stands for initialization vector here

#encrypted_file

File

Decrypting Files

• Create an instance of

  Underlock::EncryptedEntity

  , use the

  key

  and

  iv

  collected in the previous steps.

irb> file = File.open('/path/to/your/secret/file.txt.enc')
irb> encrypted_entity = Underlock::EncryptedEntity.new(encrypted_file: file, key: key, iv: iv)

• Decrypt using one of the following methods:

irb> encrypted_entity.decrypt

irb> Underlock::Base.decrypt(encrypted_entity)

Following naming scheme is followed when encrypting/decrypting files:

| original file name | encrypted file name | decrypted file name | |--------------------|---------------------|---------------------| | file.pdf | file.pdf.enc | file.decrypted.pdf |

Development

After checking out the repo, run

bin/setup

rake spec

bin/console

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/metaware/underlock.

License

The gem is available as open source under the terms of the MIT License.