shhh 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4ee814eff1d6f5243a0e3be1e31c85e0bb329512
-  data.tar.gz: b05dbb3702143ac23f3ef6dfee34fdfd62cac03b
+  metadata.gz: 326b0b0a82ce4ceb7e3a56a32f1f9546f88b9c83
+  data.tar.gz: c58225fb321bb2d459567f96140237829efcaef0
 SHA512:
-  metadata.gz: cb5177308cfe91b81ef89a9ad05c23e919b6c32f641f8c2ab6ff392898caad6fc7ad29525b41e55c232229e01350126c0da5a0e8a97436c0dfaf35231cf290c4
-  data.tar.gz: 19c2cd4f58536784b3e157667dfc76f5345fdadab397cd9370f1295c537294003ca5d04f457a332a114ef7bdd19a47cba9f27195b435fa2713f48040eb090b42
+  metadata.gz: 4dfcedd479814b71b5a0f0d4372e717fbcc66bd44e95b4053806cb280f9147aaa84bedac3c60793fc74ce12e45acf189f5df60ead4cc885bf1be9798b97a9475
+  data.tar.gz: 51eec0fd771a16205bc349a3f1de230c8623c942b4021655c3986d9bb6e4e2e4f9f13c736a8f1d558c0b126c2c63b73cd27e5d71efef9f66c01c65bcf8c27024

data/.document

@@ -0,0 +1,2 @@
+lib/ exe/ - README.md MANAGING-KEYS.md LICENSE 
+

data/.yardopts

@@ -0,0 +1,5 @@
+
+--protected
+--no-private
+--embed-mixin ClassMethods
+--embed-mixin Shhh::Extensions::InstanceMethods

data/README.md

@@ -3,12 +3,11 @@
 [![Gem Version](https://badge.fury.io/rb/shhh.svg)](https://badge.fury.io/rb/shhh)
 [![Downloads](http://ruby-gem-downloads-badge.herokuapp.com/shhh?type=total)](https://rubygems.org/gems/shhh)
 
-<br />
 
-[![Build Status](https://travis-ci.org/kigster/shhh.svg?branch=master)](https://travis-ci.org/kigster/shhh)
-[![Code Climate](https://codeclimate.com/github/kigster/shhh/badges/gpa.svg)](https://codeclimate.com/github/kigster/shhh)
-[![Test Coverage](https://codeclimate.com/github/kigster/shhh/badges/coverage.svg)](https://codeclimate.com/github/kigster/shhh/coverage)
-[![Issue Count](https://codeclimate.com/github/kigster/shhh/badges/issue_count.svg)](https://codeclimate.com/github/kigster/shhh)
+[![Build Status](https://travis-ci.org/kigster/secrets-cipher-base64.svg?branch=master)](https://travis-ci.org/kigster/secrets-cipher-base64)
+[![Code Climate](https://codeclimate.com/github/kigster/secrets-cipher-base64/badges/gpa.svg)](https://codeclimate.com/github/kigster/secrets-cipher-base64)
+[![Test Coverage](https://codeclimate.com/github/kigster/secrets-cipher-base64/badges/coverage.svg)](https://codeclimate.com/github/kigster/secrets-cipher-base64/coverage)
+[![Issue Count](https://codeclimate.com/github/kigster/secrets-cipher-base64/badges/issue_count.svg)](https://codeclimate.com/github/kigster/secrets-cipher-base64)
 
 ## Summary
 
@@ -279,6 +278,7 @@ end
 The library offers a typical `Shhh::Configuration` class which can be used to tweak some of the internals of the gem. This is really meant for a very advanced user who knows what she is doing. The following snippet is actually part of the Configuration class itself, but can be overridden by your code that uses and initializes this library. `Configuration` is a singleton, so changes to it will propagate to any subsequent calls to the gem.
 
 ```ruby
+require 'zlib'
 Shhh::Configuration.configure do |config|
   config.password_cipher = 'AES-128-CBC'  # 
   config.data_cipher = 'AES-256-CBC'
@@ -308,16 +308,13 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/kigste
  
 ### Natural Language Based API
 
-This is the spec for an alternative CLI that is at feature parity with the standard flag-based CLI.
+This is the proposed mini-idea/specification for an alternative CLI that is at a feature parity with the standard flag-based CLI.
 
     shhh encrypt with $key string 'hello' and save to output.enc 
-    shhh edit file 'hamlet.enc' encrypted with $key
-    shhh decrypt file'hamlet.enc' encrypted with $key \ 
-      and save to hamlet.txt
+    shhh edit file 'passwords.enc' encrypted with $key
+    shhh decrypt file /etc/secrets encrypted with $key save to ./secrets
     shhh encrypt with keychain $item file $input   
 
-
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -1,13 +1,14 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
-#require 'guard/notifiers/terminal_notifier'
-RSpec::Core::RakeTask.new(:spec)
-
 require 'yard'
-YARD::Rake::YardocTask.new do |t|
+
+
+YARD::Rake::YardocTask.new(:doc) do |t|
   t.files = %w(lib/**/*.rb exe/*.rb - README.md MANAGING-KEYS.md LICENSE)
   t.options.unshift('--title', '"Shhh – Symmetric Key Encryption for Your Data"')
-  system('open doc/index.html')
+  t.after = ->() { exec('open doc/index.html') }
 end
 
+RSpec::Core::RakeTask.new(:spec)
+
 task :default => :spec

data/lib/shhh/app/cli.rb

@@ -16,10 +16,42 @@ require_relative 'output/stdout'
 
 module Shhh
   module App
-    class CLI
+    # This is the main interface class for the CLI application.
+    # It is responsible for parsing user's input, providing help, examples,
+    # coordination of various sub-systems (such as PrivateKey detection), etc.
+    #
+    # Besides holding the majority of the application state, it contains
+    # two primary public methods: +#new+ and +#run+.
+    #
+    # The constructor is responsible for parsing the flags and determining
+    # the the application is about to do. It sets up input/output, but doesn't
+    # really execute any encryption or decryption. This happens in the +#run+
+    # method called immediately after +#new+.
+    #
+    # {{Shh::App::CLI}} module effectively performs the translation of
+    # the +opts+ object (of type {Slop::Result}) and interpretation of
+    # users intentions. It holds on to +opts+ for the duration of the program.
+    #
+    # == Responsibility Delegated
+    #
+    # The responsibility of determining the private key from various
+    # options provided is performed by the {Shhh::App::PrivateKey::Handler}
+    # instance. See there for more details.
+    #
+    # Subsequently, +#run+ method handles the finding of the appropriate
+    # {Shhh::App::Commands::Command} subclass to respond to user's request.
+    # Command registry, sorting, command dependencies, and finding them is
+    # done by the {Shhh::App::Coommands} module.
+    #
+    # User input is handled by the {Shhh::App::Input::Handler} instance, while
+    # the output is provided by the procs in the {Shhh::App::Output} classes.
+    #
+    # Finally, the Mac OS-X -specific usage of the KeyChain, is encapsulated
+    # in a cross-platform way inside the {Shhh::App::Keychain} module.
 
+    class CLI
       attr_accessor :opts, :output_proc, :print_proc, :write_proc,
-                    :action, :password, :key
+                    :action, :password, :key, :input_handler, :key_handler
 
       def initialize(argv)
         begin
@@ -30,19 +62,27 @@ module Shhh
         end
         configure_color(argv)
         select_output_stream
-        self.action = { opts[:encrypt] => :encr, opts[:decrypt] => :decr }[true]
+
+        initialize_input_handler
+        initialize_key_handler
+        self.action        = { opts[:encrypt] => :encr, opts[:decrypt] => :decr }[true]
       end
 
       def run
         return Shhh::App.exit_code if Shhh::App.exit_code != 0
+        unless opts[:generate]
+          self.key = PrivateKey::Handler.new(opts,
+                                             input_handler).key
+        end
 
-        self.key = PrivateKey::Handler.new(self.opts).key unless opts[:generate]
-
-        return self.output_proc.call(command.run) if command
-
-        # command was not found. Reset output to printing, and return an error.
-        self.output_proc = print_proc
-        command_not_found_error!
+        if command
+          result = command.run
+          output_proc.call(result)
+        else
+          # command was not found. Reset output to printing, and return an error.
+          self.output_proc = print_proc
+          command_not_found_error!
+        end
 
       rescue ::OpenSSL::Cipher::CipherError => e
         error type:      'Cipher Error',
@@ -56,6 +96,10 @@ module Shhh
               reason:    (opts[:password] ? nil : 'Perhaps the key is password-protected?'),
               exception: e
 
+      rescue Shhh::Errors::InvalidPasswordPrivateKey => e
+        error type:      'Error',
+              details:   'Invalid password, private key can not decrypted.'
+
       rescue Shhh::Errors::Error => e
         error type:      'Error',
               details:   e.message,
@@ -86,7 +130,6 @@ module Shhh
         self.output_proc = opts[:output] ? self.write_proc : self.print_proc
       end
 
-
       def configure_color(argv)
         if opts[:no_color]
           Colored2.disable! # reparse options without the colors to create new help msg
@@ -94,6 +137,16 @@ module Shhh
         end
       end
 
+
+      def initialize_input_handler(handler = Input::Handler.new)
+        self.input_handler = handler
+      end
+
+      def initialize_key_handler
+        self.key_handler = PrivateKey::Handler.new(self.opts, input_handler)
+      end
+
+
       def command_not_found_error!
         if key
           h             = opts.to_hash
@@ -142,7 +195,6 @@ module Shhh
           o.separator ''
         end
       rescue StandardError => e
-        error exception: e
         raise(e)
       end
     end

data/lib/shhh/app/commands/generate_key.rb

@@ -14,7 +14,7 @@ module Shhh
 
           if opts[:password]
             new_private_key = encr_password(new_private_key,
-                                            Shhh::App::Input::Handler.new_password)
+                                            cli.input_handler.new_password)
           end
 
           clipboard_copy(new_private_key) if opts[:copy]

data/lib/shhh/app/input/handler.rb

@@ -4,7 +4,7 @@ module Shhh
   module App
     module Input
       class Handler
-        def self.ask
+        def ask
           retries ||= 0
           prompt('Password: ', :green)
         rescue ::OpenSSL::Cipher::CipherError
@@ -13,11 +13,15 @@ module Shhh
           nil
         end
 
-        def self.prompt(message, color)
+        def puts(*args)
+          STDERR.puts args
+        end
+
+        def prompt(message, color)
           HighLine.new(STDIN, STDERR).ask(message.bold) { |q| q.echo = '•'.send(color) }
         end
 
-        def self.new_password
+        def new_password
           password         = prompt('New Password     : ', :blue)
           password_confirm = prompt('Confirm Password : ', :blue)
 

data/lib/shhh/app/private_key/decryptor.rb

@@ -7,7 +7,7 @@ module Shhh
 
         attr_accessor :encrypted_key, :input_handler
 
-        def initialize(encrypted_key, input_handler = Shhh::App::Input::Handler)
+        def initialize(encrypted_key, input_handler)
           self.encrypted_key = encrypted_key
           self.input_handler = input_handler
         end
@@ -20,8 +20,8 @@ module Shhh
               retries ||= 0
               decrypted_key = decrypt(password)
             rescue ::OpenSSL::Cipher::CipherError => e
-              STDERR.puts 'Invalid password. Please try again.'
-              ((retries += 1) < 3) ? retry : raise(Shhh::Errors::InvalidPasswordPrivateKey.new(e))
+              input_handler.puts 'Invalid password. Please try again.'
+              ((retries += 1) < 3) ? retry : raise(Shhh::Errors::InvalidPasswordPrivateKey.new('Invalid password.'))
             end
           else
             decrypted_key = encrypted_key

data/lib/shhh/app/private_key/detector.rb

@@ -1,7 +1,7 @@
 module Shhh
   module App
     module PrivateKey
-      class Detector < Struct.new(:opts) # :nodoc:
+      class Detector < Struct.new(:opts, :input_handler) # :nodoc:s
         @mapping = Hash.new
         class << self
           attr_reader :mapping
@@ -13,20 +13,28 @@ module Shhh
 
         def key
           self.class.mapping.each_pair do |options_key, key_proc|
-            return key_proc.call(self.opts[options_key]) if self.opts[options_key]
+            return key_proc.call(opts[options_key], self) if opts[options_key]
           end
           nil
         end
       end
 
-      Detector.register :private_key, ->(key) { key }
-      Detector.register :interactive, -> { Input::Handler.prompt('Private Key: ', :magenta) }
-      Detector.register :keychain, ->(key_name) { KeyChain.new(key_name).find }
-      Detector.register :keyfile, ->(file) {
+      Detector.register :private_key,
+                        ->(key, *) { key }
+
+      Detector.register :interactive,
+                        ->(*, detector) { detector.input_handler.prompt('Please paste your private key: ', :magenta) }
+
+      Detector.register :keychain,
+                        ->(key_name, * ) { KeyChain.new(key_name).find }
+
+      Detector.register :keyfile,
+                        ->(file, *) {
         begin
           ::File.read(file)
         rescue Errno::ENOENT
           raise Shhh::Errors::FileNotFound.new("Encryption key file #{file} was not found.")
+          nil
         end
       }
     end

data/lib/shhh/app/private_key/handler.rb

@@ -1,6 +1,7 @@
 require_relative 'detector'
 require_relative 'base64_decoder'
 require_relative 'decryptor'
+require_relative '../input/handler'
 module Shhh
   module App
     module PrivateKey
@@ -9,24 +10,32 @@ module Shhh
       class Handler
         include Shhh
 
-        attr_accessor :opts, :key
+        attr_accessor :opts, :input_handler
+        attr_writer :key
+
+        def initialize(opts, input_handler)
+          self.opts          = opts
+          self.input_handler = input_handler
+        end
 
-        def initialize(opts)
-          self.opts = opts
 
+        # @return [String] key Private key detected
+        def key
+          return @key if @key
 
-          self.key =
-            begin
-              Detector.new(opts).key
-            rescue Shhh::Errors::Error => e
-              if Shhh::App::Args.new(opts).key? && key.nil?
-                raise e
-              end
+          @key = begin
+            Detector.new(opts, input_handler).key
+          rescue Shhh::Errors::Error => e
+            if Shhh::App::Args.new(opts).key? && key.nil?
+              raise e
             end
+          end
 
-          if key && key.length > 45
-            self.key = Decryptor.new(Base64Decoder.new(key).key).key
+          if @key && @key.length > 45
+            @key = Decryptor.new(Base64Decoder.new(key).key, input_handler).key
           end
+
+          @key
         end
       end
     end

data/lib/shhh/app.rb

@@ -1,12 +1,16 @@
 require 'shhh/data'
 require 'active_support/inflector'
 module Shhh
-  # The +App+ Module is responsible for handing user input and executing commands.
-  # Central class in this module is the +CLI+ class.
-
-  # This module is responsible for printing pretty errors and maintaining the
-  # future exit code class-global variable.
 
+  # The {Shhh::App} Module is responsible for handing user input and executing commands.
+  # Central class in this module is the {Shhh::App::CLI} class.
+  #
+  # Methods in this module are responsible for reporting errors and
+  # maintaining the future exit code class-global variable.
+  #
+  # It also contains several helpers that enable some additional functionality
+  # on Mac OS-X (such as using KeyChain for storing encryption keys).
+  #
   module App
     class << self
       attr_accessor :exit_code

data/lib/shhh/cipher_handler.rb

@@ -2,10 +2,11 @@ require 'base64'
 require_relative 'configuration'
 
 module Shhh
-  #
-  # +CipherHandler+ contains cipher-related utilities necessary to create
-  # ciphers, and seed them with the salt or iV vector,
-  #
+
+  # {Shhh::CipherHandler} contains cipher-related utilities necessary to create
+  # ciphers, and seed them with the salt or iV vector. It also defines the
+  # internal structure {Shhh::CipherHandler::CipherStruct} which is a key
+  # struct used in constructing cipher and saving it with the data packet.
   module CipherHandler
 
     CREATE_CIPHER = ->(name) { ::OpenSSL::Cipher.new(name) }

data/lib/shhh/configuration.rb

@@ -1,8 +1,24 @@
 module Shhh
-  # Application configuration Singleton class.
+  # This class encapsulates application configuration, and exports
+  # a familiar method +#configure+ for defining configuration in a
+  # block.
+  #
   # It's values are requested by the library upon encryption or
   # decryption, or any other operation.
-
+  #
+  # == Example
+  #
+  # The following is an actual initialization from the code of this
+  # library. You may override any of the value defined below in your
+  # code, but _before_ you _use_ library's encryption methods.
+  #
+  #     Shhh::Configuration.configure do |config|
+  #       config.password_cipher = 'AES-128-CBC'  #
+  #       config.data_cipher = 'AES-256-CBC'
+  #       config.private_key_cipher = config.data_cipher
+  #       config.compression_enabled = true
+  #       config.compression_level = Zlib::BEST_COMPRESSION
+  #     end
   class Configuration
     class << self
       attr_accessor :config

data/lib/shhh/errors.rb

@@ -1,4 +1,5 @@
 module Shhh
+  # All public exceptions of this library are here.
   module Errors
     # Exceptions superclass for this library.
     class Shhh::Errors::Error < StandardError; end

data/lib/shhh/version.rb

@@ -1,3 +1,3 @@
 module Shhh
-  VERSION = '1.3.0'
+  VERSION = '1.4.0'
 end

data/lib/shhh.rb

@@ -13,34 +13,70 @@ Shhh::Configuration.configure do |config|
 end
 
 #
-# _Include_ +Shhh+ in your class to enable functionality of this library.
-#
-# Once included, you would normally use +#encr+ and +#decr+ instance methods to perform
-# encryption and decryption of object of any type using a symmetric key encryption.
-#
-# You could also use +#encr_password+ and +#decr_password+ if you prefer to encrypt
-# with a password instead. The encryption key is generated from the password in that
-# case.
-#
-# Create a new key with +#create_private_key+ class method, which returns a new key every
-# time it's called, or with +#private_key+ class method, which either assigns, or creates
-# and caches the private key at a class level.
-#
-# ```ruby
-# require 'shhh'
-# class TestClass
-#   include Shhh
-#   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
-# ```
+# == Using Shhh Library
+#
+# 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 {Shhh}.
+#
+# The including class is decorated with four instance methods from the
+# module {Shhh::Extensions::InstanceMethods} and two class methods from
+# {Shhh::Extensions::ClassMethods} – for specifics, please refer there.
+#
+# The two main instance methods are +#encr+ and +#decr+, which as the name
+# implies, perform two-way symmetric encryption and decryption of any Ruby object
+# that can be +marshaled+.
+#
+# Two additional instance methods +#encr_password+ and +#decr_password+ turn on
+# password-based encryption, which actually uses a password to construct a 128-bit
+# long private key, and then uses that in the encryption of the data.
+# You could use them to encrypt data with a password instead of a randomly
+# generated private key.
+#
+# The library comes with a rich CLI interface, which is mostly encapsulated under the
+# +Shhh::App+ namespace.
+#
+# The +shhh+ executable that is the "app" in this case, and is a _user_ of the
+# API methods +#encr+ and +#decr+.
+#
+# Create a new key with +#create_private_key+ class method, which returns a new
+# key every time it's called, or with +#private_key+ class method, which either
+# assigns, or creates and caches the private key at a class level.
+#
+# == Example
+#
+#     require 'shhh'
+#
+#     class TestClass
+#       include Shhh
+#       # 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
+#
+# == Private Key
+#
+# They private key can be generated by +TestClass.create_private_key+
+# which returns but does not store a new random 256-bit key.
+#
+# The key can be assigned and saved, or auto-generated and saved using the
+# +#private_key+ method on the class that includes the +Shhh+ module.
+#
+# Each class including the +Shhh+ module would get their own +#private_key#
+# class-instance variable accessor, and a possible value.
+#
+# For example:
+#
+#
+
 module Shhh
   extend RequireDir
   init(__FILE__)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shhh
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -176,10 +176,12 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".codeclimate.yml"
+- ".document"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE
 - MANAGING-KEYS.md