First of all, we assume that you have installed the sy command-line program already. If not, please have a look at the chapter about installation.

Assuming your current directory is empty, just running vault will error.

sy vault

error: Failed to read vault configuration file at './sy-vault.yml'

Caused by: 
 1: No such file or directory (os error 2)

What you want to do is to initialize the vault. This will add yourself as the first recipient and add some state to the directory you chose or that you are in.

sy vault init

error: No existing GPG key found for which you have a secret key. Please create one with 'gpg --gen-key' and try again.

Assuming we have followed the instructions or already have setup a gpg key, you will get quite a different result.

sy vault init

Exported public key for user Tester (for testing only) <tester@example.com> to '.gpg-keys/D6339718E9B58FCE3C66C78AAA5B7BF150F48332'
vault initialized at './sy-vault.yml'

Usually what happens next is to add some resources. For now they will only be encrypted for you, and thus can only be read by you.

Resources are added via resource specs, or can be created by editing.

There are various ways to add new resources...

...by gathering output from a program...

echo hi | sy vault add :from-program

Added 'from-program'.

...or from existing files.

sy vault add $SRC_DIR/README.md:README.md

Added 'README.md'.

You can list existing resources...

sy vault list

syv://.
README.md
from-program

or you can show them.

sy vault show from-program

hi

Even though secrets that are not shared with anyone (but yourself) are great for security, they are not too useful in many settings.

So we will add our first recipient, Alexis!

As always, Alexis will require an own gpg key, and for the sake of simplicity we will assume it is already present.

Usually it's also easiest to let new recipients 'knock at the door of the vault', and leave it to existing recipients of the vault to 'let them in'.

In this analogy, 'knocking the door' is equivalent to placing their key in the vaults keys directory. 'Letting them in' means re-encrypting all resources for the current and the new recipients after verifying their key truly belongs to them.

That's quite a lot to digest, so let's start and make small steps.

Let's let Alexis look at the vault:

sy vault

syv://.
README.md
from-program

What a good start! We can list resource, but does that mean we can also see them?

sy vault show from-program

error: Export your public key using 'sy vault recipient init', then ask one of the existing recipients to import your public key using 'sy vault recipients add <your-userid>.'
Caused by: 
 2: The content was not encrypted for you.
 1: No secret key (gpg error 17)

Phew, that's good actually! It's also good that it tells you right away how to solve the issue. Let's follow along.

sy vault recipient init

Exported public key for user c <c@example.com> (905E53FE2FC0A500100AB80B056F92A52DF04D4E).

Cough, let's ignore this key seems to be for c c@example.com, Alexis loves simplicity!

Let's see what changed - where is this key exactly?

tree -a

.
├── .gpg-id
├── .gpg-keys
│   ├── 905E53FE2FC0A500100AB80B056F92A52DF04D4E
│   └── D6339718E9B58FCE3C66C78AAA5B7BF150F48332
├── README.md.gpg
├── from-program.gpg
└── sy-vault.yml

1 directory, 6 files

It looks like the keyfile is actually stored in a hidden directory. But as you can see, it's just something that can be configured to your liking.

cat sy-vault.yml

---
name: ~
auto_import: true
trust_model: always
secrets: "."
gpg_keys: ".gpg-keys"
recipients: "./.gpg-id"

That's all we can do here, now back to the prime recipient.

Back with the very first recipient of the vault who has already been informed about Alexis arrival. We received an e-mail and know it's c@example.com, maybe we can use that.

sy vault recipient add c@example.com

error: Fingerprint 'c@example.com' must only contain characters a-f, A-F and 0-9.

Looks like it doesn't like the format. The problem is that for verification purposes, it wants you to add the fingerprint, which you should also have received by Alexis. This links the key (identified by its fingerprint) to Alexis.

Let's spell it out:

sy vault recipient add 2DF04D4E

Imported recipient key at path '.gpg-keys/905E53FE2FC0A500100AB80B056F92A52DF04D4E'
Signed recipients key user c <c@example.com> (905E53FE2FC0A500100AB80B056F92A52DF04D4E) with signing key Tester (for testing only) <tester@example.com> (D6339718E9B58FCE3C66C78AAA5B7BF150F48332)
Exported public key for user user c <c@example.com> to '.gpg-keys/905E53FE2FC0A500100AB80B056F92A52DF04D4E'
Added recipient user c <c@example.com>
Re-encrypted 'README.md' for new recipient(s)
Re-encrypted 'from-program' for new recipient(s)

Let's look at the steps that it performs in details:

• import
  • it finds Alexis key as identified by the fingerprint in the vaults keys directory and imports it into the gpg keychain.
• signing
  • Alexis key is signed with the one of the prime recipient, which indicates we verified that it truly belongs to Alexis.
• export
  • Alexis key is re-exported as it now also contains said signature. The fact that the prime recipient believes that the key belongs to Alexis is communicated to others that way, which helps building the Web of Trust.
• encrypt
  • Each resource of the vault is re-encrypted for all recipients. This means Alexis will be able to get to peek inside.

(If we would already have Alexis in our keychain and signed their key, you could also more easily add them using their email alongside the --verified flag. Find all possible flags of the sy-vault-recipients-add here)

Now that Alexis has been added as a recipient, it should be possible to peek at the secrets it contains!

sy vault show from-program

hi

Beautiful!

And what's even better: Alexis now can add recipients on their own!

This is just the beginnings! Feel free to add more resources and recipients, add the contents of the vault to git and distribute it that way, or add it to your tooling to extract secrets when building your software.