README.md in sym-2.0.2 vs README.md in sym-2.0.3

- old
+ new

@@ -1,9 +1,7 @@ +# Sym — Light Weight Symmetric Encryption for Humans - -# Sym — Your Encryption Best Friend - [![Gem Version](https://badge.fury.io/rb/sym.svg)](https://badge.fury.io/rb/sym) [![Downloads](http://ruby-gem-downloads-badge.herokuapp.com/sym?type=total)](https://rubygems.org/gems/sym) [![Documentation](http://inch-ci.org/github/kigster/sym.png)](http://inch-ci.org/github/kigster/sym) [![Build Status](https://travis-ci.org/kigster/sym.svg?branch=master)](https://travis-ci.org/kigster/sym) @@ -13,11 +11,11 @@ ## Description ### Summary -> __sym__ is little program that makes it _trivial to encrypt and decrypt sensitive data_. But, unlike many other existing tools, __sym__'s goal is to dramatically simplify the command line interface (CLI), and make symmetric encryption as routine as listing directories in Terminal. +> __sym__ is a utility and an API that makes it _trivial to encrypt and decrypt sensitive data_. Unlike many other existing tools, __sym__'s goal is to dramatically simplify the command line interface (CLI), and make symmetric encryption as routine as listing directories in Terminal. With this tool I wanted to make it easy to memorize the most common options, so that there is little no longer a barrier to the full power of encryption offered by [`OpenSSL`](https://www.openssl.org/) library. And no tool works in isolation: this is just a stepping stone that could be part of your deployment or infrastructure code: don't rely on external services: minimize the risk of a "man-in-the-middle" attack, by dealing with the encryption and decryption locally. Ideal application of this gem, is the ability to store sensitive application _secrets_ protected on a file system, or in a repo, and use `sym` to automaticaly decrypt the data when any changes are to be made, or when the data needs to be read by an application service. @@ -71,23 +69,27 @@ $ sym -h $ sym -E # see examples ### BASH Completion (Optional Step) -After gem installation, an message will tell you to install a shown BASH script to your `~/.bashrc` or equivalent. +After gem installation, an message will tell you to install bash completion into to your `~/.bashrc` or equivalent: +```bash +sym --bash-completion ~/.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 supported flags. ## Usage ### Private Keys This library relies on the existance of the 32-byte private key (aka, *a secret*) to perform encryption and decryption. The key can be easily: - * generated by this gem and displayed, copied to the clipboard, or saved to the KeyChain + * generated by this gem and displayed, or saved to Mac OS-X KeyChain * one way or another must be kept very well protected and secure from attackers * can be fetched from the the Keychain in subsequent encryption/decryption steps * password-protected, which you can enable during the generation with the `-p` flag. * NOTE: right now there is no way to add a password to an existing key, only generate a new one. @@ -101,13 +103,13 @@ You can generate using the command line, or in a programmatic way. First we'll discuss the command line usage, and in a later section we'll discuss Ruby API provided by the gem. #### Generating and Using Private Keys -Once the gem is installed you will be able to run an executable `sym`. Now let's generate and copy the new private key to the clipboard. Clipboard copy is activated with the -c flag: +Once the gem is installed you will be able to run an executable `sym`. Now let's generate and copy the new private key to the clipboard (using `pbcopy` command on Mac OS-X): - sym -gc + sym -g | pbcopy Or save a new key into a bash variable SECRET=$(sym -g) @@ -159,58 +161,57 @@ #### Encryption and Decryption 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 (1.7.0) – encrypt/decrypt data with a private key +Sym (2.0.2) – encrypt/decrypt data with a private key Usage: # Generate a new key: - sym -g [ -c ] [ -p ] [ -x keychain ] [ -o keyfile | -q | ] + sym -g [ -c ] [ -p ] [ -x keychain ] [ -o keyfile | -q | ] # Encrypt/Decrypt - sym [ -d | -e ] [ -f <file> | -s <string> ] + sym [ -d | -e ] [ -f <file> | -s <string> ] [ -k key | -K keyfile | -x keychain | -i ] [ -o <output file> ] # Edit an encrypted file in $EDITOR - sym -t -f <file> [ -b ][ -k key | -K keyfile | -x keychain | -i ] + sym -t -f <file> [ -b ][ -k key | -K keyfile | -x keychain | -i ] Modes: -e, --encrypt encrypt mode -d, --decrypt decrypt mode -t, --edit decrypt, open an encr. file in an $EDITOR -Create a private key: +Create a new private key: -g, --generate generate a new private key -p, --password encrypt the key with a password - -c, --copy copy the new key to the clipboard -x, --keychain [key-name] add to (or read from) the OS-X Keychain - -Password Caching: -M, --password-timeout [timeout] when passwords expire (in seconds) - -P, --no-password-cache disables key password caching + -P, --no-password-cache disables caching of key passwords -Provide a private key: +Read existing private key from: -i, --interactive Paste or type the key interactively -k, --private-key [key] private key as a string -K, --keyfile [key-file] private key from a file -Data: +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: - --keychain-del [key-name] delete keychain entry with that name -b, --backup create a backup file in the edit mode -v, --verbose show additional information -T, --trace print a backtrace of any errors -q, --quiet silence all output -V, --version print library version -N, --no-color disable color output +Utility: + -a, --bash-completion [file] append shell completion to a file + Help & Examples: -E, --examples show several examples -L, --language natural language examples -h, --help show help ``` @@ -223,13 +224,13 @@ export KEY=$(sym -g) echo $KEY # => 75ngenJpB6zL47/8Wo7Ne6JN1pnOsqNEcIqblItpfg4= -Generate a new password-protected key, copy to the clipboard & save to a file: +Generate a new password-protected key & save to a file: - sym -gpc -o ~/.key + sym -gp -o ~/.key New Password : •••••••••• Confirm Password : •••••••••• Encrypt a plain text string with a key, and save the output to a file: @@ -272,85 +273,10 @@ # 3c3 # # (c) 2015 Konstantin Gredeskoul. All rights reserved. # --- # # (c) 2016 Konstantin Gredeskoul. All rights reserved. - -### Natural Language Processing - -When sym is invoked, and the first argument does not begin with a dash, -then the the NLP (natural language processing) Translator is invoked. -The Translator is based on a very simple algorithm: - - * ignore any of the words tagged STRIPPED. These are the ambiguous words, or words with duplicate meaning. - * map the remaining arguments to regular double-dashed options using the DICTIONARY - * words that are a direct match for a --option are automatically double-dashed - * remaining words are left as is (these would be file names, key names, etc). - * finally, the resulting "new" command line is parsed with regular options. - * When arguments include "verbose", NLP system will print "before" and "after" - of the arguments, so that any issues can be debugged and corrected. - -#### CURRENTLY IGNORED WORDS: - - and, a, the, it, item, to, key, with, about, for, of, new, make, store, in, print - -#### REGULAR WORD MAPPING - -``` -________________________________________________________________________ - clipboard ───────➤ --copy - unlock ───────➤ --decrypt - open ───────➤ --edit - lock ───────➤ --encrypt - ───────➤ --backup - ───────➤ --keychain - read ───────➤ --file - create ───────➤ --generate - ask enter type ───────➤ --interactive - from ───────➤ --keyfile - save write ───────➤ --output - using private ───────➤ --private_key - value ───────➤ --string - silently quietly silent sym ───────➤ --quiet - secure secured protected ───────➤ --password -________________________________________________________________________ -``` - -#### EXAMPLES - -```bash -# generate a new private key and copy to the clipboard but do not print to terminal -sym create new key to clipboard quietly - -# generate and save to a file a password-protected key, silently -sym create a secure key and save it to "my.key" - -# encrypt a plain text string with a key, and save the output to a file -sym encrypt string "secret string" using $(cat my.key) save to file.enc - -# decrypt a previously encrypted string: -sym decrypt string $ENC using $(cat my.key) - -# encrypt "file.txt" with key from my.key and save it to file.enc -sym encrypt file file.txt with key from my.key and save it to file.enc - -# decrypt an encrypted file and print it to STDOUT: -sym decrypt file file.enc with key from "my.key" - -# edit an encrypted file in $EDITOR, ask for key, and create a backup upon save -sym edit file file.enc ask for a key and make a backup - -# generate a new password-encrypted key, save it to your Keychain: -sym create a new protected key store in keychain "my-keychain-key" - -# print the key stored in the keychain item "my-keychain-key" -sym print keychain "my-keychain-key" - -# use the new key to encrypt a file: -sym encrypt with keychain "my-keychain-key" file "password.txt" and write to "passwords.enc" -``` - ### 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`. @@ -442,27 +368,15 @@ 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 -Bug reports and pull requests are welcome on GitHub at 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]. -## Feature Ideas - -### Natural Language Based API - -This is the proposed mini-idea/specification for an alternative CLI that is at a feature parity with the standard flag-based CLI. - - sym generate key to the clipboard and keychain - sym encrypt file 'hello' using $key [to output.enc] - sym edit 'passwords.enc' using $key - sym decrypt /etc/secrets encrypted with $key save to ./secrets - sym 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). ## Author -This library is the work of [Konstantin Gredeskoul](http:/kig.re), &copy; 2016, distributed under the MIT license. +This library is the work of [Konstantin Gredeskoul](http:/kig.re), &copy; 2016-2017, distributed under the MIT license.