cmd

README

Usage examples and supported subcommands

Generate a key-pair

The following command generates a private key:

gosop generate-key "Alice <alice@example.com>" > private-key.sec

Note that, as per the OpenPGP specification, this private key also contains public key material. You can extract the public key (also referred to as certificate) safely as follows:

gosop extract-cert < private-key.sec > public-key.pgp

This outputs PGP armored strings by default

$ head -n1 private-key.sec
-----BEGIN PGP PRIVATE KEY BLOCK-----
$ head -n1 public-key.pgp
-----BEGIN PGP PUBLIC KEY BLOCK-----

but you may use binary format providing the --no-armor flag to the above commands.

Encrypt/decrypt

Using a passphrase

gosop encrypt --with-password="strong_passphrase" < input_file > encrypted_file
gosop decrypt --with-password="strong_passphrase" < encrypted_file > decrypted_file

Using PGP keys

gosop encrypt public-key.pgp < file_to_encrypt > encrypted_file
gosop decrypt private-key.sec < encrypted_file > decrypted_file

For advanced modes and available flags, run gosop help encrypt, gosop help decrypt.

Sign/Verify

gosop sign private-key.sec < file_to_sign > signature.asc
gosop verify signature public-key.asc < signature.asc

You need to inspect the exit status and output of verify to check if the signature is valid.

Armor/Dearmor

Any PGP armored string, you can convert it to/from binary. gosop will automatically detect the type from the underlying packets, and set the correct headers (SIGNATURE, MESSAGE, etc).

gosop dearmor < public-key.asc > public-key-binary

Documentation

Overview

Package cmd defines all commands for the gosop implementation.

Index

• Constants
• Variables
• func ArmorComm(keyFilenames ...string) error
• func DearmorComm() error
• func Decrypt(keyFilenames ...string) error
• func Encrypt(keyFilenames ...string) error
• func Err99(cmd string, err error) error
• func ExtractCert() error
• func GenerateKey(userIDs ...string) error
• func InlineDetach() error
• func InlineSign(keyFilenames ...string) error
• func InlineVerify(input ...string) error
• func ListProfiles(commands ...string) error
• func Sign(keyFilenames ...string) error
• func Verify(input ...string) error
• func Version() error

Constants

const SOPV_VERSION = "1.0"

const SOP_VERSION = "~draft-dkg-openpgp-stateless-cli-06"

const VERSION = "1.1.0"

Variables

var (
	Err3  = cli.Exit("Code 3: No acceptable signatures found (\"gosop verify\")", 3)
	Err13 = cli.Exit("Code 13: Asymmetric algorithm unsupported (\"gosop encrypt\")", 13)
	Err17 = cli.Exit("Code 17: Certificate not encryption-capable (\"gosop encrypt\")", 17)
	Err19 = cli.Exit("Missing required argument", 19)
	Err23 = cli.Exit("Incomplete verification instructions (\"gosop decrypt\")", 23)
	Err29 = cli.Exit("Unable to decrypt (\"gosop decrypt\")", 29)
	Err31 = cli.Exit("Non-\"UTF-8\" password (\"gosop encrypt\")", 31)
	Err37 = cli.Exit("Unsupported option", 37)
	Err41 = cli.Exit("Invalid data type (no secret key where \"KEY\" expected, etc)", 41)
	Err53 = cli.Exit("Non-text input where text expected", 53)
	Err67 = cli.Exit("A KEYS input is password-protected (locked), and sop cannot unlock it with any of the --with-key-password options", 67)
	Err69 = cli.Exit("Unsupported subcommand", 69)
	Err83 = cli.Exit("Options were supplied that are incompatible with each other", 83)
	Err89 = cli.Exit("The requested profile is unsupported or the indicated subcommand does not accept profiles", 89)
)

Error codes as defined in the draft, section 6.

var All = []*cli.Command{
	{
		Name:  "version",
		Usage: "Version Information",
		Flags: []cli.Flag{
			backendFlag,
			extendedFlag,
			sopSpecFlag,
			sopvFlag,
		},
		Action: func(c *cli.Context) error {
			return Version()
		},
	},
	{
		Name:      "list-profiles",
		Usage:     "List profiles for subcommands",
		UsageText: "gosop list-profiles SUBCOMMAND",
		Flags:     []cli.Flag{},
		Action: func(c *cli.Context) error {
			return ListProfiles(c.Args().Slice()...)
		},
	},
	{
		Name:      "generate-key",
		Usage:     "Generate a Secret Key",
		UsageText: "gosop generate-key [command options] [USERID...]",
		Flags: []cli.Flag{
			noArmorFlag,
			selectedProfileFlag,
			keyPasswordFlag,
		},
		Action: func(c *cli.Context) error {
			return GenerateKey(c.Args().Slice()...)
		},
	},
	{
		Name:      "extract-cert",
		Usage:     "Extract a Certificate from a Secret Key",
		UsageText: "gosop extract-cert [command options]",
		Flags: []cli.Flag{
			noArmorFlag,
		},
		Action: func(c *cli.Context) error {
			return ExtractCert()
		},
	},
	{
		Name:      "sign",
		Usage:     "Create a Detached Signature",
		UsageText: "gosop sign [command options] KEY [KEY...] < DATA",
		Flags: []cli.Flag{
			noArmorFlag,
			asFlag,
			keyPasswordFlag,
		},
		Action: func(c *cli.Context) error {
			return Sign(c.Args().Slice()...)
		},
	},
	{
		Name:      "verify",
		Usage:     "Verify a Detached Signature",
		UsageText: "gosop verify SIGNATURE CERTS [CERTS...] < DATA",
		Flags: []cli.Flag{
			notBeforeFlag,
			notAfterFlag,
		},
		Action: func(c *cli.Context) error {
			return Verify(c.Args().Slice()...)
		},
	},
	{
		Name:      "inline-sign",
		Usage:     "Create an Inline-Signed Message",
		UsageText: "gosop inline-sign [command options] KEY [KEY...] < DATA",
		Flags: []cli.Flag{
			noArmorFlag,
			asSignedFlag,
			keyPasswordFlag,
		},
		Action: func(c *cli.Context) error {
			return InlineSign(c.Args().Slice()...)
		},
	},
	{
		Name:      "inline-verify",
		Usage:     "Verify an Inline-Signed Message",
		UsageText: "gosop inline-verify CERTS [CERTS...] < INLINESIGNED",
		Flags: []cli.Flag{
			notBeforeFlag,
			notAfterFlag,
			verificationsOutFlag,
		},
		Action: func(c *cli.Context) error {
			return InlineVerify(c.Args().Slice()...)
		},
	},
	{
		Name:      "inline-detach",
		Usage:     "Split Signatures from an Inline-Signed Message",
		UsageText: "gosop inline-verify < INLINESIGNED",
		Flags: []cli.Flag{
			noArmorFlag,
			signaturesOutFlag,
		},
		Action: func(c *cli.Context) error {
			return InlineDetach()
		},
	},
	{
		Name:      "encrypt",
		Usage:     "Encrypt a Message",
		UsageText: "gosop encrypt [command options] [CERTS...] < DATA",
		Flags: []cli.Flag{
			selectedProfileFlag,
			asFlag,
			noArmorFlag,
			passwordFlag,
			signWithFlag,
			keyPasswordFlag,
		},
		Action: func(c *cli.Context) error {
			return Encrypt(c.Args().Slice()...)
		},
	},
	{
		Name:      "decrypt",
		Usage:     "Decrypt a Message",
		UsageText: "gosop decrypt [command options] [KEY...] < CIPHERTEXT",
		Flags: []cli.Flag{
			sessionKeyOutFlag,
			sessionKeyFlag,
			passwordFlag,
			verificationsOutFlag,
			verifyWithFlag,
			verifyNotBeforeFlag,
			verifyNotAfterFlag,
			keyPasswordFlag,
		},
		Action: func(c *cli.Context) error {
			return Decrypt(c.Args().Slice()...)
		},
	},
	{
		Name:      "armor",
		Usage:     "Add ASCII Armor",
		UsageText: "gosop armor [command options] < DATA",
		Action: func(c *cli.Context) error {
			return ArmorComm(c.Args().Slice()...)
		},
	},
	{
		Name:      "dearmor",
		Usage:     "Remove ASCII Armor",
		UsageText: "gosop dearmor < DATA",
		Action: func(c *cli.Context) error {
			return DearmorComm()
		},
	},
}

All commands defined by the CLI.

Functions

func ArmorComm

func ArmorComm(keyFilenames ...string) error

ArmorComm takes unarmored OpenPGP material from Std input and outputs the same material with ASCII-armoring added.

func DearmorComm

func DearmorComm() error

DearmorComm takes armored OpenPGP material from Std input and outputs the same material with ASCII-armoring removed.

func Decrypt

func Decrypt(keyFilenames ...string) error

Decrypt takes the data from stdin and decrypts it with the key file passed as argument, or a passphrase in a file passed with the --with-password flag. Note: Can't encrypt both symmetrically (passphrase) and keys. TODO: Multiple signers?

--session-key-out=file flag: Outputs session key byte stream to given file.

func Encrypt

func Encrypt(keyFilenames ...string) error

Encrypt takes the data from stdin and encrypts it with the keys passed as argument, or a passphrase passed with the --with-password flag. It signs with the given private keys. Note: Can't encrypt both symmetrically (passphrase) and keys.

func Err99

func Err99(cmd string, err error) error

Err99 returns the error message of any error not defined by the draft.

func ExtractCert

func ExtractCert() error

ExtractCert - Extract a Certificate from a Secret Key

func GenerateKey

func GenerateKey(userIDs ...string) error

GenerateKey creates a single default OpenPGP certificate with zero or more User IDs. Given that go-crypto expects name, comment, email parameters, we force the USERID of this implementation to be of the form "name (comment) <email>".

func InlineDetach

func InlineDetach() error

InlineDetach splits signatures from an inline-signed message.

func InlineSign

func InlineSign(keyFilenames ...string) error

InlineSign takes the data from stdin and signs it with the key passed as argument. TODO: Exactly one signature should be made by each supplied "KEY".

func InlineVerify

func InlineVerify(input ...string) error

InlineVerify checks the validity of a signed message against a set of certificates.

func ListProfiles

func ListProfiles(commands ...string) error

func Sign

func Sign(keyFilenames ...string) error

Sign takes the data from stdin and signs it with the key passed as argument. TODO: Exactly one signature will be made by each supplied "KEY".

func Verify

func Verify(input ...string) error

Verify checks the validity of a signature against a set of certificates.

func Version

func Version() error

Version prints version information about gosop, and/or the underlying OpenPGP library/libraries.