EvpBytesToKey

This gem is a pure Ruby implementation of OpenSSL's EVP_BytesToKey() function as it is used by the openssl command line utility. This function is used to generate a key and IV from a given password. (and optional salt)

The purpose of this gem is to make it easier to encrypt or decrypt data that has been encrypted by openssl with a password on the command line by replicating the logic used to derive a key and IV from a given password.

The OpenSSL documentation states:

Newer applications should use a more modern algorithm such as PBKDF2

Therefore use of this key derivation function is at your own risk. It is provided here to make interoperation with Ruby more convenient.

The is not a drop-in replacement for EVP_BytesToKey(). The original function supports specifying an algorithm (to determine key length and IV and IV length automatically), a message digest (so a digest other than MD5 can be used), and the number of rounds.

This is a drop-in replacement for EVP_BytesToKey() as it is used by the openssl command line utility, that is, using MD5 with 1 round. However, the options passed to this method require some knowledge of the algorithm in use, e.g., aes256 will use a 256-bit key and a 16-byte IV while rc4-40 will use a 40-bit key and no IV. These are provided as arguments to EvpBytesToKey::Key.new.

Installation

Add this line to your application's Gemfile:

gem 'evp_bytes_to_key'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install evp_bytes_to_key

Requirements

This gem requires Ruby 2.0.0 due to the format of its gemspec file but the EvpBytesToKey module has been tested to work in Ruby as low as 1.9.3.

Usage

Require the gem first:

require 'evp_bytes_to_key'

Set the arguments for key generation. All arguments are required.

# must be a string and may be empty
password = 'password'

# must be nil or an eight-byte string
salt = 'saltsalt'

# must be a positive integer divisible by 8
bits = 256

# must be an integer >= 0
iv_length = 16

Then use the Key class to get access to the key:

key = EvpBytesToKey::Key.new(password, salt, bits, iv_length)
=> #<EvpBytesToKey::Key:0x00007fe388095330
 @bits=256,
 @iv="\v\\\xA7\xB1\b\x1F\x94\xB1\xAC\x12\xE3\xC8\xBA\x87\xD0Z",
 @iv_hex="0b5ca7b1081f94b1ac12e3c8ba87d05a",
 @iv_length=16,
 @key="\xFD\xBD\xF3A\x9F\xFF\x98\xBD\xB0$\x13\x90\xF6*\x9D\xB3_J\xBA)\xD7uf7y\x971N\xBF\xC7\t\xF2",
 @key_hex="fdbdf3419fff98bdb0241390f62a9db35f4aba29d77566377997314ebfc709f2",
 @password="password",
 @salt="saltsalt">

key.key_hex
=> "fdbdf3419fff98bdb0241390f62a9db35f4aba29d77566377997314ebfc709f2"

key.iv_hex
=> "0b5ca7b1081f94b1ac12e3c8ba87d05a"

key.key
=> "\xFD\xBD\xF3A\x9F\xFF\x98\xBD\xB0$\x13\x90\xF6*\x9D\xB3_J\xBA)\xD7uf7y\x971N\xBF\xC7\t\xF2"

key.iv
=> "\v\\\xA7\xB1\b\x1F\x94\xB1\xAC\x12\xE3\xC8\xBA\x87\xD0Z"

These values can be compared to the values returned by the command line utility openssl:

echo -n "foo" | openssl enc -e -base64 -aes256 -S 73616c7473616c74 -pass pass:password -p

salt=73616C7473616C74
key=FDBDF3419FFF98BDB0241390F62A9DB35F4ABA29D77566377997314EBFC709F2
iv =0B5CA7B1081F94B1AC12E3C8BA87D05A
U2FsdGVkX19zYWx0c2FsdOnid6UWvFAXeeXIe+sL0l8=

Note that openssl requires the salt in hexadecimal format:

printf saltsalt | xxd
00000000: 7361 6c74 7361 6c74                      saltsalt

Examples

aes256 with a salt and IV

Encrypt with openssl:

echo -n "foo" | openssl enc -e -base64 -aes256 -S 73616c7473616c74 -pass pass:password

This returns:

U2FsdGVkX19zYWx0c2FsdOnid6UWvFAXeeXIe+sL0l8=

Decrypt with Ruby:

require 'openssl'
require 'base64'
require 'evp_bytes_to_key'

key = EvpBytesToKey::Key.new('password', 'saltsalt', 256, 16)
decipher = OpenSSL::Cipher.new('aes256')
decipher.decrypt
decipher.key = key.key
decipher.iv = key.iv
ciphertext = Base64.strict_decode64('U2FsdGVkX19zYWx0c2FsdOnid6UWvFAXeeXIe+sL0l8=')
ciphertext = ciphertext.byteslice(16..-1) if ciphertext.byteslice(0, 8) == 'Salted__'
plaintext = decipher.update(ciphertext) + decipher.final

This returns:

"foo"

Encrypt with Ruby:

require 'openssl'
require 'base64'
require 'evp_bytes_to_key'

salt = 'saltsalt'
key = EvpBytesToKey::Key.new('password', salt, 256, 16)
cipher = OpenSSL::Cipher.new('aes256')
cipher.encrypt
cipher.key = key.key
cipher.iv = key.iv
ciphertext = cipher.update('foo') + cipher.final
ciphertext = "Salted__#{salt}#{ciphertext}" if salt
ciphertext = Base64.strict_encode64(ciphertext)

This returns:

"U2FsdGVkX19zYWx0c2FsdOnid6UWvFAXeeXIe+sL0l8="

Decrypt with openssl:

echo -n "U2FsdGVkX19zYWx0c2FsdOnid6UWvFAXeeXIe+sL0l8=" | base64 --decode | openssl enc -d -aes256 -S 73616c7473616c74 -pass pass:password

This returns:

foo

rc4 with no salt and no IV

Encrypt with openssl:

echo -n "foo" | openssl enc -e -base64 -rc4 -nosalt -pass pass:password

This returns:

jpdE

Decrypt with Ruby:

require 'openssl'
require 'base64'
require 'evp_bytes_to_key'

key = EvpBytesToKey::Key.new('password', nil, 128, 0)
decipher = OpenSSL::Cipher.new('rc4')
decipher.decrypt
decipher.key = key.key
ciphertext = Base64.strict_decode64('jpdE')
plaintext = decipher.update(ciphertext) + decipher.final

This returns:

"foo"

Encrypt with Ruby:

require 'openssl'
require 'base64'
require 'evp_bytes_to_key'

key = EvpBytesToKey::Key.new('password', nil, 128, 0)
cipher = OpenSSL::Cipher.new('rc4')
cipher.encrypt
cipher.key = key.key
ciphertext = cipher.update('foo') + cipher.final
ciphertext = Base64.strict_encode64(ciphertext)

This returns:

"jpdE"

Decrypt with openssl:

echo -n "jpdE" | base64 --decode | openssl enc -d -rc4 -nosalt -pass pass:password

This returns:

foo

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/anothermh/evp_bytes_to_key.