= Sym — Symmetric Encryption for Humans :source-highlighter: rouge :rouge-style: base16.monokai :icons: font :toc: :sectnum: :toclevel: 4

=== Please Donate!

https://liberapay.com/kigster/donate[image:https://liberapay.com/assets/widgets/donate.svg[Donate using Liberapay,height=30]]   https://liberapay.com/kigster/donate[image:https://img.shields.io/liberapay/goal/kigster.svg?logo=liberapay[https://img.shields.io/liberapay/goal/kigster,height=30]]

====

image:https://github.com/kigster/sym/actions/workflows/ruby.yml/badge.svg[Ruby,link=https://github.com/kigster/sym/actions/workflows/ruby.yml] image:https://github.com/kigster/sym/actions/workflows/rubocop.yml/badge.svg[Rubocop,link=https://github.com/kigster/sym/actions/workflows/rubocop.yml]

image:https://api.codeclimate.com/v1/badges/4f1d1614ccaa61c974dd/maintainability[Maintainability,link=https://codeclimate.com/github/kigster/sym/maintainability]

image:https://badge.fury.io/rb/sym.svg[Gem Version,link=https://badge.fury.io/rb/sym]

image:https://codecov.io/gh/kigster/sym/branch/master/graph/badge.svg?style=shield[Coverage,link="https://codecov.io/gh/kigster/sym"] image:https://img.shields.io/gitter/room/gitterHQ/gitter.svg[Gitter,link=https://gitter.im/kigster/sym] image:https://ruby-gem-downloads-badge.herokuapp.com/sym?extension=svg[Sym Downloads,link=https://rubygems.org/gems/sym]

image:https://codecov.io/gh/kigster/sym/branch/master/graphs/sunburst.svg[Coverage Map,link=https://codecov.io/gh/kigster/sym]

NOTE: Please checkout the following post — http://kig.re/2017/03/10/dead-simple-encryption-with-sym.html[Dead Simple Encryption with Sym] — that announced the initial release of this library, and provides further in-depth discussion. Your donation of absolutely any amount is much appreciated but never required.

image:https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif[Donate,link=https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=FSFYYNEQ8RKWU]

NOTE: You can read this README in the properly rendered for print format, by downloading the xref:README.pdf[PDF].

== Introduction

NOTE: SYM is an open source command line utility and a Ruby library, which makes it _trivial to encrypt your application secrets with mathematically proven models and ciphers offered in a much larger project — Open SSL.

Unlike many existing encryption tools, sym 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. +

• sym uses the https://en.wikipedia.org/wiki/Symmetric-key_algorithm[Symmetric Encryption] 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. +

• Finally, the library offers encryption using any regular password, and in particular supports password-protected encryption keys. Automatic key detection algorithm attempts to resolve a provided key as a filename, an environment variable name, an OS-X Keychain password entry name, a key itself, or a default key file. +

NOTE: Sym uses Ruby's Marshall.dump to serialize it's data, and therefore it is not currently possible or easy to deserialize the data in languages other than Ruby.

=== Quick Demo of the CLI in Action

image::design/ascii-cinema.png[asciicast,link=https://asciinema.org/a/106737]

==== Help Screens, Examples and Symit Bash Wrapper

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.

Additionally, Sym comes with a helpful BASH wrapper symit.

Help screens for sym and symit are shown in full on another page -- xref:SYM-CLI.adoc[Sym Help Screens and Symit]. Please refer to it for complete help screens and the examples.

== Supported Ruby Versions

NOTE: Ruby 3.0.0 is only supported by Sym version 3.0.1 and later.

Sym currently builds and runs on the following ruby versions on Travis CI:

.Ruby Version Compatibility [cols="<,<", width="80%"] |=== | MRI Ruby |JRuby

| 2.3.8 | jruby-9.1.17.0 | 2.4.10| jruby-9.2.13.0 | 2.5.8 | | 2.6.6 | | 2.7.1 |

|===

=== 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 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 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 https://www.openssl.org/[OpenSSL] 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:

. <<cli,Rich command line interface CLI>> with many features to streamline encryption/decryption, and to be integrated into the deployment flow. + . Ruby APIs: ** <<rubyapi,Key Generation, Encryption & Decryption API>> *** is activated by including Sym module in a class, it adds easy to use encr/decr methods. ** <<rubyapi-app,Application API to shadow the CLI usage>> *** You can instantiate Sym::Application class with a hash representing CLI arguments, and then call it's #execute method to mimic CLI execution. ** <<magic-file,Sym::MagicFile API>> *** This is a convenience class allowing you to encrypt/decrypt files in your ruby code with just couple of lines of code. ** <<rubyapi-config,Sym::Configuration>> *** Use this class to override the default cipher, and configure other parameters such as compression, password caching, and more.

=== Massive Time Savers

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, 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 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.

[quote, Socrates (LOL)] Encrypting application secrets had never been easier!

== Using Sym

[discrete] ==== 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:

[source,bash]

$ 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.

[discrete] ==== Typical Use-Case Scenario

. 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. . Next, let's assume you have a file or a string that you want to encrypt. We call this data. . 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. . Finally, we are ready to encrypt. The data to be encrypted can be read from a fi