share-secrets-safely (sheesy) is a solution for managing shared secrets in teams and build pipelines.

Like pass, sy allows to setup a vault to store secrets, and share them with your team members and tooling. However, it wants to be a one-stop-shop in a single binary without any dependencies except for a gpg installation, helping users to work with the gpg toolchain and workaround peculiarities.

Installation

Please read the installation notes here.

Getting Started

The first steps showing on how to use the vault with a complete example and detailed explanations can be found in the book.

Project Goals

• a great user experience
  • The user experience comes first when designing the tool, making it easy for newcomers while providing experts with all the knobs to tune
  • deploy as single binary, without dynamically linked dependencies
• proven cryptography
  • Don't reinvent the wheel, use gpg for crypto. It's OK to require gpg to be installed on the host
  • Thanks to GPG each user is identified separately through their public key
• automation and scripting is easy
  • storing structured secrets is as easy as making them available in shell scripts
  • common operations like substituting secrets into a file are are natively supported
  • proper program exit codes make error handling easy
• user management
  • support small and large teams, as well as multiple teams, with ease
  • make use of gpg's web of trust to allow inheriting trust even across team boundaries, and incentivize thorough checking of keys
• basic access control
  • partition your secrets and define who can access them
• support old wheels - pass compatibility
  • something pass does really well is to setup a vault with minimal infrastructure and configuration. We use said infrastructure and don't reinvent the wheel.
  • This makes us compatible with pass, allowing you use pass on a sheesy vault with default configuration.

Non-Goals

• replicate pass or gpg functionality directly
  • having seen what pass actually is and how difficult it can be to use it especially in conjunction with gpg, this project will not even look at the provided functionality but be driven by its project goals instead.
• become something like hashicorp vault
  • this solution is strictly file based and offline, so it can fill be used without any additional setup.

Why would I use sheesy over...

You will find various and probably biased and opinionated comparisons in our book. However, it's a fun read, and please feel free to make PRs for corrections.

Caveats

• Many crypto-operations store decrypted data in a temporary file. These touch disk and currently might be picked up by attackers. A fix could be 'tempfile', which allows using a secure temporary file - however, it might make getting MUSL builds impossible. Static builds should still be alright.
• GPG2 is required to use the 'sign-key' operation. The latter is required when trying to add new unverified recipients via vault recipients add <fingerprint>.

Roadmap to Future

As you can see from the version numbers, this project dispenses major version generously. This is mainly because, for the sake of simplicity, there is only a single version number for the CLI as well as all used libraries.

Effectively, you can expect the CLI will change rarely, and if it does only to improve the user experience. The more tests we write, the more certain shortcomings become evident.

The vault library and its types will change much more often, but we would expect it to settle from 5.0.

Roadmap to 3.1

Substitution-Superpowers

Make it easy to generate property-sets by merging structured files together, and make said context available to a handlebars powered engine to perform substitutions.

This allows to bring together context owned by various entities into a single aggregated one, with the possibility for later contexts to override earlier ones.

With this capability, it's also possible to substitute secrets into files, for example like this: sy sub base.json sub/ours.yaml <(sy vault show secret.yaml) < deployment.yml | kubectl apply -f -

Roadmap to 3.2

Adding the merge subcommand

The merge subcommand allows to combine json or yaml files. This is useful to partition context and data according to your needs, yet use all of the values in combination for substitution. This is particularly useful if some of that content was just decrypted from a vault.

Roadmap to 3.3

Adding the extract subcommand

The extract capability makes it feasible to store secrets in structured files like YAML or JSON, as it allows to extract pieces of data in various ways. Think jq but with native support for YAML files.

Roadmap to 3.4

Improved UX and basic Web of Trust controls

• [ ] Assure that the error messages provided when we can't find a partition are better and specific to the use case.
• [ ] Tree mode for lists of
  • [ ] recipients
  • [ ] resources
• [ ] Configure web-of-trust options on per-partition basis and use that when encrypting.
  • this includes an option to turn it off (i.e. something like --always-encrypt)
• [ ] Don't fail when listing recipients whose keys are not in the keychain
• [ ] Option to auto-import keys when encrypting resources (how does it work with WoT?)

Roadmap to 4.0

Sub-Commands as standalone programs

Even though the main binary should by sy as before, the code should be structured to provide cli versions of the respective subcommand, e.g. vault-cli. That way, people can also use special-purpose sub-programs directly without having a binary that contains all the other cruft.

This can be useful to make pass standins more approachable, and also build custom sy binaries with just a sub-set of the functionality (for example, without pass stand-in capability).

• [ ] move vault-cli into own library and use it from hub cli.

Roadmap to 4.1

Add the pass subcommand

sy aims to be as usable as possible, and breaks compatiblity were needed to achieve that. However, to allow people to leverage its improved portability thanks to it being self-contained, it should be possible to let it act as a stand-in for pass.

Even though its output won't be matched, its input will be matched perfectly, as well as its behaviour.

Roadmap to 5.0

Web of Trust for everyone

The web-of-trust is powerful if used correctly, and helps to assure you are encrypting only for trusted keys.

• [ ] Suggestion engine to learn how to encrypt for everyone in partition(s) with the least amount of work. It will suggest 'ownertrust' to well-connected people and make available everyone they signed for.
• [ ] suggest to import keys or do it for the user
• [ ] suggest to trust recipients or ((locally) sign) to make encryption possible

Development Practices

• test-first development
  • protect against regression and make implementing features easy
  • user docker to test more elaborate user interactions
  • keep it practical, knowing that the Rust compiler already has your back for the mundane things, like unhappy code paths.
• safety first
  • handle all errors, never unwrap
  • provide an error chain and make it easy to understand what went wrong.
• strive for an MVP and version 1.0 fast...
  • ...even if that includes only the most common usecases.
• Prefer to increment major version rapidly...
  • ...instead of keeping major version zero for longer than needed.

Maintenance Guide

Making a release

As a prerequisite, you should be sure the build is green.

• run clippy and fix all warnings with cargo +nightly clippy --all
• change the version in the VERSION file
• update the release notes in the release.md file.
  • Just prefix it with a description of new features and fixes
• run make tag-release
  • requires push permissions to this repository
  • requires maintainer or owner privileges on crates.io for all deployed crates

Making a deployment

As a prerequisite you must have made a release and your worktree must be clean, with the HEAD at a commit.

For safety, tests will run once more as CI doesn't prevent you from publishing red builds just yet.

• run make deployment.
• copy all text from the release.md file and copy it into the release text on github.
• drag & drop all tar.gz into the release and publish it.
• run make update-homebrew and push the changed brew file

Making a new Asciinema recording

Even though the documentation is currently updated with every push to master (to allows fixing the existing docs easily), the eye-candy on the front page needs to be regenerated too.

As a prerequisite, you will need an installed binary of asciinema. Please make sure your player is already linked to your account via asciinema auth.

• Set your terminal to a size of 120x20
  • You see these units when resizing an iterm2/3 terminal window
• run make asciinema-no-upload and verify it contains what you expect with asciicast play getting-started.cast
• Possibly upload the recording with make asciinema-upload
  • Enter the given URL and configure the asciicast to your liking, add backlinks to the description, and make it nice.