ghostpass

package module
v0.0.0-...-11d4369 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 29, 2020 License: MIT Imports: 15 Imported by: 0

README

ghostpass

Privacy-First Secrets Management Cryptosystem

Project Roadmap

This is still on-going and a work-in-progress.

  • Plainsight Distribution
  • Plausible deniability

Introduction

Ghostpass is a secrets management cryptography scheme that can hide encrypted secrets in cleartext for the purpose of distribution across public mediums. 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 through the use of textual steganography and plausible deniability. However, it should also be considered novelty because it is NOT a full replacement for current cryptographic software, but an ongoing effort to bridge together cryptography and privacy research. I encourage users to criticize, audit and expose shortcomings in order to better understand how these types of implementations can better be harnessed in the space of digital privacy.

There's quite a bit of password/secrets managers that are out there today, so why even bother with Ghostpass? In order to answer this question, let's take a look at different password managers "models" that already exist, and the problems that plague them:

  • Web-based clients are centralized, and data breaches are possible since they are central points of failure.
  • Offline clients ( i.e KeePass) don't enable for fast distribution across hosts and portability. They share a unified filetype that require compliant client implementations to work

Ghostpass's implementation aims to create a compromise that doesn't require the authority of a password management service, but can still enable portability for users across whatever mediums they choose.

Design

Features

  • Secure - all fields in secret stores are properly protected in-memory and on-disk, such that attackers with even priviledged access to the host can't recover anything.
  • Cryptographically Secure - information is secured and validated with secret-key authentication encryption scheme XSalsa20-Poly1305.
  • Privacy-Centric - supports "plainsight distribution" using zero-width encoding to hide ciphertext within plaintext, and plausible deniability (TODO) to give back fake entries under an assumption of coercion.

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 and in transmission.
  • Employ a provably secure "digital book cipher" as a medium of transmission with another party.
Who Can Use Ghostpass?
  • Journalists - hide secrets amongst corpuses of actual documents, and use plausible deniability to return bogus articles if ever interrogated
  • Lawyers - protect confidentiality of clients and sensitive anecdotes before trial by encrypting them amongst fake ones.
  • You, a Privacy-Conscious Digital Consumer

Usage

Build

The Ghostpacommand-line application and library package can be installed to your host with the following:

$ go get github.com/ex0dus-0x/ghostpass/

To use:

$ ghostpass help

However, to minimize the exfiltration of information from the user from a misuser, we recommend the usage of a Docker container:

$ docker build .

Contributing

To create a new branch for contributions:

# new feature branch
$ git remote add upstream https://github.com/ex0dus-0x/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

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.

Index

Constants

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

	// ZWNJ representds zero-width non-joiner.
	ZWNJ = '\u200C'
)
View Source
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"
)

Variables

This section is empty.

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.

Directories

Path Synopsis
cmd

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL