master-crypt 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d66fc7a3d34de5271f109f302daad32070724869cece105c062a844ae3bcc405
-  data.tar.gz: '06158f18251f6157085123568ee9818e46fea1e1f4dbf2db89f1f8293b7b7d6e'
+  metadata.gz: feb8bc6283d255c63b665645b2380b97a424973674b68c5e43ca1148d2104539
+  data.tar.gz: a5d4a0bd894035a9b099936a910210010c5de652574bb90fd0bc6e2fa3080480
 SHA512:
-  metadata.gz: da0d0b57b077b38d0e478d6940cf5c9de72b376cb8e9efbdccd0afefc04fabc1348fdf08ea014521ed3f2d747ed0afa240f027cd6fa8a26b090793e2a7804fb9
-  data.tar.gz: 3fabf752a22e46befa105e815e86964e1842c68e5d46f3d89c84f4a79be729103e893317c32d690999f28c6279c78aa5b5d39a377b76550caae35f2ba74a190c
+  metadata.gz: eb0ac83c13620f593102d8390376a692ef7a4a2fa8b4c7c8dd58da879d1b032cb3e9bf4821c28b72a115ca7ab8bb0de87b23c250d45b61ffb1feffa9c73281a4
+  data.tar.gz: 9da6ba87ab3b7eb58fc4be0e933d74d4fdbfc03c388cc7dd3508963eacefc044e52aa1c2ba6ef74ccbc95bca014ba107afe5a77d38b27b509aaebc6aae8954c9

data/README.md

@@ -1,15 +1,50 @@
-# master-crypt
+# Master Crypt
 
-## Usage
+[![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 master k3y"
-data = "Secret data..."
+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(data, [other_secret_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
 ```
 
@@ -22,13 +57,24 @@ 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 all specs + standardrb
 
 ```sh

data/lib/master_crypt.rb

@@ -4,23 +4,58 @@ require "base64"
 require "digest"
 
 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 "Master key must not be blank" if master_key.nil? || master_key.empty?
+    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
+    # 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 "At least 1 secret key is required" if !secret_keys.is_a?(Array) || secret_keys.empty?
-      raise "Secret keys must not be blank" unless secret_keys.select(&:empty?).empty?
+      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
@@ -42,16 +77,26 @@ class 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
@@ -68,7 +113,7 @@ class 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 @@
 class MasterCrypt
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: master-crypt
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Cian McElhinney
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-08-03 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