---
robots: noindex, nofollow
---

# Tools to Support Shell Script

## Updated Description

The goal of the SSH scenario is to support software releases with signatures and validation using SSH signatures and Gordian Envelopes. The [Gordian Server 1.1.0](https://github.com/BlockchainCommons/GordianServer-macOS/releases/tag/v1.1.0) release is a good baseline: it allowed for the signing of a release and its SHA256SUMS as well as the publication of the related keys with self-signing, signing from previous keys, or both. However, the Gordian Server 1.1.0 release was also a mess because there's limited order and organization to the data and no automation for testing the validation. [Bitcoin Core](https://coinguides.org/verify-bitcoin-core-signatures/) is another model for software release and verification.

The general use case is:
1. Sign releases with SSH keys.
2. Package release, signatures of releases (possibly by multiple people), and related pub keys into an Envelope.
* Our current release structure uses SHA256SUMS, but our assumption is the natural hashing of Envelope will replace this.
4. Optionally package self-signings of keys into Envelope.
5. Optionally package signings of older keys with newer keys.
6. Organize to highlight changes in keys between releases.*
7. Organize to make it easy to validate hash of release, signatures against keys, self-signings of keys, updated keys against old keys, and keys against keys registered with GitHub.*
8. Leverage use of GitHub signatures of tags, signatures of commits, and uploading of signing keys.*
9. Include additional metadata as needed.*

Some of this may be solely structural: fundamentally, we need any new code to make this possible with a specific structure being a lesser/future issue except as required by the core needs. Some issues(*) may also be better served by a future shell script rather than `envelope-cli` itself.

Our best guess is that the following functionality is necessary in `envelope-cli` and/or as a separate tool:

1. Import an encrypted SSH Key into Gordian Envelope.
2. Store SSH Key so that it can be recovered/decrypted with passwd entry, as with SSH keys.
3. Ability to sign in Gordian Envelope with SSH key.
4. Ability to verify a SSH key signature held within Gordian Envelope, possibly by exporting SSH key and what's signed for consideration by SSH keygen.
5. Ability to attest with SSH key (might be the same as #3).
6. Diff-like function that can show a key change from one-release to another AND verify that new key in "newer" package has been signed with old key from "older" package
7. Sufficient structure to fulfill any requirements implicit in above, such as a need for ordering to allow diff-like function to identify which release package is oldest beteween two in #6.

==

OLDER DESCRIPTION

I wrote up one MVP scenario that I'd like to be able to create myself, or with Shannon's help, in the near future. From what I can tell, the only things that I need beyond my own shell scripting tools are:

* some way to read the SSH keys into envelopes
* some way to do an envelope attestation with SSH keys
* some way to verify an SSH envelope attestation
* and optionally, be able verify an existing ssh signature file against an input file, raw git commit data, or a pre-generated hash compatbile with SSH (is that SHA-512?)

It could be these don't need to be in a new Gordian Companion tool, and could just be additions to the Rust Envelope tool.

Here is my outline of what I'm trying to do. Maybe there is some better way to do this than three features added to rust envelope, or gordian companion does it, I'm not sure:

Two shell scripts:

Create:
- two envelopes, one with private key material, one without. [I can do this with envelope tool now, but likely need some structure advice].
- Private:
- I need to decrypt and put 1+ signing keys (one for each machine) into my private envelope's structure. [This I'll need some tool to decrypt the SSH key and parse it into the appropriate place in the private envelope, but it could be an addition to envelope tool]
- THIS IS A TODO: GET ENVELOPE TO READ/DECRYPT THE PRIVATE KEY ON DISK. AND ENCRYPT IT.
- PASSWORD ENCRYPTION?
- I need to associate various metadata with that key [I can do this with envelope tool now, with output of the previous tool, but likely need some structure advice]
- Public:
- This will be my Self-Sovereign Assertion envelope (SSA? SSE?, but alternatives are Decentralized Key Document (DKD), Autonomous Identity Declaration (AID), Key Attestation Record (KAR), I'm totally open on naming.
- It will have at minimum
- my public keys, corresponding JSON object https://api.github.com/users/ChristopherA/ssh_signing_keys [script can do this]
- specific metadata about each signing key, at minimum matching other data at https://api.github.com/users/ChristopherA/ssh_signing_keys [script can do this]
- A self-signed envelope attestation, signed compatible with SSH, where each key signs itself saying the holder of the private key controls this key. [This I need a tool for, our ability to do this with envelope tool]
- TODO: SSH Signing within Envelope
- TODO: How can we export it so that ssh keygen can verify?
- A envelope attestation, of each key asserting "same as" each other key, giving all the same signing authority. [needs same SSH attestation function]
- TODO: Point to other tree? Point to other key? [pubkey, sameas, point to other envelope]
- An attestation from each key that say the holder controls github account ChristopherA with the keys at https://api.github.com/users/ChristopherA/ssh_signing_keys [need same SSH attestion function]
- TODO
- An attestation that you can find future version of this file at https://github.com/ChristopherA/ChristopherA/ChristopherA.ssa.env and that the git commitment to added or modified this file was signed by one of these keys (because of catch-22 you can't put the actually commitment here, but maybe the previous commitment?) [only needs SSH attestation function]
- TODO

[tell him that we're basically trying to replicate our GitHub signing with Envelopes]
[/what is done with signing Bitcoin]
[but better]

Verify:
-- Allows anyone to verify a file.
-- standard SSH .sig detached signature
-- looks for .sig.env in the same directory
-- is able to parse the envelope, confirm the keys against github, and then verify that one of those keys was used to sign the .sig, and verify the sig.
[this needs either new tool to verify ssh signatures in envelopes, or an update to envelope tool]

==
GENERAL NOTES ON PROCESS:

* Put script in tagged release
* That checks PGP keys and such
* But does it with SSH keys
* Tag should be signed by one of the SSH keys
* Commits in history since last tagged release are by someone's authorized keys
* Signatures/Commits have CLA behind them
* And exemplifies best practices of key separation (auth/sign, by machine)