stronghold

README

Stronghold

[!IMPORTANT] Use only if you know what you are doing. I'm not responsible for any security issues you could be exposed if you use this library.

This is a toy I created, based on Facebook Onion PRF, I tried to extract the interesting ideas, and the mitigations in-place to build a modern password hash system.

[!IMPORTANT] Use at your own risk

Documentation

Overview

Package stronghold provides a secure way to store and verify secrets.

The package provides a way to store a secret in a secure way. The secret is stored as a hash and can be verified later. The package uses a key derivation function to derive a key from the secret and a salt. The key is used to encrypt the secret using an authenticated encryption with associated data (AEAD) scheme. The encrypted secret is then hashed using a remote hardware security module (HSM).

This is inspirred by the Facebook Onion PRF service.

Index

• Variables
• type AEAD
• type Hash
  • func (s *Hash) Seal(ctx context.Context, secret, aad []byte) ([]byte, error)
  • func (s *Hash) Verify(ctx context.Context, secret, storedHash, aad []byte) error
• type KDF

Variables

var (
	// ErrEmptySecret is returned when the secret is empty.
	ErrEmptySecret = errors.New("empty secret")
	// ErrSecretTooLong is returned when the secret is too long.
	ErrSecretTooLong = errors.New("secret too long")
	// ErrAADTooLong is returned when the additional data is too long.
	ErrAADTooLong = errors.New("aad too long")
	// ErrStoredHashTooShort is returned when the stored hash is too short.
	ErrStoredHashTooShort = errors.New("stored hash too short")
	// ErrContextMismatch is returned when the context does not match the stored context.
	ErrContextMismatch = errors.New("context mismatch")
	// ErrHashMismatch is returned when the hash does not match the stored hash.
	ErrHashMismatch = errors.New("hash mismatch")
)

Types

type AEAD

type AEAD uint8

AEAD is the authenticated encryption with associated data type.

const (
	// AESGCM is the authenticated encryption with associated data.
	AESGCM AEAD = iota
	// CHACHAPOLY is the authenticated encryption with associated data.
	CHACHAPOLY
)

type Hash

type Hash struct {
	// Remote is the remote HSM.
	RemoteHashFunc func(context.Context, []byte) ([]byte, error)
	// KeyDerivation is the key derivation function.
	KeyDerivation KDF
	// Encryption is the authenticated encryption with associated data.
	Encryption AEAD
}

Hash is a hash implementation that uses a remote HSM to hash the password.

func (*Hash) Seal

func (s *Hash) Seal(ctx context.Context, secret, aad []byte) ([]byte, error)

Seal hashes the secret and seals the context with the provided additional data. It returns the sealed context.

The AAD is the additional data that is used to seal the context. Consider to use a canonical representation of the context to prevent mismatches. The result is expected to be in the format SALT || ENCRYPTED_HASH.

func (*Hash) Verify

func (s *Hash) Verify(ctx context.Context, secret, storedHash, aad []byte) error

Verify verifies the secret against the stored hash and additional data. It returns nil if the secret matches the stored hash, ErrHashMismatch if the hash does not match, or ErrContextMismatch if the context does not match the stored context.

The stored hash is expected to be in the format SALT || ENCRYPTED_HASH. AAD is the additional data that was used to seal the context. Consider to use a canonical representation of the context to prevent mismatches.

type KDF

type KDF uint8

KDF is the key derivation function type.

const (
	// SCRYPT is the key derivation function.
	SCRYPT KDF = iota
	// PBKDF2 is the key derivation function.
	PBKDF2
	// ARGON2ID is the key derivation function.
	ARGON2ID
)