ghostpass

README

ghostpass

Privacy-First Secrets Management Cryptosystem

WARNING: this is experimental software and should not be used in production.

Introduction

Ghostpass is a command-line tool that helps symmetrically encrypt your secrets, and makes it feasible for plainsight distribution. It ensures that your secrets, whether in the form of authentication credentials or actual messages and documents, can appear in plainsight as normal cleartexts, and can be confidently transmitted even in a public medium with potential malicious actors, even those that may act out with coercion to exfiltrate and decrypt it.

Ghostpass is novel in the sense that it applies modern symmetric cryptography towards digital consumer privacy to mitigate rubber-hose cryptoanalysis. However, it should also be considered novelty because it is NOT a full replacement for current cryptographic software.

Use Cases

• Hide and encrypt sensitive and private information away before going into an area of surveillance (ie. airport, government building).
• Use plainsight distribution as a means to make cold storage of keys safer on a host or in transmission.
• Employ a provably secure "digital book cipher" as a medium of transmission with another party.

Usage

There is on-going support for Ghostpass across different mediums, including the web and chatops. However, Ghostpass can still be used locally through the command line.

Command Line

The Ghostpass command line application can be installed locally as follows:

$ go get -u github.com/ghostpass/ghostpass/cmd/ghostpass

Docker is also supported if you want to minimize exfiltration on a host:

$ docker build .

To use:

$ ghostpass help

Contributing

To create a new branch for contributions:

# new feature branch
$ git remote add upstream https://github.com/ghostpass/ghostpass
$ git checkout -b my-branch-name

# do code, do tests, etc
$ git add .
$ git commit -m "Useful commit message"

# push and make pull request
$ git push origin my-branch-name

License

MIT License

Documentation

Overview

Implements secret-key authentication encryption using LibNacl's Golang interface.

Implements the functionality for performing zero-width encoding and decoding given a corpus and information to hide within.

Provides the high level definition for the `Field` struct, which encapsulates and performs AEAD on secrets in order to return for storage back into the secret store mapping.

Implements helper routines useful for de/serialization for both the stationary and plainsight states in order to securely JSONify secret store state for storage.

Implements the secret-store that interfaces with the majority of functionality, including interacting with fields and notes (TODO), using cryptographic primitives, and implementing the plainsight importing and distribution.

Index

• Constants
• func BinToData(binstring string) []byte
• func BoxDecrypt(key []byte, ciphertext []byte) ([]byte, error)
• func BoxEncrypt(key []byte, plaintext []byte) ([]byte, error)
• func ContainsHiddenChars(corpus string) bool
• func DataToBin(s string) string
• func DecodeHiddenString(corpus string) []byte
• func EncodeHiddenString(plain string, secret string) string
• func MakeWorkspace() string
• func PathExists(path string) bool
• type Field
  • func NewField(key []byte, username string, pwd *memguard.Enclave) (*Field, error)
  • func ReconstructField(key []byte, compressed []byte) (*Field, error)
  • func (f *Field) AddDeniableSecret(username string, pwd *memguard.Enclave) error
  • func (f *Field) RederiveAuthPair(key []byte) error
• type SecretStore
  • func Import(pwd *memguard.Enclave, encoded string) (*SecretStore, error)
  • func InitStore(name string, pwd *memguard.Enclave) (*SecretStore, error)
  • func OpenStore(name string, pwd *memguard.Enclave) (*SecretStore, error)
  • func PlainsightUnmarshal(checksum [32]byte, encoded []byte) (*SecretStore, error)
  • func StationaryUnmarshal(checksum [32]byte, serialized []byte) (*SecretStore, error)
  • func (ss *SecretStore) AddDeniableField(service string, username string, pwd *memguard.Enclave) error
  • func (ss *SecretStore) AddField(service string, username string, pwd *memguard.Enclave) error
  • func (ss *SecretStore) CommitStore() error
  • func (ss *SecretStore) DestroyStore() error
  • func (ss *SecretStore) Export(corpus string) (string, error)
  • func (ss *SecretStore) FieldExists(service string) bool
  • func (ss *SecretStore) GetField(service string) ([]string, error)
  • func (ss *SecretStore) GetFields() []string
  • func (ss *SecretStore) PlainsightMarshal() ([]byte, error)
  • func (ss *SecretStore) RemoveField(service string) error

Constants

const (
	// ZWJ represents zero-width joiner.
	ZWJ = '\u200D'

	// ZWNJ representds zero-width non-joiner.
	ZWNJ = '\u200C'
)

const (
	// current protocol version
	Version int = 2.0

	// default configuration storage path for secret stores
	StoragePath string = ".ghostpass"

	// represents the state that the store is at where it's residing
	StoreStationary string = "Stationary"
	StorePlainsight string = "Plainsight"
)

Functions

func BinToData

func BinToData(binstring string) []byte

Helper function used to convert a binary string back into a byte array of data.

func BoxDecrypt

func BoxDecrypt(key []byte, ciphertext []byte) ([]byte, error)

Use symmetric authenticated encryption to decrypt a plaintext from a ciphertext given a ciphertext byte buffer.

func BoxEncrypt

func BoxEncrypt(key []byte, plaintext []byte) ([]byte, error)

Use symmetric authenticated encryption to generate a ciphertext given any plaintext byte buffer.

func ContainsHiddenChars

func ContainsHiddenChars(corpus string) bool

Checks to see if a given corpus file contains zero-width characters already

func DataToBin

func DataToBin(s string) string

Helper function for converting a string of ASCII characters into a binary string.

func DecodeHiddenString

func DecodeHiddenString(corpus string) []byte

given a corpus string with encoded zero-width characters, find them and strip them back into a compressed form.

func EncodeHiddenString

func EncodeHiddenString(plain string, secret string) string

Given a plaintext string corpus and a secret to hide, encode it with zero-width characters by converting serialized input into bitstring, which is then encoded to the plaintext to hide in.

func MakeWorkspace

func MakeWorkspace() string

Helper routine to construct path to a ghostpaworkspace for storage if not found in filesystem, and returns name

func PathExists

func PathExists(path string) bool

Helper routine to check if a given path exists.

Types

type Field

type Field struct {

	// auth credentials are securely stored for fast retrieval in memory when deserialized, but
	// will never show up in persistent storage for security.
	Username *memguard.Enclave `json:"-"`
	Pwd      *memguard.Enclave `json:"-"`

	// encrypted secret of auth combo is persistently stored, and used to recover the pair
	// once deserialized back to memory securely.
	AuthPair []byte `json:"authpair"`

	// stores n number of deniable authpairs that can revealed from a generated key
	DeniablePairs [][]byte `json:"-"`
}

Represents a strongly typed field, a struct that encapsulates a secret attribute that represents an encrypted username and password combination. Given a deniable combo pair, the secret can be mutated through a one-time pad and a deniable key can be derived for plausible deniability

func NewField

func NewField(key []byte, username string, pwd *memguard.Enclave) (*Field, error)

Given a key, service key and auth combination, create a completely new field that is encrypted.

func ReconstructField

func ReconstructField(key []byte, compressed []byte) (*Field, error)

Given a compressed secret, reconstruct a `Field` by decrypting it with a symmetric key, and re-deriving the username and password securely from them. This is used if the store being deserialized is from a plainsight state, where no field structure is JSONified and needs to be reconstructed completely.

func (*Field) AddDeniableSecret

func (f *Field) AddDeniableSecret(username string, pwd *memguard.Enclave) error

Given a bogus and deniable auth combo, generate a secret like with the original pair and store it for deniable key generation later. (TODO)

func (*Field) RederiveAuthPair

func (f *Field) RederiveAuthPair(key []byte) error

Given a partially initialized Field, like one being deserialized from a stationary store, rederive the user and encrypted password for retrieval by a user in-memory.

type SecretStore

type SecretStore struct {

	// ghostpaprotocol version
	Version int `json:"version"`

	// represents the state of the store. when exported, it will swap to Plainsight
	StoreState string `json:"state"`

	// name identifier for the secret store
	Name string `json:"name"`

	// represents a hashed and secured key for symmetric encryption
	SymmetricKey []byte `json:"-"`

	// internal state of the store with all the available secrets
	Fields map[string]*Field `json:"fields"`
}

Defines a serializable `SecretStore`, which can be instantiated to securely hold secrets in the form of `Field`s, and exported for plainsight distribution.

func Import

func Import(pwd *memguard.Enclave, encoded string) (*SecretStore, error)

Given an imported compressed corpus, extract and decrypt it with a symmetric key, and attempt to reinitialize the state it represented when marshalled.

func InitStore

func InitStore(name string, pwd *memguard.Enclave) (*SecretStore, error)

Initializes a new `SecretStore` given a name and master symmetric key that is secured. Will create a new store if name does not exist, otherwise will read and return the existing one.

func OpenStore

func OpenStore(name string, pwd *memguard.Enclave) (*SecretStore, error)

Opens an existing `SecretStore` for interaction by the user. Will error if does not exist or cannot properly read and deserialize the contents of the persistent database.

func PlainsightUnmarshal

func PlainsightUnmarshal(checksum [32]byte, encoded []byte) (*SecretStore, error)

Helper routine that prepares a secret store from an exported plainsight distribution. Since the state stored on disk does not contain any remnants of the auth credentials per field, this unmarshaller rederives that using the given symmetric key.

func StationaryUnmarshal

func StationaryUnmarshal(checksum [32]byte, serialized []byte) (*SecretStore, error)

Helper function that converts a stationary persistent store back into a `SecretStore` for interaction. Putting the store in stationary mode preserves more state than plainsight mode, so not much decryption is needed.

func (*SecretStore) AddDeniableField

func (ss *SecretStore) AddDeniableField(service string, username string, pwd *memguard.Enclave) error

Given an existing field, attempt to encrypt a deniable credential pair, an derive a "deniability" key for plausible deniability. (TODO)

func (*SecretStore) AddField

func (ss *SecretStore) AddField(service string, username string, pwd *memguard.Enclave) error

Add a new field to the secret store, given a service as key, and a credential pair for encryption and storage. Will overwrite if already exists.

func (*SecretStore) CommitStore

func (ss *SecretStore) CommitStore() error

Commits any changes made to the current state of the existing `SecretStore` back to the file-based database to ensure that operations all persist.

func (*SecretStore) DestroyStore

func (ss *SecretStore) DestroyStore() error

Nukes the entire state of a given secret store, deleting all traces of it in-memory and the path to the file-based database.

func (*SecretStore) Export

func (ss *SecretStore) Export(corpus string) (string, error)

Given a corpus to hide in, take the current state of the secret store, and export a version of it hidden within the corpus through zero-width encoding

func (*SecretStore) FieldExists

func (ss *SecretStore) FieldExists(service string) bool

Helper routine used to check if a field with a specific service already exists.

func (*SecretStore) GetField

func (ss *SecretStore) GetField(service string) ([]string, error)

Given a service name as the key, reveal the contents safely for the given entry.

func (*SecretStore) GetFields

func (ss *SecretStore) GetFields() []string

Return a slice of all available services in the secret store.

func (*SecretStore) PlainsightMarshal

func (ss *SecretStore) PlainsightMarshal() ([]byte, error)

Helper routine that helps prepare a secret store to be plainsight distributable, by incorporating indistinguishability to all entries, stripping the symmetric key checksum, compressing the final store, and applying one-time pads for deniability (TODO).

func (*SecretStore) RemoveField

func (ss *SecretStore) RemoveField(service string) error

Given a service name as the key, delete an entry corresponding to it in the secret store.