password

README

Password Package

Passwords: as simple as it gets.

• Password Package
  • Usage
    • Importing
    • Hashing Passwords
    • Verifying Passwords
    • Validating Passwords
    • Customizing Password Policies
  • Development Runbook
    • Getting Started
    • Continuous Integration (CI) Pipeline
  • Licensing

Usage

Importing

import "github.com/usvc/password"

Hashing Passwords

plaintext := "abcd1234!@#$"
hash, salt, err := password.Hash(plaintext)
// ...
// store the hash and salt
// ...

Verifying Passwords

storedHash := "<hash>"
storedSalt := "<salt>"
plaintext := "abcd1234!@#$"
err := password.Verify(plaintext, storedHash, storedSalt)
if err != nil {
  // handle failed verification
} else {
  // handle successful verification
}

Validating Passwords

defaultPolicy := password.GetDefaultPolicy()
plaintext := "abcd1234!@#$"
if err := password.Validate(plaintext, defaultPolicy); err != nil {
  // handle failed validation
} else {
  // handle successful validation
}

Customizing Password Policies

customPolicy := password.Policy{
  MaximumLength: 32,
  MinimumLength: 12,
  MinimumLowercaseCount: 1,
  MinimumUppercaseCount: 1,
  MinimumNumericCount: 1,
  MinimumSpecialCount: 1,
  CustomSpecial: []byte("`!@"),
}
plaintext := "abcd1234!@#$"
if err := password.Validate(plaintext, defaultPolicy); err != nil {
  // handle failed validation
} else {
  // handle successful validation
}

Development Runbook

Getting Started

1. Clone this repository
2. Run make deps to pull in external dependencies
3. Write some awesome stuff
4. Run make test to ensure unit tests are passing
5. Push

Continuous Integration (CI) Pipeline

To set up the CI pipeline in Gitlab:

1. Run make .ssh
2. Copy the contents of the file generated at ./.ssh/id_rsa.base64 into an environment variable named DEPLOY_KEY in Settings > CI/CD > Variables
3. Navigate to the Deploy Keys section of the Settings > Repository > Deploy Keys and paste in the contents of the file generated at ./.ssh/id_rsa.pub with the Write access allowed checkbox enabled

• DEPLOY_KEY: generate this by running make .ssh and copying the contents of the file generated at ./.ssh/id_rsa.base64

Licensing

Code in this package is licensed under the MIT license (click to view text).

Documentation

Index

• Constants
• func Hash(plaintext string) (string, string, error)
• func Validate(plaintext string, customPolicy ...Policy) error
• func Verify(plaintext string, encodedHash string, encodedSalt string) error
• type Policy
  • func GetDefaultPolicy() Policy
• type StringMetadata
  • func GetStringMetadata(plaintext string, customSpecial ...[]byte) StringMetadata

Constants

const (
	// LowercaseCharacters defines lowercase characters
	LowercaseCharacters = "abcdefghijklmnopqrstuvwxyz"

	// NumericCharacters defines numerical characters
	NumericCharacters = "1234567890"

	// SpecialCharacters defines special characters
	SpecialCharacters = "~`!@#$%^&*()_-=+[{]}\\|;:'\"<>./?"

	// UppercaseCharacters defines uppercase characters
	UppercaseCharacters = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
)

const (
	// DefaultPasswordCustomSpecial defines the default character set
	// that is used to define special characters
	DefaultPasswordCustomSpecial string = SpecialCharacters

	// DefaultPasswordMinimumLowercaseCount defines the default for
	// the number of lower-cased characters required
	DefaultPasswordMinimumLowercaseCount int = 0

	// DefaultPasswordMinimumUppercaseCount defines the default for
	// the number of upper-cased characters required
	DefaultPasswordMinimumUppercaseCount int = 0

	// DefaultPasswordMaximumLength defines the default for the length
	// of the password
	DefaultPasswordMaximumLength int = 64

	// DefaultPasswordMinimumLength defines the default for the minimum
	// length of the password
	DefaultPasswordMinimumLength int = 8

	// DefaultPasswordMinimumNumericCount defines the default
	// number of numeric characters in the password
	DefaultPasswordMinimumNumericCount int = 0

	// DefaultPasswordMinimumSpecialCount defines the default
	// number of special characters in the password
	DefaultPasswordMinimumSpecialCount int = 0
)

const (
	// StringTypeNumeric defines a numeric character type
	StringTypeNumeric = "NUMERIC"
	// StringTypeSpecial defines a special character type
	StringTypeSpecial = "SPECIAL"
	// StringTypeLowercase defines a lowercase character type
	StringTypeLowercase = "LOWERCASE"
	// StringTypeUppercase defines a uppercase character type
	StringTypeUppercase = "UPPERCASE"
	// StringTypeUnknown defines an unknown character type
	StringTypeUnknown = "UNKNOWN"
)

const VariableArgon2RequiredMemory uint64 = 64 * 1024

VariableArgon2RequiredMemory defines the recommended memory in bytes to use to generate an Argon2id hashed password

const VariableMemoryTolerance float64 = 0.5

VariableMemoryTolerance defines the maximum amount of the available heap to use for hashing passwords

Functions

func Hash

func Hash(plaintext string) (string, string, error)

Hash hashes and salts the given plaintext string and returns the result as a base64-encoded hash and salt

func Validate

func Validate(plaintext string, customPolicy ...Policy) error

Validate validates a provided plaintext password using the default PasswordPolicy or a custom policy if it's provided

func Verify

func Verify(plaintext string, encodedHash string, encodedSalt string) error

Verify verifies a provided plaintext string matches the provided base64-encoded hash and salt

Types

type Policy

type Policy struct {
	MaximumLength         int
	MinimumLength         int
	MinimumLowercaseCount int
	MinimumUppercaseCount int
	MinimumNumericCount   int
	MinimumSpecialCount   int
	CustomSpecial         []byte
}

Policy defines possible configurations for password requirements

func GetDefaultPolicy

func GetDefaultPolicy() Policy

GetDefaultPolicy returns a Policy with its values set to the default

type StringMetadata

type StringMetadata struct {
	Length     int
	Lowercases strings.Builder
	Uppercases strings.Builder
	Numerics   strings.Builder
	Specials   strings.Builder
	Unknowns   strings.Builder
	PrefixType string
	SuffixType string
}

StringMetadata provides metadata about a string, use GetStringMetadata to generate the metadata

func GetStringMetadata

func GetStringMetadata(plaintext string, customSpecial ...[]byte) StringMetadata

GetStringMetadata returns a populated StringMetadata structure that provides meta-data about the provided plaintext string for further processing by validators