sym 2.5.3 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aca611feea26256020a9d946efbbdc7cba379ce4
-  data.tar.gz: 2948a5e41803333a67c7aae070a13d2742a0156a
+  metadata.gz: 4f617e5a540da0d9f51124c4ba3f8affa335593b
+  data.tar.gz: 5fe223d7450486ba4fc3b201bfb06311968f9963
 SHA512:
-  metadata.gz: 238dace75955c11031173d5584dc3672fc623c34dd0dd491948147e471750d7fdf8685c8b77b5f27db29a0317abd9fb70ea94da2286f7837c48ec0ea9db68073
-  data.tar.gz: 5678caa99c45624bb438954a3fc2bc9e70d1accb699104c0b061e244b53b18a444297b6953fe4438683b67a3174b8676fc38c7cb7a02258f28756f40cc9f35ec
+  metadata.gz: c17e78d532c9f3edbb075e1e1936619a187244a0e514b5b7600d6b686103f43af99b1f949846c489860875cb750c255bda8792ce5892163f1d968cb7498677d7
+  data.tar.gz: 4ae3a762791fcdf65417185ad0d0d3d9c85ef2d7b6db51cecd6d9ab4911768b125c10dba7e8815b92f9bb226230a92177cb309c0932253f5364b220b2ce4d687

data/CHANGELOG.md

@@ -4,6 +4,22 @@
 
 [Changes since the last tag](https://github.com/kigster/sym/compare/v2.5.1...HEAD)
 
+## [v2.6.0](https://github.com/kigster/sym/tree/v2.6.0) (2017-03-11)
+[Full Changelog](https://github.com/kigster/sym/compare/v2.5.3...v2.6.0)
+
+ * Added `Sym::MagicFile` API for easy access to encrypted files.
+ * Moving output processing into the `Sym::Application` class.
+
+## [v2.5.3](https://github.com/kigster/sym/tree/v2.5.3) (2017-03-09)
+[Full Changelog](https://github.com/kigster/sym/compare/v2.5.2...v2.5.3)
+
+ * Added a "\n" to all printouts to STDOUT as long as it's a TTY
+
+## [v2.5.2](https://github.com/kigster/sym/tree/v2.5.2) (2017-03-06)
+[Full Changelog](https://github.com/kigster/sym/compare/v2.5.1...v2.5.2)
+
+ * Minor bug fixes around `symit` bash script, and `--bash-support` flag.
+
 ## [v2.5.1](https://github.com/kigster/sym/tree/v2.5.0) (2017-03-06)
 [Full Changelog](https://github.com/kigster/sym/compare/v2.5.0...v2.5.1)
 

data/README.md

@@ -13,9 +13,11 @@
 
 <hr/>
 
+**March 10th, 2017**: Please read the blog post [Dead Simple Encryption with Sym](http://kig.re/2017/03/10/dead-simple-encryption-with-sym.html) launching this tool and a library. Please leave comments or questions in the discussion thread at the bottom of that post. Thanks!
+
 ## Description
 
-<div style="padding 20px; font-size: 13pt;">
+<div style="padding 40px; margin: 40px; font-size: 13pt;">
 
 <strong>sym</strong> is a command line utility and a Ruby API that makes it <em>trivial to encrypt and decrypt sensitive data</em>. Unlike many other existing encryption tools, <strong>sym</strong> focuses on usability and streamlined interface (CLI), with the goal of making encryption easy and transparent. The result? There is no longer any excuse for keeping your application secrets unencrypted or outside of your repo.<br /><br />
 
@@ -39,10 +41,11 @@ __Sym__ is a layer built on top of the [`OpenSSL`](https://www.openssl.org/) lib
 
 This gem includes two primary components:
 
- * [Rich command line interface CLI](#cli) with many features to streamline encryption/decryption.
- * Ruby API:
+ 1. [Rich command line interface CLI](#cli) with many features to streamline encryption/decryption.
+ 2.  Ruby API:
      * [Basic Encryption/Decryption API](#rubyapi) is activated by including `Sym` module in a class, it adds easy to use `encr`/`decr` methods.     
      * [Application API](#rubyapi-app) is activated by instantiating `Sym::Application`, and using the instance to drive sym's complete set of functionality, as if it was invoked from the CLI.
+     * [Sym::MagicFile API](#magic-file) is a convenience class allowing you to read encrypted files in your ruby code with a couple of lines of code.
      * [Sym::Configuration](#rubyapi-config) class for overriding default cipher, and many other parameters such as compression, cache location, zlib compression, and more.
 
 ### Massive Time Savers
@@ -176,7 +179,9 @@ Note the `diff` shown after save.
 
 ## Ruby API
 
-You start by including `Sym` module into your class or a module. Such class will be decorated with new class methods `#private_key` and `#create_private_key`, as well as instance methods `#encr`, and `#decr`.
+### Including `Sym` module
+
+Low-level encryption routines can be imported by including `Sym` module into your class or a module. Such class will be decorated with new class methods `#private_key` and `#create_private_key`, as well as instance methods `#encr`, and `#decr`.
 
 #### Class Method `#create_private_key()` 
 
@@ -207,7 +212,7 @@ end
 @key.eql?(SomeClass.private_key)  # => true (it was assigned)
 ```
 
-#### Encrypting and Decrypting Data
+#### Encrypting and Decrypting
 
 So how would we use this library from another Ruby project to encrypt and decrypt values?
 
@@ -246,7 +251,7 @@ They can be used independently of `encr` and `decr` to encrypt/decrypt any data
 
 <a name="rubyapi-app"></a>
 
-#### Full Application API
+### `Sym::Application`
 
 Since the command line interface offers much more than just encryption/decryption of data with a key, majority of these features are available through `Sym::Application` instance.
 
@@ -261,6 +266,50 @@ key  = Sym::Application.new(generate: true).execute
 # => '75ngenJpB6zL47/8Wo7Ne6JN1pnOsqNEcIqblItpfg4='
 ```
 
+### `Sym::MagicFile` for Reading Encrypted Data
+
+This is probably the easiest way to leverage Sym-encrypted files, by loading them into memory.
+
+`Sym::MagicFile` provides a very simple API for loading and reading encrypted files
+into memory, while supporting all of the convenience features of the rich
+application API.
+
+You initialize this class with just two things: a `pathname` to a file (encrypted
+or not), and the `key` identifier. The identifier can either be a filename, or
+OS-X Keychain entry, or environment variable name, etc — basically it is resolve
+like any other `-k <value>` CLI flag.
+
+#### Example: Using `Sym::MagicFile` with the `RailsConfig` gem
+
+In this example, we assume that the environment variable `$PRIVATE_KEY` contain
+the key to be used in decryption. Note that methods `#decrypt` and `#read` on `Sym::MagicFile` instance are synomymous.
+
+```ruby
+require 'sym/magic_file'
+require 'yaml'
+secrets = Sym::MagicFile.new('/usr/local/etc/secrets.yml.enc', 'PRIVATE_KEY')
+hash = YAML.load(secrets.decrypt)
+```
+
+Let's say that you are using [RailsConfig](https://github.com/railsconfig/config) gem for managing your Rails application setings. Since the gem allows appending settings from a hash, you can simply do the following in your `settings_initializer.rb`, and after all of the unencrypted settings are loaded:
+
+```ruby
+require 'config'
+require 'sym/magic_file'
+require 'yaml'
+Settings.add_source!(
+    YAML.load(
+        Sym::MagicFile.new(
+            '/usr/local/etc/secrets.yml.enc', 
+            'PRIVATE_KEY'
+        ).decrypt)
+    )
+Settings.reload!
+```
+
+### Ruby API Conclusion
+
+Using `Sym`'s rich ruby API you can perform both low-level encryption/decryption, as well as high-level management of encrypted files. By using `Sym::MagicFile` and/or `Sym::Application` classes you can access the entire set of functionality expressed vi the CLI, described in details below.
 
 <a name="cli"></a>
 ## Using `sym` with the Command Line

data/lib/sym/app/cli.rb

@@ -98,12 +98,9 @@ module Sym
       def execute
         return Sym::App.exit_code if Sym::App.exit_code != 0
         result = application.execute
-        case result
-          when Hash
-            self.output_proc ::Sym::App::Args.new({}).output_class
-            error(result)
-          else
-            self.output_proc.call(result)
+        if result.is_a?(Hash)
+          self.output_proc ::Sym::App::Args.new({}).output_class
+          error(result)
         end
         Sym::App.exit_code
       end

data/lib/sym/app/commands/base_command.rb

@@ -61,7 +61,7 @@ module Sym
         end
 
         def content
-          @content ||= (opts[:string] || (opts[:file].eql?('-') ? STDIN.read : File.read(opts[:file]).chomp))
+          @content ||= (opts[:string] || (opts[:file].eql?('-') ? STDIN.read : ::File.read(opts[:file]).chomp))
         end
 
         def to_s

data/lib/sym/app/output/file.rb

@@ -7,6 +7,7 @@ module Sym
         required_option :output
 
         def output_proc
+          Sym::App.log :info, "writing to a file #{opts[:output]}"
           ->(data) {
             ::File.open(opts[:output], 'w') { |f| f.write(data) }
           }

data/lib/sym/application.rb

@@ -51,8 +51,17 @@ module Sym
       end
     end
 
+    def process_output(result)
+      unless result.is_a?(Hash)
+        self.output.call(result)
+        result
+      else
+        result
+      end
+    end
+
     def execute
-      execute!
+      process_output(execute!)
     rescue ::OpenSSL::Cipher::CipherError => e
       { reason:    'Invalid key provided',
         exception: e }

data/lib/sym/magic_file.rb

@@ -0,0 +1,88 @@
+require 'sym/application'
+module Sym
+  # This class provides a very simple API for loading/reading encrypted files
+  # into memory buffers, while supporting all of the convenience features of the
+  # sym CLI.
+  #
+  # You initialize this class with just two things: a pathname to a file (encrypted
+  # or not), and the key identifier. The identifier can either be a filename, or
+  # OS-X Keychain entry, or environment variable name, etc — basically it is resolved
+  # like any other `-k <value>` CLI flag.
+  #
+  # == Example
+  #
+  # In this example, we assume that the environment variable $PRIVATE_KEY contain
+  # the key to be used in decryption. Note that methods +decrypt+ and +read+ are
+  # synomymous
+  #
+  #    require 'sym/magic_file'
+  #    magic = Sym::MagicFile.new('/usr/local/etc/secrets.yml.enc', 'PRIVATE_KEY')
+  #    YAML.load(magic.read)
+  #
+  # Or, lets say you are using the +config+ gem. Then you would do something like this:
+  #
+  #    require 'config'
+  #    Settings.add_source!(YAML.load(magic.decrypt))
+  #
+  class MagicFile
+    attr_accessor :pathname, :opts, :key_value, :action
+
+    def initialize(pathname, key_value, **opts)
+      init(key_value, opts, pathname)
+    end
+
+    # Returns decrypted string
+    def read
+      decrypt
+    end
+
+    # Encrypts +pathname+ to a +filename+
+    def encrypt_to(filename)
+      self.opts.merge!({output: filename})
+      encrypt
+    end
+
+    # Decrypts +pathname+ to a +filename+
+    def decrypt_to(filename)
+      self.opts.merge!({output: filename})
+      decrypt
+    end
+
+    # Returns encrypted string
+    def encrypt
+      self.opts.merge!({ encrypt: true })
+      action
+    end
+
+    # Returns decrypted string
+    def decrypt
+      self.opts.merge!({ decrypt: true })
+      action
+    end
+
+    private
+
+    def init(key_value, opts, pathname)
+      raise ArgumentError, 'pathname does not exist' unless ::File.exist?(pathname)
+      self.pathname  = pathname
+      self.opts      = opts || {}
+      self.key_value = key_value
+      self.opts.merge!({ file: pathname, key: key_value, quiet: true})
+    end
+
+    def action
+      app    = Sym::Application.new(opts)
+      result = app.execute
+      if result.is_a?(Hash)
+        log :error, result.inspect
+        raise result[:exception] if result[:exception]
+      else
+        return result
+      end
+    end
+
+    def log(*args)
+      Sym::App.log(*args, **opts)
+    end
+  end
+end

data/lib/sym/version.rb

@@ -1,5 +1,5 @@
 module Sym
-  VERSION = '2.5.3'
+  VERSION = '2.6.0'
   DESCRIPTION = <<-eof
     Sym is a command line utility plus a straightforward Ruby API that makes it easy to 
     transparently handle sensitive data such as application secrets using symmetric

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sym
 version: !ruby/object:Gem::Version
-  version: 2.5.3
+  version: 2.6.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-03-11 00:00:00.000000000 Z
+date: 2017-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colored2
@@ -299,6 +299,7 @@ files:
 - lib/sym/extensions/stdlib.rb
 - lib/sym/extensions/with_retry.rb
 - lib/sym/extensions/with_timeout.rb
+- lib/sym/magic_file.rb
 - lib/sym/version.rb
 - sym-3.0-cli.md
 - sym.gemspec