attr_encrypter 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9deb2dc66f623007552ad4e619e4d96cbf1596bb2e6e327abc9319cb32c30f3f
+  data.tar.gz: baa889f1cd1de2b7abc32cd040709e0194fca2ac546c9355437b1814939294cb
+SHA512:
+  metadata.gz: 1304196d54904f124f56dcbf9b28388fdd32ec17aff3501c4fabb4c3a321347fff0e9a4ee9e70f09ffb32ea61f67f43c9e4ede355295a44a0ec42f6127f364ae
+  data.tar.gz: 71245009cf9f27e050c035ab90a90edfda05b4ba0e47772c7242c57053442aefa87b1001a58e33dfc43c1a02833464c62c84cc82738fc55c1566dd90cf58a0e6

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## v1.0.0
+
+* Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Michael van Rooijen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,212 @@
+# AttrEncrypter
+
+[![Gem Version](https://badge.fury.io/rb/attr_encrypter.svg)](https://badge.fury.io/rb/attr_encrypter)
+[![Test Status](https://github.com/mrrooijen/attr_encrypter/workflows/Test/badge.svg)](https://github.com/mrrooijen/attr_encrypter/actions)
+
+Encrypts/Decrypts, with key rotation, attributes on classes, using [RbNaCl] ([libsodium]).
+
+This library was developed for- and extracted from [HireFire].
+
+The documentation can be found on [RubyDoc].
+
+
+### Compatibility
+
+- Ruby 2.5+
+- RbNaCl 7.0+
+
+
+### Installation
+
+Ensure that you've installed [libsodium], then add the gem to your Gemfile and run `bundle`.
+
+```ruby
+gem "attr_encrypter", "~> 1"
+```
+
+
+### Example
+
+```rb
+class Account
+  include AttrEncrypter::Accessors
+
+  # Defines the token accessor that seamlessly encrypts and decrypts
+  # data stored in @token_digest.
+  #
+  # Note: This won't define a @token instance variable, as state is
+  #       managed by the token_digest accessor using @token_digest.
+  #
+  # Note: You can add multiple attributes in a single attr_encrypter call.
+  #       e.g. `attr_encrypter ENV["KEYCHAIN"], :attr_a, :attr_b, :attr_c`
+  #
+  attr_encrypter ENV["KEYCHAIN"], :token
+
+  # Defines the token_digest accessor for storing and retrieving encrypted data.
+  # You don't directly use this accessor. Both read and write operations should
+  # always go through the token/token= methods provided by the attr_encrypter method.
+  #
+  # Consider making this accessor private. We'll leave it public for this demo.
+  #
+  attr_accessor :token_digest
+end
+```
+
+The `KEYCHAIN` environment variable must contain one or more keys. To generate a key, use the following function.
+
+```rb
+AttrEncrypter::Generator.generate_key
+```
+
+Place the generated key in the `KEYCHAIN` environment variable.
+
+The key consists of two segments, `<version>.<secret>`. The initial key has a version of 1. Versions determine which secrets will be used to encrypt and decrypt data.
+
+With the key in place you'll be able to store and retrieve data using the dynamically defined `token` accessor. Data assigned with `token=` will automatically be encrypted and stored with `token_digest=` in `@token_digest`.
+
+```rb
+account                 = Account.new
+account.token           = "my_secret_token"
+account.token_digest # => "1.yCZGH0QEk8+OPT0ad29wVmCkvr/7NXZjZtxu23v2j9HKfehndH0qv9MsF4ME\n"
+account.token        # => "my_secret_token"
+
+account.instance_variable_get("@token")        # => nil
+account.instance_variable_get("@token_digest") # => "1.yCZGH0QEk8+OPT0ad29wVmCkvr/7NXZjZtxu23v2j9HKfehndH0qv9MsF4ME\n"
+```
+
+The `@token_digest` value, like the keychain, also consists of two segments, `<version>.<data>`. The version matches the key version used to encrypt the data. This way, whenever data is accessed via `token`, it knows which secret to use to decrypt the data.
+
+To clear the token, simply assign `nil` to it.
+
+```rb
+account.token           = nil
+account.token_digest # => nil
+```
+
+
+### Active Record
+
+This is a general purpose library, and while its only hard dependency is rbnacl (libsodium), it was designed to work seamlessly with Active Record.
+
+```rb
+class User < ActiveRecord::Base
+  include AttrEncrypter::Accessors
+  attr_encrypter ENV["KEYCHAIN"], :token
+end
+```
+
+This assumes that you have a users table in the database, containing a column named `token_digest` of type text.
+
+
+### Key Rotation
+
+You'll want to rotate your keys at some point.
+
+First, add a second key to the keychain (`ENV["KEYCHAIN"]` in this case).
+
+To generate version 2 you can again use the following function, but this time using the version argument.
+
+```rb
+AttrEncrypter::Generator.generate_key 2 # or 3, 4, 5...
+```
+
+The keychain format allows any kind of whitespace to delimit keys.
+
+```rb
+ENV["KEYCHAIN"] = "<version>.<secret> <version>.<secret> <version>.<secret>"
+```
+
+For example.
+
+```rb
+ENV["KEYCHAIN"] = <<-EOS
+  1.c1dbb0dd094d4f40916c9cc0d8c974151949f105c499366b2acd9da76de7e5e9
+  2.3054563b2d80ae13c6e115405d6263e70be004f81eb3982f4a61ff9e9821e7d4
+EOS
+```
+
+Then simply reassign the token to re-encrypt the token with key version 2.
+
+```rb
+User.find_each do |user|
+  user.token = user.token
+  user.save
+end
+```
+
+The `user.token` (reader) decrypts the existing encrypted token from `token_digest` back to its unencrypted form using key version 1. It then uses the highest key version in the keychain, version 2, to re-encrypt the token with `user.token=` which overwrites the key version 1-encrypted token in `token_digest` with the key version 2-encrypted token. We then persist the key version 2-encrypted token to the database.
+
+
+#### Quick Facts
+
+* The order of the keys in the keychain is irrelevant.
+* The key with the highest version in the keychain is always used for encryption.
+* The key version used to encrypt data is stored along with the encrypted data (`<version>.<secret>`).
+* The version of the encrypted data determines which key's secret to use in order to decrypt data.
+* Keys can be safely removed from the keychain when none of the encrypted data requires it for decryption.
+* It's recommended that you increment key versions by 1 when generating a new key.
+
+
+### Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mrrooijen/attr_encrypter.
+
+First, install [libsodium] on your machine, and then install the remaining development dependencies:
+
+```
+$ bundle
+```
+
+To open an interactive console:
+
+```
+$ bundle console
+```
+
+To run the tests:
+
+```
+$ bundle exec rake
+```
+
+To view the code coverage (generated after each test run):
+
+```
+$ open coverage/index.html
+```
+
+To run the local documentation server:
+
+```
+$ bundle exec rake doc
+```
+
+To build a gem:
+
+```
+$ bundle exec rake build
+```
+
+To build and install a gem on your local machine:
+
+```
+$ bundle exec rake install
+```
+
+For a list of available tasks:
+
+```
+$ bundle exec rake --tasks
+```
+
+
+### Author / License
+
+Released under the [MIT License] by [Michael van Rooijen].
+
+[Michael van Rooijen]: https://michael.vanrooijen.io
+[HireFire]: https://www.hirefire.io
+[RubyDoc]: https://rubydoc.info/gems/attr_encrypter
+[MIT License]: https://github.com/mrrooijen/attr_encrypter/blob/master/LICENSE.txt
+[RbNaCl]: https://github.com/RubyCrypto/rbnacl
+[libsodium]: https://doc.libsodium.org/

data/lib/attr_encrypter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "base64"
+require "rbnacl"
+
+class AttrEncrypter
+
+  require "attr_encrypter/accessors"
+  require "attr_encrypter/boxes"
+  require "attr_encrypter/errors"
+  require "attr_encrypter/generator"
+  require "attr_encrypter/version"
+
+  DIGEST_FORMAT = /^(\d+)\.([a-zA-Z0-9\+\=\n\/]+)$/.freeze
+
+  def initialize(keychain)
+    @boxes = Boxes.new(keychain || "")
+  end
+
+  def encrypt(raw)
+    version   = @boxes.latest_version
+    encrypted = @boxes[version].encrypt(raw)
+    encoded   = Base64.encode64(encrypted)
+
+    "#{version}.#{encoded}"
+  end
+
+  def decrypt(digest)
+    segments  = digest.match(DIGEST_FORMAT)
+    version   = segments[1].to_i
+    encoded   = segments[2]
+    encrypted = Base64.decode64(encoded)
+
+    @boxes[version].decrypt(encrypted)
+  end
+end

data/lib/attr_encrypter/accessors.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module AttrEncrypter::Accessors
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  module ClassMethods
+
+    def attr_encrypter(keychain, *attributes)
+      attr_encrypter = AttrEncrypter.new(keychain)
+
+      attributes.each do |attribute|
+        reader         = "#{attribute}"
+        writer         = "#{attribute}="
+        digest_reader  = "#{attribute}_digest"
+        digest_writer  = "#{attribute}_digest="
+
+        define_method reader do
+          digest = send(digest_reader)
+
+          if digest.is_a?(String)
+            attr_encrypter.decrypt(digest)
+          end
+        end
+
+        define_method writer do |raw|
+          if raw.is_a?(String)
+            send(digest_writer, attr_encrypter.encrypt(raw))
+          else
+            send(digest_writer, nil)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/attr_encrypter/boxes.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class AttrEncrypter::Boxes
+
+  KEY_FORMAT = /^(\d+)\.([a-f0-9]{64})$/.freeze
+
+  def initialize(keychain)
+    @boxes = keychain.split.reduce({}) do |keys, item|
+      segments = item.match(KEY_FORMAT)
+      version  = segments[1].to_i
+      key      = [segments[2]].pack("H*")
+
+      keys.merge(version => RbNaCl::SimpleBox.from_secret_key(key))
+    end
+
+    if @boxes.empty?
+      raise AttrEncrypter::Errors::NoKeychainError
+    end
+
+    @boxes.freeze
+  end
+
+  def [](version)
+    @boxes[version]
+  end
+
+  def latest_version
+    @boxes.keys.max
+  end
+end

data/lib/attr_encrypter/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module AttrEncrypter::Errors
+  class NoKeychainError < StandardError
+    def message
+      "AttrEncrypter.new(keychain) requires a valid keychain containing at least one key." \
+      "\nYou can generate a key using AttrEncrypter::Generator.generate_key(version = 1)." \
+      "\nHere's a (version 1) key if you need one: #{AttrEncrypter::Generator.generate_key}" \
+    end
+  end
+end

data/lib/attr_encrypter/generator.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module AttrEncrypter::Generator
+
+  def self.generate_key(version = 1)
+    byte_size    = RbNaCl::SecretBox.key_bytes
+    secret_bytes = RbNaCl::Random.random_bytes(byte_size)
+    secret_hex   = secret_bytes.unpack("H*")[0]
+
+    "#{version}.#{secret_hex}"
+  end
+end

data/lib/attr_encrypter/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class AttrEncrypter
+  VERSION = "1.0.0"
+end

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: attr_encrypter
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Michael van Rooijen
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-06-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rbnacl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 13.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 13.0.1
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.9.25
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.9.25
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 5.14.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 5.14.1
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.18.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.18.5
+description:
+email:
+- michael@vanrooijen.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/attr_encrypter.rb
+- lib/attr_encrypter/accessors.rb
+- lib/attr_encrypter/boxes.rb
+- lib/attr_encrypter/errors.rb
+- lib/attr_encrypter/generator.rb
+- lib/attr_encrypter/version.rb
+homepage: https://github.com/mrrooijen/attr_encrypter
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/mrrooijen/attr_encrypter
+  source_code_uri: https://github.com/mrrooijen/attr_encrypter
+  changelog_uri: https://github.com/mrrooijen/attr_encrypter/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/mrrooijen/attr_encrypter/issues
+  documentation_uri: https://rubydoc.info/gems/attr_encrypter
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key:
+specification_version: 4
+summary: Encrypts/Decrypts, with key rotation, attributes on classes, using RbNaCl
+  (libsodium).
+test_files: []