sym 2.5.1 → 2.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6862ecd0c07b12c1ee20a9d2f2bb070bf8912656
-  data.tar.gz: 98edcee0cd5c47c876cd002841b7aa1bff420bee
+  metadata.gz: aca611feea26256020a9d946efbbdc7cba379ce4
+  data.tar.gz: 2948a5e41803333a67c7aae070a13d2742a0156a
 SHA512:
-  metadata.gz: 97c4215175e2afd0ad94f01069cfab3690a2d50c1e9603ea9d6f956becaba8f969fdbaf173326815ab3f88630b9a58702c8d23d40f1c98f032982f5e57faf8d2
-  data.tar.gz: ce41e1adb186a492eef492e5d9e6699987fbeab95f0a4ee8271c2fe75a98654374633c33ae7fa11c6b1aa41f0072ede88b619126210ca3e4c7f82e692f481482
+  metadata.gz: 238dace75955c11031173d5584dc3672fc623c34dd0dd491948147e471750d7fdf8685c8b77b5f27db29a0317abd9fb70ea94da2286f7837c48ec0ea9db68073
+  data.tar.gz: 5678caa99c45624bb438954a3fc2bc9e70d1accb699104c0b061e244b53b18a444297b6953fe4438683b67a3174b8676fc38c7cb7a02258f28756f40cc9f35ec

data/README.md

@@ -15,11 +15,17 @@
 
 ## Description
 
-> __sym__ is a command line utility and a Ruby API that makes it _trivial to encrypt and decrypt sensitive data_. Unlike many other existing encryption tools, __sym__ focuses on usability and streamlined interface (CLI), with the goal of making encryption easy and transparent. The result? There is no excuse for keeping your application secrets unencrypted :) 
+<div style="padding 20px; 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 />
+
+<strong>sym</strong> uses <em>symmetric Encryption</em> which simply means that you will be using the same 256-bit key to encrypt and decrypt data. In addition to the private key, the encryption uses an IV vector. The library completely hides `iv` generation from the user, and automatically generates a random `iv` per encryption. Finally, each key can be uniquely password-protected (encrypted) and stored in OS-X Keychain, environment variable or a file.
+
+</div>
 
 ### Motivation
 
-The primary goal of this tool is to streamline and simplify handling of relatively sensitive data in the most trasparent and easy to use way as possible, without sacrificing security.
+The main goal when writing this tool was to streamline and simplify handling of sensitive data in a  trasparent and easy to use way without sacrificing security.
 
 Most common use-cases include:
 
@@ -33,15 +39,15 @@ __Sym__ is a layer built on top of the [`OpenSSL`](https://www.openssl.org/) lib
 
 This gem includes two primary components:
 
- * [Ruby API](#rubyapi) for enabling encryption/decryption of any data within any Ruby class, with extremely easy-to-use methods
- * [Rich command line interface CLI](#cli) with many additional features to streamline handling of encrypted data.
-
-_Symmetric Encryption_ simply means that we are using the same private key to encrypt and decrypt. In addition to the private key, the encryption uses an IV vector. The library completely hides `iv` generation from the user, and automatically generates a random `iv` per encryption.
-
+ * [Rich command line interface CLI](#cli) with many features to streamline encryption/decryption.
+ * 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::Configuration](#rubyapi-config) class for overriding default cipher, and many other parameters such as compression, cache location, zlib compression, and more.
 
 ### Massive Time Savers
 
-So how does `sym` substantiate its claim that it *streamlines* the encryption process? I thought about it, and turns out there are quite a few reasons:
+What are the time savers that we mentioned earlier?
  
   * By using Mac OS-X Keychain, `sym` offers a simple yet secure way of storing the key on a local machine, much more secure then storing it on a file system.
   * By using a password cache (`-c`) via an in-memory provider such as `memcached` or `drb`, `sym` invocations take advantage of password cache, and only ask for a password once per a configurable time period.
@@ -54,26 +60,53 @@ As you can see, we really tried to build a tool that provides good security for
 
 > Encrypting application secrets had never been easier! –– Socrates [LOL, -ed.]
 
-### How It Works
+## Using Sym
+
+#### Installation
+
+If you plan on using the library in your Ruby project with Bundler managing its dependencies, just include the following line in your `Gemfile`:
+
+    gem 'sym'
+
+And then run `bundle`.
+
+Or install it into the global namespace with `gem install` command:
+
+    $ gem install sym
+    $ sym -h
+    $ sym -E # see examples
+
+__BASH Completion__
+
+Optionally, after gem installation, you can also install bash-completion of gem's command line options, but running the following command (and feel free to use any of the "dot" files you prefer):
+
+    sym -B ~/.bashrc
+
+Should you choose to install it (this part is optional), you will be able to use "tab-tab" after typing `sym`, and you'll be able to choose from all of the supported flags.
+
+#### Typical Use-Case Scenario
 
-  1. You generate a new encryption key, that will be used to both encrypt and decrypt the data. The key is 256 bits, or 32 bytes, or 45 bytes when base64-encoded, and can be generated with `sym -g`.
-     * You can optionally password protect the key with `sym -gp`
-     * You can save the key into a file with `sym -gpo key-file` 
-     * Or you can save it into the OS-X Keychain, with `sym -gpx keychain-name`
-     * You can also cache the password, with `sym -gpcx keychain-name`
-     * Normally, `sym` will also print the resulting key to STDOUT.
+  1. You generate a new encryption key, that will be used to both encrypt and decrypt the data. The key is 256 bits, or 32 bytes, or 45 bytes when base64-encoded, and can be generated with `sym -g`. The key must be saved somewhere for later retrieval. The key should not be easily accessible to an attacker. Note, that while generating the key, you can:
+     * optionally password protect the key with `sym -gp`
+     * save the key into a file with `sym -gpo key-file` 
+     * save it into the OS-X Keychain, with `sym -gpx keychain-name`
+     * cache the password, with `sym -gpcx keychain-name`
+     * Normally, `sym` will print the resulting key to STDOUT
      * You can prevent the key from being printed to STDOUT with `-q/--quiet`. 
-  2. You then take a piece of sensitive __data__ that you want to encrypt. This can be a file or a string.
-  3. You can then use the key to encrypt sensitive __data__, with `sym -e [key-spec] [data-spec]`, passing it the key in several accepted ways. Smart flag `-k` automatically interpretes the source of the key, by trying:
-     * a file with a pathname.
-     * or environment variable
-     * or OS-X Keychain password entry
-     * or you can paste the key interactively with `-i` 
-  4. Input data can be read from a file with `-f file`, or read from STDIN, or a passed on the command line with `-s string`    
-  4. Output is the encrypted data, which is printed to STDOUT by the default, or it can be saved to a file with `-o <file>`
-  5. Encrypted file can be later decrypted with `sym -d [key-spec] [data-spec]`
-
-Sample session that uses Mac OS-X Keychain to store the password-protected key.
+  2. Next, let's assume you have a file or a string that you want to encrypt. We call this *data*.
+  3. In order to encrypt the __data__, we must supply an encryption key. Flag `-k` automatically retrieves the key, by trying to read it in several distinct ways, such as:
+     * a file with a pathname specified by the argument (eg, `-k ~/.key`)
+     * or environment variable (eg `-k ENC_KEY`)
+     * or OS-X Keychain entry
+     * verbatum string argument (not recommended)
+     * alternatively, you can paste the key interactively with `-i` or save the default key in `~/.sym.key` file.
+  4. Finally, we are ready to encrypt. The data to be encrypted can be read from a file with `-f filename`, or it can be read from STDIN, or a passed on the command line with `-s string`. For example, `sym -e -k ~/.key -f /etc/passwd` will encrypt the file and print the encrypted contents to STDOUT.
+  4. Instead of printing to STDOUT, the output can be saved to a file with `-o <file>` or a simple redirect or a pipe.
+  5. Encrypted file can later be decrypted with `sym -d ...` assuming the same key it was encrypted with.
+  6. Encrypted file with extension `.enc` can be automatically decrypted with `-n/--negate` option; if the file does not end with `.enc`, it is encrypted and `.enc` extension added to the resulting file.
+  7. With `-t` flag you can open in VIM (or `$EDITOR`) any encrypted file and edit it. Once you save it, the file gets re-encrypted and replaces the previous version. A backup can be created with `-b` option. See the section on [inline editing](#inline)
+
+A sample session that uses Mac OS-X Keychain to store the password-protected key.
 
 ```bash
 # Gen a new key, password-encrypt it, cache the password, save
@@ -83,7 +116,6 @@ New Password     :  •••••••••
 Confirm Password :  •••••••••
 
 ❯ sym -eck my-new-key -s 'My secret data' -o secret.enc
-Coin::Vault listening at: druby://127.0.0.1:24924
 Password: •••••••••
 
 ❯ cat secret.enc
@@ -104,47 +136,136 @@ My secret data
 My secret data
 ```
 
-The line that says `Coin::Vault listening at: druby://127.0.0.1:24924` is the indication that the local dRB server used for caching passwords has been started. Password caching is off by default, but is enabled with `-c` flag. In the example above, the decryption step fetched the password from the cache, and so the user was not required to re-enter the password.
+Note that password caching is off by default, but is enabled with `-c` flag. In the example above, the decryption step fetched the password from the cache, and so the user was not required to re-enter the password.
 
-__Direct Editing Encrypted Files__
+<a name="inline"></a>
+
+#### Inline Editing of Encrypted Files
 
-Instead of decrypting data anytime you need to change it, you can use the shortcut flag `-t` (for "edi**t**"), which decrypts your data into a temporary file, automatically opening it with an `$EDITOR`. 
+The `sym` CLI tool supports one particularly interesting mode, that streamlines handling of encrypted files. The mode is called __edit mode__, and is activated with the `-t` flag. 
 
-Example:
+Instead of decrypting data anytime you need to change it into a new file and then manually re-encrypting the result, you can use the shortcut flag `-t` (for "edi**t**"), which decrypts your data into a temporary file, automatically opening it with an `$EDITOR`. 
 
     sym -t -f config/application/secrets.yml.enc -k ~/.key
     
 > This is one of those time-saving features that can make a difference in making encryption feel easy and transparent.
 
-For more information see the section on [inline editing](#inline).
+> NOTE: this mode does not seem to work with GUI editors such as Atom or TextMate. Since `sym` waits for the editor process to complete, GUI editors "complete" immediately upon starting a windowed application. 
 
-## Installation
+In this mode several flags are of importance:
 
-If you plan on using the library in your Ruby project with Bundler managing its dependencies, just include the following line in your `Gemfile`:
+    -b (--backup)   – will create a backup of the original file
+    -v (--verbose) - will show additional info about file sizes
 
-    gem 'sym'
+Here is a full command that opens a file specified by `-f | --file`, using the key specified in `-k | --keyfile`, in the editor defined by the `$EDITOR` environment variable (or if not set – defaults to `/bin/vi`)".
 
-And then run `bundle`.
+Example: here we edit an encrypted file in `vim`, while using interactive mode to paste the key (`-i | --interactive`), and then creating a backup file (`-b | --backup`) upon save:
 
-Or install it into the global namespace with `gem install` command:
+    sym -tibf data.enc
+    # => Private Key: ••••••••••••••••••••••••••••••••••••••••••••
+    #
+    # => Diff:
+    # 3c3
+    # # (c) 2015 Konstantin Gredeskoul.  All rights reserved.
+    # ---
+    # # (c) 2016 Konstantin Gredeskoul.  All rights reserved.
 
-    $ gem install sym
-    $ sym -h
-    $ sym -E # see examples
+Note the `diff` shown after save.
 
-__BASH Completion__
+<a name="rubyapi"></a>
 
-Optionally, after gem installation, you can also install bash-completion of gem's command line options, but running the following command (and feel free to use any of the "dot" files you prefer):
+## Ruby API
 
-    sym -B/--bash-support ~/.bashrc
+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`.
 
-Should you choose to install it (this part is optional), you will be able to use "tab-tab" after typing `sym`, and you'll be able to choose from all of the supported flags.
+#### Class Method `#create_private_key()` 
 
-<a name="cli"></a>
+This method will generate a new key each time it's called.
+
+#### Class Method `#private_key(value = nil)` 
+
+This method will either assign an existing key (if a value is passed) or generate and save a new key in the class instance variable. Therefore each class including `Sym` will (by default) use a unique key (unless the key is passed in as an argument).
+
+The following example illustrates this point:
+
+```ruby
+require 'sym'
+
+class TestClass
+  include Sym
+end
+
+@key = TestClass.create_private_key
+@key.eql?(TestClass.private_key)  # => false
+# A new key was created and saved in #private_key accessor.
+
+class SomeClass
+  include Sym
+  private_key TestClass.private_key
+end
+
+@key.eql?(SomeClass.private_key)  # => true (it was assigned)
+```
+
+#### Encrypting and Decrypting Data
+
+So how would we use this library from another Ruby project to encrypt and decrypt values?
+
+After including the `Sym` module, two instance methods are added: 
+
+* `#encr(value, private_key)` and 
+* `#decr(value, private_key)`.
+
+Therefore you could write something like this below, protecting a sensitive string using a class-level secret.
+
+```ruby
+require 'sym'
+class TestClass
+  include Sym
+  private_key ENV['SECRET']
+
+  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
+```
+
+#### Encrypting the Key Itself
 
+You can encrypt the private key using a custom password. This is highly recommended, because without the password the key is the only piece that stands between an attacker and decrypting your sensitive data. 
+
+For this purpose, two more instance methods exist:
+
+ * `encr_password(data, password, iv = nil)`
+ * `decr_password(encrypted_data, password, iv = nil)`
+
+They can be used independently of `encr` and `decr` to encrypt/decrypt any data with a password.
+
+<a name="rubyapi-app"></a>
+
+#### Full Application API
+
+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.
+
+The class is instantiated with a hash that would be otherwise generated by parsing CLI arguments, typical `options`. For example, to generate the key, pass `generate: true` — essentially any flag in it's long form can be converted into a hash member.
+
+Here is an example:
+
+```ruby
+require 'sym/application'
+
+key  = Sym::Application.new(generate: true).execute
+# => '75ngenJpB6zL47/8Wo7Ne6JN1pnOsqNEcIqblItpfg4='
+```
+
+
+<a name="cli"></a>
 ## Using `sym` with the Command Line
 
-### Private Keys
+### Encryption Keys
 
 The private key is the cornerstone of the symmetric encryption. Using `sym`, the key can be:
 
@@ -158,37 +279,69 @@ The __unencrypted private__ key will be in the form of a base64-encoded string,
 
 __Encrypted (with password) private key__ will be considerably longer, perhaps 200-300 characters long.
 
-#### Generating Private Keys
-
-Let's generate a new key, and copy it to the clipboard (using `pbcopy` command on Mac OS-X):
-
-    sym -g | pbcopy
-
-Or save a new key into a bash variable
+#### Generating the Key — Examples
 
-    KEY=$(sym -g)
+```bash
+# Let's generate a new key, and copy it to the clipboard (using `pbcopy` command on Mac OS-X):
+$ sym -g | pbcopy
 
-Or save it to a file:
+# Or save a new key into a bash variable
+$ KEY=$(sym -g)
 
-    sym -go ~/.key
+# Or save it to a file:
+$ sym -go ~/.key
 
-Or create a password-protected key (`-p`), and save it to a file (`-o`), cache the password (`-c`), and don't print the new key to STDOUT (`-q` for quiet):
+# Or create a password-protected key (`-p`), and save it to a file (`-o`), 
+# cache the password (`-c`), and don't print the new key to STDOUT (`-q` for quiet)
+$ sym -gpcqo ~/.secret
+New Password:     ••••••••••
+Confirm Password: ••••••••••
+$ 
+```
 
-    sym -gpcqo ~/.secret
-    New Password:     ••••••••••
-    Confirm Password: ••••••••••
+#### Resolving the `-k` Argument
     
-##### Key Sources
-    
-You can subsequently use the private key by passing either of these options to the `-k` flag (*sym attempts to resolve the key automatically, by trying each option and moving to the next until the key is found*):
+You can use the generated private key by passing an argument to the `-k` flag. 
+
+**Sym** attempts to automatically resolve the key source by trying each of the following options, and then moving on to the next until the key is found, or error is shown:
 
  1. the `-k value` flag, where the *value* is one of:
-    * a file path
-    * an environment variable name 
+    * a file path, eg (`-k ~/.key`)
+    * an environment variable name (`-k MY_KEY`)
     * an actual base64-encoded key (not recommended for security reasons)
-    * a keychain name
+    * a keychain name (`-k keychain-entry-name`)
  2. pasting or typing the key with the `-i` (interactive) flag
- 3. a default key file, in your home folder, `~/.sym.key`, used only when no other flags were passed in.
+ 3. if exists, a default key file, located in your home folder: `~/.sym.key` is used only when no other key-specifying flags were passed in.
+
+#### Encryption and Decryption
+
+<a name="inline"></a>
+
+#### Inline Editing
+
+The `sym` CLI tool supports one particularly interesting mode, that streamlines handling of encrypted files. The mode is called __edit mode__, and is activated with the `-t` flag. 
+
+In this mode `sym` can decrypt the file, and open the result in an `$EDITOR`. Once you make any changes, and save it (exiting the editor), `sym` will automatically diff the new and old content, and if different – will save encrypt it and overwrite the original file.
+
+> NOTE: this mode does not seem to work with GUI editors such as Atom or TextMate. Since `sym` waits for the editor process to complete, GUI editors "complete" immediately upon starting a windowed application. 
+In this mode several flags are of importance:
+
+    -b (--backup)   – will create a backup of the original file
+    -v (--verbose) - will show additional info about file sizes
+
+Here is a full command that opens a file specified by `-f | --file`, using the key specified in `-k | --keyfile`, in the editor defined by the `$EDITOR` environment variable (or if not set – defaults to `/bin/vi`)".
+
+To edit an encrypted file in `$EDITOR`, while asking to paste the key (`-i | --interactive`), while creating a backup file (`-b | --backup`):
+
+    sym -tibf data.enc
+    # => Private Key: ••••••••••••••••••••••••••••••••••••••••••••
+    #
+    # => Diff:
+    # 3c3
+    # # (c) 2015 Konstantin Gredeskoul.  All rights reserved.
+    # ---
+    # # (c) 2016 Konstantin Gredeskoul.  All rights reserved.
+
 
 #### Using KeyChain Access on Mac OS-X
 
@@ -269,228 +422,19 @@ sym -Adf file.enc -o file.original
 sym -Atf file.enc
 ```
 
-#### Complete CLI Usage
-
-This may be a good time to take a look at the full help message for the `sym` tool, shown naturally with a `-h` or `--help` option.
-
-```
-Sym (2.5.1) – encrypt/decrypt data with a private key
-
-Usage:
-   # Generate a new key, optionally password protected, and save it
-   # in one of: keychain, file, or STDOUT (-q turns off STDOUT) 
-   
-        sym -g [ -p/--password ] [ -x keychain | -o file | ] [ -q ]  
-
-   # To specify encryption key, provide the key as 
-   #   1) a string, 2) a file path, 3) an OS-X Keychain, 4) env variable name 
-   #   5) use -i to paste/type the key interactively
-   #   6) default key file (if present) at /Users/kig/.sym.key
-   
-   KEY-SPEC = -k/--key [ key | file | keychain | environment_variable ]
-              -i/--interactive
-
-   # Encrypt/Decrypt from STDIN/file/args, to STDOUT/file:
-   
-        sym -e/--encrypt KEY-SPEC [-f [file | - ] | -s string ] [-o file] 
-        sym -d/--decrypt KEY-SPEC [-f [file | - ] | -s string ] [-o file] 
-
-   # Auto-detect mode based on a special file extension ".enc"
-   
-        sym -n/--negate  KEY-SPEC file[.enc] 
- 
-   # Edit an encrypted file in $EDITOR 
-   
-        sym -t/--edit    KEY-SPEC -f file [ -b/--backup ]
- 
-   # Save commonly used flags in a BASH variable. Below we save the KeyChain 
-   # "staging" as the default key name, and enable password caching.
-   
-        export SYM_ARGS="-ck staging"
-   
-   # Then activate $SYM_ARGS by using -A/--sym-args flag:
-   
-        sym -Aef file
- 
-Modes:
-  -e, --encrypt                     encrypt mode
-  -d, --decrypt                     decrypt mode
-  -t, --edit                        edit encrypted file in an $EDITOR
-  -n, --negate           [file]     encrypts any regular file into file.enc
-                                    conversely decrypts file.enc into file.
- 
-Create a new private key:
-  -g, --generate                    generate a new private key
-  -p, --password                    encrypt the key with a password
-  -x, --keychain         [key-name] write the key to OS-X Keychain
- 
-Read existing private key from:
-  -k, --key              [key-spec] private key, key file, or keychain
-  -i, --interactive                 Paste or type the key interactively
- 
-Password Cache:
-  -c, --cache-passwords             enable password cache
-  -u, --cache-timeout    [seconds]  expire passwords after
-  -r, --cache-provider   [provider] cache provider, one of memcached, drb
- 
-Data to Encrypt/Decrypt:
-  -s, --string           [string]   specify a string to encrypt/decrypt
-  -f, --file             [file]     filename to read from
-  -o, --output           [file]     filename to write to
- 
-Flags:
-  -b, --backup                      create a backup file in the edit mode
-  -v, --verbose                     show additional information
-  -q, --quiet                       do not print to STDOUT
-  -T, --trace                       print a backtrace of any errors
-  -D, --debug                       print debugging information
-  -V, --version                     print library version
-  -N, --no-color                    disable color output
-  -A, --sym-args                    read more CLI arguments from $SYM_ARGS
- 
-Utility:
-  -B, --bash-support     [file]     append bash completion & utils to a file
-                                    such as ~/.bash_profile or ~/.bashrc
- 
-Help & Examples:
-  -E, --examples                    show several examples
-  -h, --help                        show help
-
-```
-
-### CLI Usage Examples
-
-__Generating the Key__:
-
-Generate a new private key into an environment variable:
-
-    export KEY=$(sym -g)
-    echo $KEY
-    # => 75ngenJpB6zL47/8Wo7Ne6JN1pnOsqNEcIqblItpfg4=
-
-Generate a new password-protected key & save to a file:
-
-    sym -gpqo ~/.key
-    New Password     : ••••••••••
-    Confirm Password : ••••••••••
-
-Encrypt a plain text string with a key, and save the output to a file:
-
-    sym -e -s "secret string" -k $KEY -o file.enc
-    cat file.enc
-    # => Y09MNDUyczU1S0UvelgrLzV0RTYxZz09CkBDMEw4Q0R0TmpnTm9md1QwNUNy%T013PT0K
-
-Decrypt a previously encrypted string:
-
-    sym -d -s $(cat file.enc) -k $KEY
-    # => secret string
-
-Encrypt a file and save it to `sym.enc`:
-
-    sym -e -f app-sym.yml -o app-sym.enc -k $KEY
-
-Decrypt an encrypted file and print it to STDOUT:
-
-    sym -df app-sym.enc -k $KEY
-
-<a name="inline"></a>
-
-#### Inline Editing
-
-The `sym` CLI tool supports one particularly interesting mode, that streamlines handling of encrypted files. The mode is called __edit mode__, and is activated with the `-t` flag. 
-
-In this mode `sym` can decrypt the file, and open the result in an `$EDITOR`. Once you make any changes, and save it (exiting the editor), `sym` will automatically diff the new and old content, and if different – will save encrypt it and overwrite the original file.
-
-> NOTE: this mode does not seem to work with GUI editors such as Atom or TextMate. Since `sym` waits for the editor process to complete, GUI editors "complete" immediately upon starting a windowed application. 
-In this mode several flags are of importance:
-
-    -b (--backup)   – will create a backup of the original file
-    -v (--verbose) - will show additional info about file sizes
-
-Here is a full command that opens a file specified by `-f | --file`, using the key specified in `-k | --keyfile`, in the editor defined by the `$EDITOR` environment variable (or if not set – defaults to `/bin/vi`)".
-
-To edit an encrypted file in `$EDITOR`, while asking to paste the key (`-i | --interactive`), while creating a backup file (`-b | --backup`):
-
-    sym -tibf data.enc
-    # => Private Key: ••••••••••••••••••••••••••••••••••••••••••••
-    #
-    # => Diff:
-    # 3c3
-    # # (c) 2015 Konstantin Gredeskoul.  All rights reserved.
-    # ---
-    # # (c) 2016 Konstantin Gredeskoul.  All rights reserved.
-
-<a name="rubyapi"></a>
-
-## Ruby API
-
-To use this library, you must include the main `Sym` module into your library.
-
-Any class including `Sym` will be decorated with new class methods `#private_key` and `#create_private_key`, as well as instance methods `#encr`, and `#decr`.
-
-`#create_private_key` will generate a new key each time it's called, while `#private_key` will either assign an existing key (if a value is passed) or generate and save a new key in the class instance variable. Therefore each class including `Sym` will use its key (unless the key is assigned).
-
-The following example illustrates this point:
-
-```ruby
-require 'sym'
-
-class TestClass
-  include Sym
-end
-@key = TestClass.create_private_key
-@key.eql?(TestClass.private_key)  # => false
-# A new key was created and saved in #private_key accessor.
-
-class SomeClass
-  include Sym
-  private_key TestClass.private_key
-end
-
-@key.eql?(SomeClass.private_key)  # => true (it was assigned)
-```
-
-### Encryption and Decryption Operations
+#### CLI Help Screen and Examples
 
-So how would we use this library from another Ruby project to encrypt and decrypt values?
+This may be a good time to take a look at the full help message for the `sym` tool, shown naturally with a `-h` or `--help` option. Examples can be shown with `-E/--examples` flag.
 
-After including the `Sym` module in a ruby class, the class will now have the `#encr` and `#decr` instance methods, as well as `#secret` and `#create_private_key class methods.
+Please take a look at the [SYM-CLI](SYM-CLI.md) for a complete help screen and the examples.
 
-Therefore you could write something like this below, protecting a sensitive string using a class-level secret.
+## Fine Tuning
 
-```ruby
-require 'sym'
-class TestClass
-  include Sym
-  private_key ENV['SECRET']
-
-  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
-```
-
-### Full Application API
-
-Since the command line interface offers more than just encryption/decryption, it is available via `Sym::Application` class.
-
-The class is instantiated with a hash that would be otherwise generated by `Slop.parse(argv)` – ie, typical `options`.
-
-Here is an example:
-
-```ruby
-require 'sym/application'
-
-key  = Sym::Application.new(generate: true).execute
-# => returns a new private key
-```
+<a name="rubyapi-config"></a>
 
 ### Configuration
 
-The library offers a typical `Sym::Configuration` class which can be used to tweak some of the internals of the gem. Its meant for an advanced user who knows what he or she is doing. The code snippet shown below is an actual part of the Configuration class, but you can override it by including it in your code that uses and initializes this library, right after the `require.` The `Configuration` class is a Singleton, so changes to it will propagate to any subsequent calls to the gem.
+The library contains a `Sym::Configuration` singleton class, which can be used to tweak some of the internals of the gem. Its meant for advanced users who know what they are doing. The code snippet shown below is an actual default configuration. You can override the defaults by including a similar snipped in your application initialization, right after the `require 'sym'`. The `Configuration` class is a Singleton, so changes to it will propagate to any subsequent calls to the gem.
 
 ```ruby
 require 'zlib'
@@ -509,18 +453,19 @@ Sym::Configuration.configure do |config|
   # When nil is selected, providers are auto-detected.
   config.password_cache_default_provider = nil
   config.password_cache_arguments        = {
+    # Ruby dRB-based in-memory cache.
     drb:       {
       opts: {
         uri: 'druby://127.0.0.1:24924'
       }
     },
+    # Memcached Provider – local is the default, but can be changed.
     memcached: {
       args: %w(127.0.0.1:11211),
       opts: { namespace:  'sym',
               compress:   true,
               expires_in: config.password_cache_timeout
       }
-
     }
   }
 end
@@ -529,7 +474,8 @@ end
 
 As you can see, it's possible to change the default cipher type, although not all ciphers will be code-compatible with the current algorithm, and may require additional code changes.
 
-## Encryption Features & Cipher Used
+
+#### Encryption Features & Cipher
 
 The `sym` executable as well as the Ruby API provide:
 
@@ -555,11 +501,11 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-### Contributing
+#### Contributing
 
-Bug reports and pull requests are welcome on GitHub at [https://github.com/kigster/sym](https://github.com/kigster/sym).
+Bug reports and pull requests are welcome on GitHub at [https://github.com/kigster/sym](https://github.com/kigster/sym)
 
-## License
+### License
 
 `Sym` library is &copy; 2016-2017 Konstantin Gredeskoul.
 
@@ -567,13 +513,13 @@ The gem is available as open source under the terms of the [MIT License](http://
 
 The library is designed to be a layer on top of [`OpenSSL`](https://www.openssl.org/), distributed under the [Apache Style license](https://www.openssl.org/source/license.txt).
 
-## Acknowledgements
+### Acknowledgements
 
-[Konstantin Gredeskoul](http:/kig.re) is the primary developer of this library. Contributions from others are strongly encouraged and very welcome. Any pull requests will be reviewed promptly.
+While [Konstantin Gredeskoul](http:/kig.re) is the primary developer of this library, contributions  are very much encouraged. Any pull requests will be reviewed promptly. Please submit feature requests, bugs, or a good word :) 
 
-Contributors:
+#### Contributors:
 
- * Wissam Jarjoui (Shippo)
+ * [Wissam Jarjoui](https://github.com/bosswissam)
  * Megan Mathews 
  * Barry Anderson
 

data/SYM-CLI.md

@@ -0,0 +1,143 @@
+# Sym CLI Help Screen
+
+```text
+Sym (2.5.1) – encrypt/decrypt data with a private key
+
+Usage:
+   Generate a new key, optionally password protected, and save it
+   in one of: keychain, file, or STDOUT (-q turns off STDOUT) 
+ 
+       sym -g [ -p/--password ] [-c] [-x keychain | -o file | ] [-q]
+
+   To specify encryption key, provide the key as 
+      1) a string, 2) a file path, 3) an OS-X Keychain, 4) env variable name 
+      5) use -i to paste/type the key interactively
+      6) default key file (if present) at /Users/kig/.sym.key
+ 
+       KEY-SPEC = -k/--key [ key | file | keychain | env variable name ]
+                  -i/--interactive
+
+   Encrypt/Decrypt from STDIN/file/args, to STDOUT/file:
+ 
+       sym -e/--encrypt KEY-SPEC [-f [file | - ] | -s string ] [-o file] 
+       sym -d/--decrypt KEY-SPEC [-f [file | - ] | -s string ] [-o file] 
+
+   Auto-detect mode based on a special file extension ".enc"
+ 
+       sym -n/--negate  KEY-SPEC file[.enc] 
+ 
+   Edit an encrypted file in $EDITOR 
+ 
+       sym -t/--edit    KEY-SPEC -f file [ -b/--backup ]
+ 
+   Save commonly used flags in a BASH variable. Below we save the KeyChain 
+   "staging" as the default key name, and enable password caching.
+ 
+       export SYM_ARGS="-ck staging"
+ 
+   Then activate $SYM_ARGS by using -A/--sym-args flag:
+ 
+       sym -Aef file
+ 
+Modes:
+  -e, --encrypt                     encrypt mode
+  -d, --decrypt                     decrypt mode
+  -t, --edit                        edit encrypted file in an $EDITOR
+  -n, --negate           [file]     encrypts any regular file into file.enc
+                                    conversely decrypts file.enc into file.
+ 
+Create a new private key:
+  -g, --generate                    generate a new private key
+  -p, --password                    encrypt the key with a password
+  -x, --keychain         [key-name] write the key to OS-X Keychain
+ 
+Read existing private key from:
+  -k, --key              [key-spec] private key, key file, or keychain
+  -i, --interactive                 Paste or type the key interactively
+ 
+Password Cache:
+  -c, --cache-passwords             enable password cache
+  -u, --cache-timeout    [seconds]  expire passwords after
+  -r, --cache-provider   [provider] cache provider, one of memcached, drb
+ 
+Data to Encrypt/Decrypt:
+  -s, --string           [string]   specify a string to encrypt/decrypt
+  -f, --file             [file]     filename to read from
+  -o, --output           [file]     filename to write to
+ 
+Flags:
+  -b, --backup                      create a backup file in the edit mode
+  -v, --verbose                     show additional information
+  -q, --quiet                       do not print to STDOUT
+  -T, --trace                       print a backtrace of any errors
+  -D, --debug                       print debugging information
+  -V, --version                     print library version
+  -N, --no-color                    disable color output
+  -A, --sym-args                    read more CLI arguments from $SYM_ARGS
+ 
+Utility:
+  -B, --bash-support     [file]     append bash completion & utils to a file
+                                    such as ~/.bash_profile or ~/.bashrc
+ 
+Help & Examples:
+  -E, --examples                    show several examples
+  -h, --help                        show help
+```
+
+## Examples
+
+```bash
+# generate a new private key into an environment variable:
+export mykey=$(sym -g)
+echo $mykey
+75ngenJpB6zL47/8Wo7Ne6JN1pnOsqNEcIqblItpfg4=
+————————————————————————————————————————————————————————————————————————————————
+# generate a new key with a cached password & save to the default key file
+sym -gcpqo /Users/kig/.sym.key
+New Password     : ••••••••••
+Confirm Password : ••••••••••
+————————————————————————————————————————————————————————————————————————————————
+# encrypt a plain text string with default key file, and immediately decrypt it
+sym -es "secret string" | sym -d
+secret string
+————————————————————————————————————————————————————————————————————————————————
+# encrypt secrets file using key in the environment, and --negate option:
+export PRIVATE_KEY="75ngenJpB6zL47/8Wo7Ne6JN1pnOsqNEcIqblItpfg4="
+sym -ck PRIVATE_KEY -n secrets.yml
+
+————————————————————————————————————————————————————————————————————————————————
+# encrypt a secrets file using the key in the keychain:
+sym -gqx keychain.key
+sym -ck keychain.key -n secrets.yml
+secret string
+————————————————————————————————————————————————————————————————————————————————
+# encrypt/decrypt sym.yml using the default key file
+sym -gcq > /Users/kig/.sym.key
+sym -n secrets.yml
+sym -df secrets.yml.enc
+————————————————————————————————————————————————————————————————————————————————
+# decrypt an encrypted file and print it to STDOUT:
+sym -ck production.key -df secrets.yml.enc
+————————————————————————————————————————————————————————————————————————————————
+# edit an encrypted file in $EDITOR, use default key file, create file backup
+sym -tbf secrets.enc
+
+Private Key: ••••••••••••••••••••••••••••••••••••••••••••
+Saved encrypted content to sym.enc.
+
+Diff:
+3c3
+# (c) 2015 Konstantin Gredeskoul.  All rights reserved.
+---
+# (c) 2016 Konstantin Gredeskoul.  All rights reserved.
+————————————————————————————————————————————————————————————————————————————————
+# generate a new password-encrypted key, save it to your Keychain:
+sym -gpcx staging.key
+————————————————————————————————————————————————————————————————————————————————
+# use the new key to encrypt a file:
+sym -e -c -k staging.key -n etc/passwords.enc
+————————————————————————————————————————————————————————————————————————————————
+# use the new key to inline-edit the encrypted file:
+sym -k mykey -tf sym.yml.enc
+————————————————————————————————————————————————————————————————————————————————
+```

data/bin/sym.symit

@@ -110,12 +110,24 @@ symit::locs() {
   echo -n ${locations[*]}
 }
 
+symit::locs::print() {
+  printf "Search locations:\n"
+  for loc in ${locations[@]}; do
+    if [[ -n "${loc}" ]] ; then
+      printf "\t - ${bldblu}${loc}${txtrst}\n"
+    fi
+  done
+}
+
 symit::exit() {
   code=${1:-0}
+  echo -n ${code}
+}
+
+symit::cleanup() {
   unset encrypted_file
   unset cli__opts
   unset locations
-  echo -n ${code}
 }
 
 symit() {
@@ -140,6 +152,7 @@ symit() {
       -h|-\?|--help)
           shift
           symit::usage
+          symit::cleanup
           return $(symit::exit 0)
           ;;
 
@@ -171,6 +184,7 @@ symit() {
       -i|--install)
           shift
           symit::install
+          symit::cleanup
           return $(symit::exit 0)
           ;;
 
@@ -186,6 +200,7 @@ symit() {
 
       -?*)
           printf 'WARN: Unknown option (ignored): %s\n' "$1" >&2
+          symit::cleanup
           return $(symit::exit 127)
           shift
           ;;
@@ -201,24 +216,24 @@ symit() {
   if [[ ${cli__opts[locations]} == ${true} ]]; then
     if [[ -z ${encrypted_file} ]]; then
       symit::error "-l/--locations requires file-spec to be provided as the 1st argument"
+      symit::cleanup
       return $(symit::exit 2)
+    else
+      symit::locs::print
+      symit::cleanup
+      return $(symit::exit 0)
     fi
-    printf "search locations:\n"
-    for loc in ${locations[@]}; do
-      if [[ -n "${loc}" ]] ; then
-        printf "\t - ${loc}\n"
-      fi
-    done
-    return $(symit::exit 0)
   fi
 
   if [[ -z "${encrypted_file}" ]]; then
     symit::error "Missing 1st argument — file name to be loaded, eg 'production', etc."
+    symit::cleanup
     return $(symit::exit 3)
   fi
 
   if [[ -z "${cli__opts[key]}" ]]; then
     symit::error "Key was not defined, pass it with ${bldblu}-k key-spec${bldred} or set it via ${bldgrn}\$sym__key${bldred} variable."
+    symit::cleanup
     return $(symit::exit 4)
   fi
 
@@ -231,7 +246,9 @@ symit() {
   done
 
   [[ -z "${file}" ]] && {
-    symit::error "${encrypted_file} could not be found."
+    symit::error "${bldylw}${encrypted_file}${bldred} could not be found."
+    symit::locs::print
+    symit::cleanup
     return $(symit::exit 5)
   }
 

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

@@ -5,7 +5,10 @@ module Sym
       class Stdout < ::Sym::App::Output::Base
         required_option nil
         def output_proc
-          ->(argument) { printf "%s", argument }
+          ->(argument) do
+            printf '%s', argument
+            printf "\n" if STDOUT.tty?
+          end
         end
       end
     end

data/lib/sym/version.rb

@@ -1,15 +1,28 @@
 module Sym
-  VERSION = '2.5.1'
+  VERSION = '2.5.3'
   DESCRIPTION = <<-eof
-    Sym is a command line utility and a Ruby API that makes it trivial to encrypt and decrypt 
-    sensitive data. Unlike many other existing encryption tools, sym focuses on usability and 
-    streamlined interface (CLI), with the goal of making encryption easy and transparent. 
-    The result? There is no excuse for keeping your application secrets unencrypted :)
-
-    You can password-protect the key for an additional layer of security, and store the key in the  
-    OS-X keychain. Use the key to reliably encrypt, decrypt and re-encrypt your application 
-    secrets. Use the -t CLI switch to transparently edit an encrypted file in an editor of your choice.
+    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
+    encryption with a 256bit key.
+ 
+    Unlike many modern encryption tools, sym focuses on the streamlined interface (CLI),
+    and offers many time-saving features that make encryption/decryption of application
+    secrets and other sensitive data as seamless as possible.   
  
-    Sym uses a symmetric aes-256-cbc cipher with a private key and an IV vector.
+    You can encrypt the key itself with a password, for an additional layer of security.
+    You can choose to save the key to OS-X Keychain, making it difficult to get the key
+    when only disk is accessible. Using memcached or DRb sym can cache passwords so that
+    you don't have to retype it too often. Finally, the -t flag (edit mode) decrypts
+    the file on the fly, and lets you edit the unencrypted contents in $EDITOR. 
+
+    Sym can read the key from many sources, including file, environment variable, 
+    keychain, or CLI argument — all of the above become arguments of -k flag: one 
+    flag to define the key no matter where it lives.
+
+    Finally, set environment variable SYM_ARGS to common flags you use, and then
+    have sym read these flags, activating this time-saving feature with -A flag.     
+     
+    Sym uses a symmetric aes-256-cbc cipher with a private key and an IV vector, 
+    and is built atop of OpenSSL.
   eof
 end

data/sym.gemspec

@@ -21,17 +21,16 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
   spec.required_ruby_version = '>= 2.2'
   spec.post_install_message = <<-EOF
-Thank you for installing this gem! 
+Thank you for installing this gem! We hope you like it :)  
 
-To enable bash command line completion, please run the following 
-command, which appends sym's shell completion to the specified file:
-
-  sym --bash-completion ~/.bash_profile 
-
-(or any other shell initialization file of your preference).
+NOTE: To enable bash command line completion, please run the following 
+command, which appends sym's shell completion to the file specified
+in arguments to -B/--bash-support flag.
 
+  sym -B ~/.bash_profile
+ 
 Thank you for checking out Sym and happy crypting :)
-   -- KG ( github.com/kigster | twitter.com/kig )
+              -- KG ( github.com/kigster | twitter.com/kig )
 EOF
   spec.add_dependency 'colored2', '~> 3'
   spec.add_dependency 'slop', '~> 4.3'
@@ -48,4 +47,4 @@ EOF
   spec.add_development_dependency 'rspec', '~> 3'
   spec.add_development_dependency 'rspec-its'
   spec.add_development_dependency 'yard'
-end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sym
 version: !ruby/object:Gem::Version
-  version: 2.5.1
+  version: 2.5.3
 platform: ruby
 authors:
 - Konstantin Gredeskoul
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-03-07 00:00:00.000000000 Z
+date: 2017-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colored2
@@ -206,16 +206,23 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: "    Sym is a command line utility and a Ruby API that makes it trivial
-  to encrypt and decrypt \n    sensitive data. Unlike many other existing encryption
-  tools, sym focuses on usability and \n    streamlined interface (CLI), with the
-  goal of making encryption easy and transparent. \n    The result? There is no excuse
-  for keeping your application secrets unencrypted :)\n\n    You can password-protect
-  the key for an additional layer of security, and store the key in the  \n    OS-X
-  keychain. Use the key to reliably encrypt, decrypt and re-encrypt your application
-  \n    secrets. Use the -t CLI switch to transparently edit an encrypted file in
-  an editor of your choice.\n \n    Sym uses a symmetric aes-256-cbc cipher with a
-  private key and an IV vector.\n"
+description: "    Sym is a command line utility plus a straightforward Ruby API that
+  makes it easy to \n    transparently handle sensitive data such as application secrets
+  using symmetric\n    encryption with a 256bit key.\n \n    Unlike many modern encryption
+  tools, sym focuses on the streamlined interface (CLI),\n    and offers many time-saving
+  features that make encryption/decryption of application\n    secrets and other sensitive
+  data as seamless as possible.   \n \n    You can encrypt the key itself with a password,
+  for an additional layer of security.\n    You can choose to save the key to OS-X
+  Keychain, making it difficult to get the key\n    when only disk is accessible.
+  Using memcached or DRb sym can cache passwords so that\n    you don't have to retype
+  it too often. Finally, the -t flag (edit mode) decrypts\n    the file on the fly,
+  and lets you edit the unencrypted contents in $EDITOR. \n\n    Sym can read the
+  key from many sources, including file, environment variable, \n    keychain, or
+  CLI argument — all of the above become arguments of -k flag: one \n    flag to define
+  the key no matter where it lives.\n\n    Finally, set environment variable SYM_ARGS
+  to common flags you use, and then\n    have sym read these flags, activating this
+  time-saving feature with -A flag.     \n     \n    Sym uses a symmetric aes-256-cbc
+  cipher with a private key and an IV vector, \n    and is built atop of OpenSSL.\n"
 email:
 - kigster@gmail.com
 executables:
@@ -236,6 +243,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- SYM-CLI.md
 - bin/console
 - bin/setup
 - bin/sym.completion
@@ -297,11 +305,11 @@ files:
 homepage: https://github.com/kigster/sym
 licenses: []
 metadata: {}
-post_install_message: "Thank you for installing this gem! \n\nTo enable bash command
-  line completion, please run the following \ncommand, which appends sym's shell completion
-  to the specified file:\n\n  sym --bash-completion ~/.bash_profile \n\n(or any other
-  shell initialization file of your preference).\n\nThank you for checking out Sym
-  and happy crypting :)\n   -- KG ( github.com/kigster | twitter.com/kig )\n"
+post_install_message: "Thank you for installing this gem! We hope you like it :)  \n\nNOTE:
+  To enable bash command line completion, please run the following \ncommand, which
+  appends sym's shell completion to the file specified\nin arguments to -B/--bash-support
+  flag.\n\n  sym -B ~/.bash_profile\n \nThank you for checking out Sym and happy crypting
+  :)\n              -- KG ( github.com/kigster | twitter.com/kig )\n"
 rdoc_options: []
 require_paths:
 - lib