master-crypt 0.0.1 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30c1cf54ea583219381fdbed0e73f77f1f4b7168fe7bf5e3a568832d50be208f
-  data.tar.gz: 8add2b4b02dc45935f7317561b09e49a1e1bca477634a0bf3672ffaf8fc80a4c
+  metadata.gz: 9a11aff2304c6483147f3e7cc3d57996af1a4fd0ba730f10d3e130fec9730562
+  data.tar.gz: 86bfd58ddc3e941d344ea0ccb83ae608305ba86e5118243e19e47d9e306f1a20
 SHA512:
-  metadata.gz: b9b16ea951a97dd3577962c54303ec46ab1e3c9df2bd890408a925a69f65f71a555139facefca207c32f87d82bf8a4984e20711a95c0de807fa085c2a1ec9dca
-  data.tar.gz: d94abe5413f90b4a7cac2fcf875f834d6066904e0b2b36f3b3991a9123d89be19a19bd6b8484962a6ecf082b3c84bbab45bb06a825287498c12cc9aa41fdbd26
+  metadata.gz: 47d07d1d36a509892ee5cc4e05794233ef6d37c6f866896133a89abc92a0ed5af30dc2c1a7640925b71ff2f0dba5c52d378c66e3926d9c85cf5249df87ea663a
+  data.tar.gz: a8e56a738b7afc220129eb7bd7dd5762b10a8a8cf09285327917a83e68b2b167ee18725c903c2a232b4f4b67c16849aae64e9937817a11513ff9548d4a0a6bbb

data/README.md

@@ -1,12 +1,88 @@
-# master-crypt
+# Master Crypt
+
+[![CircleCI](https://circleci.com/gh/cianmce/master-crypt.svg?style=shield)](https://circleci.com/gh/cianmce/master-crypt)
+
+Master Key is a gem for encrypting data with a [master keying](https://en.wikipedia.org/wiki/Master_keying) approach
+
+This allows you to have a master key to decrypt the full set of data while also creating keys that can only decrypt a subset of data. These keys can then be safely distributed to relevant actors who will be only able to access their permitted data
+
+You can encrypt data with as many keys as needed, all of which will be able to decrypt the data while only causing a small encrypted data size increase of 129 bytes for each extra key
+
+
+## Installatio
+### Installing RbNaCl
+https://github.com/RubyCrypto/rbnacl#installation
+
+#### OS X users
+```sh
+brew install libsodium
+```
+
+#### FreeBSD users
+```sh
+pkg install libsodium
+```
+
+#### APT users
+
+```sh
+apt install libsodium-dev
+```
+
+### Installing MasterCrypt
+```sh
+gem install master_crypt
+```
+
+## Usage
+### Encrypting data with a master key
+```ruby
+require "master_crypt"
+
+master_key = "Very secure & random master k3y"
+other_secret_key = "Another very secure & random other k3y"
+plaintext = "Secret data..."
+master_crypt = MasterCrypt.new(master_key)
+
+encrypted_data = master_crypt.master_key_encrypt(plaintext, [other_secret_key])
+# encrypted_data can be decrypted with either the master_key or other_secret_key
+```
+
+### Decrypting data with a master key
+```ruby
+master_key = "Very secure & random master k3y"
+encrypted_data = "...."
+master_crypt = MasterCrypt.new(master_key)
+
+plaintext = master_crypt.master_key_decrypt(encrypted_data)
+```
+
+### Encrypting data with an array of keys
+
+```ruby
+secret_keys = ["array", "of", "secret", "keys"]
+encrypted_data = MasterCrypt.encrypt(plaintext, secret_keys)
+```
+
+### Decrypting data with a specific key
+
+```ruby
+MasterCrypt.decrypt(encrypted_data, secret_keys[0])
+```
 
 ## Development
 ```sh
 bundle install
 ```
 
-### Specs
-Run a
+### Run all specs + standardrb
+
 ```sh
+bundle exec rake
+```
 
+### Run specs using guard
+
+```sh
+bundle exec guard
 ```

data/lib/master_crypt.rb

@@ -3,11 +3,59 @@ require "rbnacl"
 require "base64"
 require "digest"
 
-module MasterCrypt
+class MasterCrypt
+  class CryptoError < StandardError; end
+
+  # Create a new MasterCrypt object with a master key which
+  # is used in `master_key_encrypt` and `master_key_decrypt`
+  #
+  # @param [String] Master key
+  #
+  # @return [MasterCrypt] A MasterCrypt object with a stored master key
+  def initialize(master_key)
+    raise ArgumentError, "Master key must not be blank" if master_key.nil? || master_key.empty?
+    @master_key = master_key
+  end
+
+  # Encrypts plaintext data with the master key and an optional
+  # list of additional secret keys
+  #
+  # @param plaintext [String] Plaintext data to be encrypted
+  # @param secret_keys [Array<String>] Optional list of
+  # additional secret keys to be used for encrypting data
+  #
+  # @return [String] Base64 representation of encrypted data
+  #
+  # @raise [ArgumentError] When secret keys are missing or blank
+  def master_key_encrypt(plaintext, secret_keys = [])
+    self.class.encrypt(plaintext, [@master_key] + Array(secret_keys))
+  end
+
+  # Decrypts encrypted data with the master key
+  #
+  # @param encrypted_data [String] Base64 representation of encrypted data
+  #
+  # @return [String] Decrypted plaintext data
+  #
+  # @raise [MasterCrypt::CryptoError] When master key or encrypted data is invalid
+  def master_key_decrypt(encrypted_data)
+    self.class.decrypt(encrypted_data, @master_key)
+  end
+
   class << self
-    def encrypt(plaintext, secrets)
-      raise "Secrets must not be blank" unless secrets.select(&:empty?).empty?
-      raise "At least 1 secret is required" if !secrets.is_a?(Array) || secrets.empty?
+    # Encrypts plaintext data with a list of secret keys
+    #
+    # @param plaintext [String] Plaintext data to be encrypted
+    # @param secret_keys [Array<String>] A list of secret keys to be used for encrypting data
+    #
+    # @return [String] Base64 representation of encrypted data
+    #
+    # @raise [ArgumentError] When secret keys are missing or blank
+    def encrypt(plaintext, secret_keys)
+      raise ArgumentError, "At least 1 secret key is required" if !secret_keys.is_a?(Array) || secret_keys.empty?
+      raise ArgumentError, "Secret keys must not be blank" unless secret_keys.select(&:empty?).empty?
+      # there's no point in using the same key multiple times
+      secret_keys.uniq!
 
       random_key = RbNaCl::Random.random_bytes(RbNaCl::SecretBox.key_bytes)
       # encrypt data with random_key
@@ -17,7 +65,7 @@ module MasterCrypt
       encrypted_data64 = Base64.strict_encode64(encrypted_data)
 
       # encrypt random_kets with each secret
-      encrypted_random_keys64 = secrets.collect do |secret|
+      encrypted_random_keys64 = secret_keys.collect do |secret|
         key = generate_key_from_secret(secret)
         box = RbNaCl::SimpleBox.from_secret_key(key)
 
@@ -29,16 +77,26 @@ module MasterCrypt
       Base64.strict_encode64(encrypted_data64 + "|" + encrypted_random_keys64.join(":"))
     end
 
-    def decrypt(encrypted_data, secret)
+    # Decrypts encrypted data with a provided secret key
+    #
+    # @param encrypted_data [String] Base64 representation of encrypted data
+    # @param secret_key [String] Secret key to be used to decrypt data
+    #
+    # @return [String] Decrypted plaintext data
+    #
+    # @raise [MasterCrypt::CryptoError] When secret key or encrypted data is invalid
+    def decrypt(encrypted_data, secret_key)
       encrypted_data64, encrypted_random_keys64_joined = Base64.strict_decode64(encrypted_data).split("|", 2)
 
       encrypted_random_keys64 = encrypted_random_keys64_joined.split(":")
-      key = find_key(encrypted_random_keys64, secret)
+      key = find_key(encrypted_random_keys64, secret_key)
 
       box = RbNaCl::SimpleBox.from_secret_key(key)
 
       ciphertext = Base64.strict_decode64(encrypted_data64)
       box.decrypt(ciphertext).force_encoding(Encoding::UTF_8)
+    rescue RbNaCl::CryptoError => e
+      raise CryptoError, e.message
     end
 
     private
@@ -55,7 +113,7 @@ module MasterCrypt
         rescue RbNaCl::CryptoError
         end
       end
-      raise "No valid key for '#{secret}'"
+      raise CryptoError, "Invalid secret key '#{secret}'"
     end
 
     def generate_key_from_secret(secret)

data/lib/master_crypt/version.rb

@@ -1,3 +1,3 @@
-module MasterCrypt
-  VERSION = "0.0.1"
+class MasterCrypt
+  VERSION = "0.0.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: master-crypt
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.5
 platform: ruby
 authors:
 - Cian McElhinney
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-08-01 00:00:00.000000000 Z
+date: 2021-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: standardrb
@@ -28,16 +28,16 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: '1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: '1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -70,86 +70,86 @@ dependencies:
   name: pry
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.13.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.13.0
 - !ruby/object:Gem::Dependency
   name: pry-byebug
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.9'
 - !ruby/object:Gem::Dependency
   name: pry-doc
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: guard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.18'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.18'
 - !ruby/object:Gem::Dependency
   name: guard-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 4.7.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 4.7.3
 - !ruby/object:Gem::Dependency
   name: rbnacl
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 7.1.1
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 7.1.1
+        version: '7.0'
 description: Allows for encrypting a single piece of data with multiple keys which
   can each be used to decrypt it
 email: 
@@ -176,7 +176,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="