This library provides a simple interface allowing access to the symmetric encryption functionality provided by the OpenSSL library. It supports private key generation, encryption/decryption with the key, as well as encryption/decryption with an arbitrary user-defined password.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
lib/sym
spec
.codeclimate.yml
.document
.gitignore
.rspec
.rubocop.yml
.travis.yml
.yardopts
Gemfile
LICENSE
README.md
Rakefile
sym-crypt.gemspec

README.md

SymCrypt

Simple Symmetric Encryption Using OpenSSL

Gem Version Downloads

Build Status Code Climate Test Coverage Issue Count

Gitter


Summary

The sym-crypt core library offers simple wrappers around OpenSSL with the following features:

  • Symmetric data encryption with either:
    1. A generated or supplied/known 256-bit key, and using the Cipher AES-256-cBC, which is the standard Cipher used by the US Government
    2. A user-provided password is used to construct a 128-bit key, and then encrypt/decrypt with the AES-128-CBC Cipher.
  • Automatic compression of the data upon encryption
  • Automatic base64 encryption to make all encrypted strings fit onto a single line.
  • This makes the format suitable for YAML or JSON configuration files, where only the values are encrypted.
  • Note: the generated key is a base64-encoded string of about 45 characters long. The decoded key is always 32 characters (or 256 bytes) long.

Usage

This library is a "wrapper" that allows you to take advantage of the symmetric encryption functionality provided by the {OpenSSL} gem (and the underlying C library). In order to use the library in your ruby classes, you should include the module Sym::Crypt.

Any class that includes Sym::Crypt is decorated with four instance methods [:encr, :decr, :encr_password, :decr_password], and three class methods [:create_private_key, :private_key, :private_key=].

Symmetric Encryption with a 256-bit Private Key

In the example below, we read a previously generated key from the environment variable. The key must be stored away from the data for obvious reasons.

require 'sym/crypt'

class TopSecret
  include Sym::Crypt
  # read the key from environmant variable and assign to this class.
  private_key ENV['PRIVATE_KEY']

  def sensitive_value=(value)
    @sensitive_value = encr(value, self.class.private_key)
  end

  def sensitive_value
    decr(@sensitive_value, self.class.private_key)
  end
end

Symmetric Encryption with a Password

In this example we encrypt sensitive value with a provided password. Password must not be nil or blank.

require 'sym/crypt'

class SensitiveStuff < Struct.new(:password)
  include Sym::Crypt  
  
  def sensitive_value=(value)
    @sensitive_value = encr_password(value, password)
  end

  def sensitive_value
    decr_password(@sensitive_value, password)
  end
end

Generating an Encryption Key

You can create a new key within any class that includes Sym::Crypt by calling the #create_private_key class method, which returns a new key every time it's called.

Classes that include Sym::Crypt are also decorated with a class instance variable @private_key and corresponding accessors #private_key and #private_key=. The writer assigns the key passed via the argument, while the reader returns a previously assigned key, or creates a new one, and assigns it. Subsequent calls will, thus, return the same key as the first call.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/kigster/sym-crypt

License

sym and sym-crypt library is © 2016-2017 Konstantin Gredeskoul.

The gem is available as open source under the terms of the MIT License. The library is designed to be a layer on top of OpenSSL, distributed under the Apache Style license.

Acknowledgements

Contributors:

Contributions of any kind are very much welcome from anyone.

Any pull requests will be reviewed promptly.

Please submit feature requests, bugs, or donations :)