share-secrets-safely/cli

share secrets within teams to avoid plain-text secrets from day one

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 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 4.1

This should make the first release which can be publicised, as it should include all the material people might need to get started using sheesy comfortably.

• Documentation for
  • vault init
  • ...

Roadmap to 5.0

The GPGME dependency is also the major flaw for usability, as it eventually goes down to the quirks of GPG itself. SEQUOIA is a pure-Rust implementation of the PGP protocol, which would greatly help making sheesy even more usable.

• Use SEQUOIA instead of GPGME
• Provide a windows binary

Roadmap to 6.0

Add the pass subcommand

sy aims to be as usable as possible, and breaks compatibility 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.

• init

And last but not least, there should be some sort of documentation, highlighting similarities and differences.

• documentation

Some usability improvements

• 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

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 clippy --all-features --bin=sy
• 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.
• in doc/src/installation.md, update the URL to use the latest published version
• run make update-homebrew - it will push for you
• run make update-getting-started - it will push for you

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.

cli's Issues

`sy vault recipient add ...` fails with 'could not sign key of recipient'

After running the command from the subject on linux (ubuntu) we saw this message.

Imported recipient key at path '.gpg-keys/60D52894609DDDFC794BCAC62DDE29BE8568696B'
error: The GNU Privacy Guard (GPG) does not supported the attempted operation.
GPG v2 is known to work, and you can install it here:
https://www.gnupg.org for more information.
Caused by:
2: Could not sign key of recipient 60D52894609DDDFC794BCAC62DDE29BE8568696B with signing key <user redacted>
1: Not supported (gpg error 60)

`vault edit` allows creating files outside of the `secrets` directory`

When installed on OSX with Homebrew on Apple Silicon, the sy command fails to load libassuan.0.dylib

Steps to reproduce:

Install Sheesy with on OSX with a recent version of Homebrew:

brew tap share-secrets-safely/cli
brew install sheesy

Then run any command, for example sy --version.

Expected behaviour

The command runs without issues.

Actual behavior

The command fails with:

dyld[2780]: Library not loaded: /usr/local/opt/libassuan/lib/libassuan.0.dylib
  Referenced from: <E27503E4-8399-3EE0-8726-E6E09272A3EC> /opt/homebrew/Cellar/sheesy/4.0.10/bin/sy
  Reason: tried: '/usr/local/opt/libassuan/lib/libassuan.0.dylib' (no such file), '/System/Volumes/Preboot/Cryptexes/OS/usr/local/opt/libassuan/lib/libassuan.0.dylib' (no such file), '/usr/local/opt/libassuan/lib/libassuan.0.dylib' (no such file), '/usr/local/lib/libassuan.0.dylib' (no such file), '/usr/lib/libassuan.0.dylib' (no such file, not in dyld cache)
zsh: abort      sy vault list

Note that libassuan is correctly installed on the system (with Homebrew).

The version you were using

The command sy --version crashes, but the installed sy version is 4.0.10.

I am on MacOS Ventura 13.1 on Apple Silicon M1 Max.

The Homebrew version is:

$ brew --version
Homebrew 3.6.20
Homebrew/homebrew-core (git revision 9b06fea8797; last commit 2023-01-17)

Possible explanation

Homebrew on Apple Silicon uses /opt/homebrew as prefix instead of /usr/local (as indicated by the output of brew --prefix and as discussed here), therefore libassuan is located in /opt/homebrew/lib/libassuan.0.dylib. Currently, sy tries to load it from /usr/local and /usr/lib.

Explicitly setting DYLD_LIBRARY_PATH=/opt/homebrew/lib sy --version finds the library, but fails with:

dyld[9043]: Library not loaded: /usr/local/opt/libassuan/lib/libassuan.0.dylib
  Referenced from: <E27503E4-8399-3EE0-8726-E6E09272A3EC> /opt/homebrew/Cellar/sheesy/4.0.10/bin/sy
  Reason: tried: '/opt/homebrew/lib/libassuan.0.dylib' (mach-o file, but is an incompatible architecture (have 'arm64', need 'x86_64')), '/usr/local/opt/libassuan/lib/libassuan.0.dylib' (no such file), '/System/Volumes/Preboot/Cryptexes/OS/usr/local/opt/libassuan/lib/libassuan.0.dylib' (no such file), '/usr/local/opt/libassuan/lib/libassuan.0.dylib' (no such file), '/usr/local/lib/libassuan.0.dylib' (no such file), '/usr/lib/libassuan.0.dylib' (no such file, not in dyld cache)

This seems to indicate that the wrong architecture is used when downloading the pre-built sy binary, I suspect because -x86_64 is hardcoded here, and the releases do not include an arm64 version.

Cloning the repo and building it with Cargo produces a working sy binary, so it looks like it is really just an issue with missing pre-built binary for Apple Silicon.

Feature Request: Please publish to home brew for OSX for easier adoption

Consider bringing https://github.com/share-secrets-safely/cli/community to 100%

Just to make the project even more appealing.

Comparison to git-crypt

It would be nice if the documentation would how sheesy differentiates itself from a git-crypt.

So far as I can see currently:

• No integration with git
• No support for simple AES key encryption

Maybe it doesn't make sense to compare sheesy to a tool like git-crypt in the first place, since the scopes are somewhat different, if so I apologize! I think that sheezy could be super useful for storing secrets right in git repos so that's one way I really want to use it.

P.S. I just saw the talk @ RustCologne -- cool project!

Add practical use-case example

I like the GPG key based ACL of this tool and can see how it prevents leaks.

But I fail to imagine the real-world usage in a team of developers and I cannot find one in the documentation.

Is is something like:

1. Alice, Bob and Charlie are working on a software source code versioned by git repository (and shared amongst them via GitHub, GitLab or any other central git repository).
2. Alice want to store MySQL password into software's git repository but doesn't want neither Bob nor Charlie to have access to this secret.
   1. Alice creates a secrets directory into software's source code directory on it's computer, cd into it and run sy vault init to initialize the sheesy vault "secrets".
   2. Alice runs git add . ; git commit -m "Created a secrets sheesy vault" to commit the vault creation.
   3. Alice adds the MySQL password to the vault with: echo s3cre7 | sy vault add :mysql-password.
   4. Alice runs git add . ; git commit -m "Added MySQL password to the secrets vault"; git push origin for the changes the sy vault add command did on the sheesy vault ("secrets") are saved to the git repository.
3. After some time, Alice trusts Bob to read secrets, so Alice asks Bob to run (on it's computer): cd secrets ; sy vault recipient init to add it's GPG key to possible recipients and git add . ; git commit -m "Adding Bob's key to the secrets vault" ; git push origin to persist the changes to the git repository.
4. Alice can now run cd secrets ; sy vault recipient add 7DF95D5E and git add . ; git commit -m "Granting Bob's key access to secrets sheesy vault" ; git push origin and tells Bob that she granted him access to the "secrets" vault.
5. Bob can now cd secrets and finally read the MySQL with sy vault show mysql-password.
6. Charlie see the commits, see the list of secrets (using sy vault) but can never read them.

Notes:

• I am intentionally omitting the parts where Alice, Bob and Charlie runs their git fetch and git merge commands.
• On point 2., if Alice wants to store the password into software's git repository, could it be because software's deployment script will need it (in which case a other recipient should be added)?

Migrate single partition vault into multi partition one

Hi there,
I am a very happy user of sy, and in my company we have setup a vault a long time ago. Now I would love to add partitions to it, but unfortunately I created it as a single-partition at the beginning, so if I try to add a partition named devs I get the following error:

error: Partition at './devs' is contained in another partitions resources directory at './.'

Is there a way, even manually, to migrate a single partition vault into a multi partition one?

I am using sy version 4.0.10.

The OSX installation instructions don't work

They need the 'cli' repository named as last argument.
Thanks a lot

'sy process' tries to read from stdin and blocks forever

If no TTY is attached, it will always try to read from stdin. However, this seems to block forever in certain situations, without indicating EOF or something similar.

Maybe there is a way to detect that, or to workaround it without forcefully providing something like echo '{}' | sy process ....

vault edit must respect 'always trust' settings

check it - in pass there is no such thing.

Provide the native homebrew repository - see image

Looks like adding a repo called 'homebrew-cli' would do the job naturally. Would also mean we have to store the homebrew file out of tree, but that should be alright.

Fix new line when checking version

Hi,

I have been using this in my project. It is very useful for storing our passwords. Thanks.

However when I check the version it comes with a newline.

shakir$./sy --version
sy 4.0.0

shakir$

Can you please fix this ?

Windows support?

Since both rust and gpg run on Windows, what obstacles are there to sy running on Windows, too?

Add use-case/cookbook style documentation

While the sheesy documentation is pretty fantastic already, I felt there was a little to be desired as far as the various vault pages, in particular vault partitions.

I was looking for basically group-like support -- being able to share a secret with a group of users but not necessarily a different group, more concretely to be able to differentiate secrets for staging/production. When looking at the vault partitions add documentation it was unfortunately a little unclear

Since what I was looking for is likely a very common usecase, it might be nice to explain it directly, either on the add page itself or in a separate "recipes" or "use case examples" or something section.

Add support for symmetric cryptography with Sequoia

As of now, we depend on GPG for asymmetric cryptography. However, depending on GPGME seems to be an issue if Windows support is desired.

An alternative seems to be Sequoia, which has Windows support on their roadmap for 2019. To get started, it should already be possible to add symmetric (i.e. password based) cryptography to sheesy, serving as quick-start alternative to the key-based cryptography and thus somewhat competing with keypass and its command-line tools.

Requirements

• assure symmetric crypto is compatible with GPG, and ideally the GPG tools can be used for decryption, too, if the password is known.

Open Questions

• should it be possible to transition between stores of different kinds, e.g. asymmetric to symmetric and vice-versa?
• Will it be clear how files are encrypted, to not mistake asymmetrically encrypted files with symmetric ones and fail decryption for that reason.

Alternatives

• https://github.com/miscreant/miscreant-rs
  • asymmetric pure-rust crypto. Would work as well, but may be less vetted than nettle.

Related to #12 .

Failed compiling sheesy-cli v1.0.1

Hi,
just installed rustup and cargo to install sheesy-cli.
After executing cargo install sheesy-cli, I get a bunch of lines like Compiling ... which looks good.

Until:

Compiling libgpg-error-sys v0.3.1
Compiling gpgme-sys v0.7.0
Compiling gpgme v0.7.1
error: failed to run custom build command for `gpgme-sys v0.7.0`
process didn't exit successfully: `/var/folders/rg/jmhmvgl57rj4n1xmgyb2lt7m0000gn/T/cargo-install.MCN5Z2Gid1rP/release/build/gpgme-sys-69e4934ff7b01c8d/build-script-build` (exit code: 1)
--- stdout
cargo:rerun-if-env-changed=GPGME_LIB_DIR
cargo:rerun-if-env-changed=GPGME_LIBS
cargo:rerun-if-env-changed=GPGME_CONFIG

--- stderr
running: "git" "apply" "../gpgme-remove-doc.patch"
error: patch failed: Makefile.am:33
error: Makefile.am: patch does not apply
error: patch failed: configure.ac:883
error: configure.ac: patch does not apply
command did not execute successfully, got: exit code: 1
running: "sh" "-c" "gpgme-config --version"
sh: gpgme-config: command not found
command did not execute successfully, got: exit code: 127

warning: build failed, waiting for other jobs to finish...

I'm running OSX El Capitan Version 10.11.6 (15G1510) if that helps somehow.

Do you have any idea if I can fix it myself?
Thanks in advance.