README.md in sym-2.6.3 vs README.md in sym-2.7.0
- old
+ new
@@ -1,75 +1,90 @@
-# Sym — Light Weight Symmetric Encryption for Humans
+# Sym — Light-weight Symmetric Encryption for Humans
-<hr/>
-[](https://gitter.im/kigster/sym)
[](https://badge.fury.io/rb/sym)
[](https://rubygems.org/gems/sym)
-[](http://inch-ci.org/github/kigster/sym)
[](https://travis-ci.org/kigster/sym)
[](https://codeclimate.com/github/kigster/sym)
[](https://codeclimate.com/github/kigster/sym/coverage)
[](https://codeclimate.com/github/kigster/sym)
-<hr/>
+[](https://gitter.im/kigster/sym)
-**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!
+---
+**March 10th, 2017**. Please checkout the post "**[Dead Simple Encryption with Sym](http://kig.re/2017/03/10/dead-simple-encryption-with-sym.html)**" that announces this library, and provides further in-depth discussion.
+
+[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=FSFYYNEQ8RKWU)
+
+Your donation of absolutely any amount is very much appreciated.
+
+---
+
## Description
<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 />
+<p><strong>sym</strong> is an open source command line utility and Ruby API which makes it very <em>easy to add reliable encryption and decryption</em> of sensitive data to an application or a project written in any language.</p>
-<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.
+<p>Unlike many existing encryption tools, <strong>sym</strong> focuses on narrowing the gap between convenience and security, by offering enhanced usability and a streamlined ruby API and a CLI. The primary goal of the library is to make encryption very easy and transparent. </p>
+<p><strong>sym</strong> uses the <em><a href="https://en.wikipedia.org/wiki/Symmetric-key_algorithm">Symmetric Encryption</a></em> algorithm. This means that the same key is used to encrypt and decrypt data. In addition to the key, the encryption uses a randomized IV vector, which is automatically generated per each encryption and serialized with the data. Result of encryption is zlib-compressed, and base64 encoded, to be suitable for storage as string. The generated keys are also base64-encoded for convenience.</p>
+
+<p>Finally, the library offers encryption using any regular password, and in particular supports password-protected encryption keys. The key can be specified by a filename, environment variable, or OS-X Keychain password entry name, or as is.</p>
+
</div>
## Supported Ruby Versions
-Sym currently builds and runs on the following ruby versions, which can be verified on Travis CI:
[](https://travis-ci.org/kigster/sym)
+Sym currently builds and runs on the following ruby versions:
+
* 2.2.5
* 2.3.3
- * 2.4.0
+ * 2.4.1
* jruby-9.1.7.0
### Motivation
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:
- * __Encrypting/decrypting of application secrets__, so that the encrypted secrets can be safely checked into the git repository and distributed, and yet without much of the added headache that this often requires
+ * __Encrypting/decrypting of application secrets files__, so that the encrypted secrets can be safely checked into the git repository and distributed, and yet without much of the added headache that this often requires
* __Secure message transfer between any number of receipients__
- * __General purpose encryption/decryption with a single encryption key__, optionally itself re-encrypted with a password.
+ * __General purpose encryption/decryption with a 256-bit encryption key__, optionally itself re-encrypted with a password.
+ * __General purpose encryption/decryption with an arbitrary password__.
__Sym__ is a layer built on top of the [`OpenSSL`](https://www.openssl.org/) library, and, hopefully, makes encryption more accessible to every-day developers, QA, and dev-ops folks, engaged in deploying applications.
### What's Included
This gem includes two primary components:
- 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.
+ 1. **[Rich command line interface CLI](#cli)** with many features to streamline encryption/decryption, and to be integrated into the deployment flow.<br /><br />
+ 2. Ruby APIs:
+ * **[Key Generation, Encryption & Decryption API](#rubyapi)**
+ - is activated by including `Sym` module in a class, it adds easy to use `encr`/`decr` methods.
+ * **[Application API to shadow the CLI usage](#rubyapi-app)**
+ - You can instantiate `Sym::Application` class with a hash representing CLI arguments, and then call it's `#execute` method to mimic CLI execution.
+ * **[Sym::MagicFile API](#magic-file)**
+ - This is a convenience class allowing you to encrypt/decrypt files in your ruby code with just couple of lines of code.
+ * **[Sym::Configuration](#rubyapi-config)**
+ - Use this class to override the default cipher, and configure other parameters such as compression, password caching, and more.
### Massive Time Savers
-What are the time savers that we mentioned earlier?
+**Sym** tries very hard to get out of your way, to make it *feel* as if your encrypted files are as easy to work with as the unencrypted files. It accomplishes this transparency with the following features:
- * 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.
- * By using `SYM_ARGS` environment variable, where common flags can be saved.
+ * 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.
+ * By using **`SYM_ARGS` environment variable** you can save common flags and they will be applied whenever `-A` flag is activated.
* By reading a key from the default key source file `~/.sym.key` which requires no flags at all.
- * By utilizing the `--negate` option to quickly encrypt a regular file, or decrypt an encrypted file with extension `.enc`.
- * By using the `-t` (edit) mode, that opens an encrypted file in your `$EDITOR`, and replaces the encrypted version upon save & exit.
+ * By utilizing the **`--negate` option to quickly encrypt a regular file**, or decrypt an encrypted file with extension `.enc`.
+ * By using the **`-t file` (edit) mode**, that opens an encrypted file in your `$EDITOR`, and replaces the encrypted version upon save & exit.
As you can see, we really tried to build a tool that provides good security for application secrets, including password-based encryption, but does not annoyingly ask for password every time. With `--edit` option, and `--negate` options you can treat encrypted files like regular files.
> Encrypting application secrets had never been easier! –– Socrates [LOL, -ed.]
@@ -114,12 +129,12 @@
* 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)
+ 6. Encrypted file with extension `.enc` can be automatically decrypted with `-n/--negate file` option; if the file does not end with `.enc`, it is encrypted and `.enc` extension added to the resulting file.
+ 7. With `-t/--edit file` flag you can edit an encrypted file 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
@@ -157,11 +172,11 @@
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.
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
+ sym -t 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.
> 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.
@@ -172,11 +187,11 @@
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`)".
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:
- sym -tibf data.enc
+ sym -ibt data.enc
# => Private Key: ••••••••••••••••••••••••••••••••••••••••••••
#
# => Diff:
# 3c3
# # (c) 2015 Konstantin Gredeskoul. All rights reserved.
@@ -381,21 +396,21 @@
<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.
+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 file` 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.
+In this mode `sym` will automaticaly decrypt the encrypted file into a temporary file, and then open it in `$EDITOR`. Once you quit the editor, `sym` will automatically diff the new and old content, and if it is different, `sym` will re-encrypt the new contents and overwrite the original file. You can create an optional backup by adding `-b` flag.
> 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`)".
+Here is a full command that opens a file specified by `-t | --edit 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: ••••••••••••••••••••••••••••••••••••••••••••
@@ -569,23 +584,31 @@
Bug reports and pull requests are welcome on GitHub at [https://github.com/kigster/sym](https://github.com/kigster/sym)
### License
-`Sym` library is © 2016-2017 Konstantin Gredeskoul.
+**Sym** library is © 2016-2017 Konstantin Gredeskoul.
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT). 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).
-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
-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 :)
+ * The blog post [(Symmetric) Encryption With Ruby (and Rails)](http://stuff-things.net/2015/02/12/symmetric-encryption-with-ruby-and-rails/) provided the inspiration for this gem.
+ * We'd like to thank [Spike Ilacqua](http://stuff-things.net/spike/), the author of the [strongbox](https://github.com/spikex/strongbox) gem, for providing very easy-to-read code examples of symmetric encryption.
+ * We'd like to thank [Wissam Jarjoui](https://github.com/bosswissam) for support and inspiration, as well as testing of the early versions of this gem.
+
#### Contributors:
- * [Wissam Jarjoui](https://github.com/bosswissam)
- * Megan Mathews
- * Barry Anderson
+Contributions of any kind are very much welcome from anyone.
+
+Any pull requests will be reviewed promptly.
+
+Please submit feature requests, bugs, or donations :)
+
+ * [Konstantin Gredeskoul](http:/kig.re) (primary developer)
+ * [Wissam Jarjoui](https://github.com/bosswissam) (testing, inspiration)
+ * [Megan Mathews](https://github.com/meganmmathews) (UX, CLI suggestions)
+ * [Barry Anderson](https://twitter.com/z3ndrag0n) (sanity checking, review)