gopass

README

Gopass

gopass is a Go package that provides utilities for password security, generation, validation, hashing, comparison, and OTP (One-Time Password) generation.

Features

• Password Generation – Generates a secure random password with customizable options.
• Password Validation – Ensures password strength by checking length, character requirements, and common usage.
• Check for Commonly Used Passwords – Checks if a password is part of the 10k most commonly used passwords.
• Secure Hashing – Hash passwords securely using the bcrypt algorithm.
• Password Comparison – Compares bcrypt-hashed passwords with plaintext.
• OTP Generation – Creates numeric one-time passwords of configurable lengths.

Installation

To install gopass, run:

 go get github.com/cradoe/gopass

Usage

Password Generation

Generate password with default options:

package main

import (
	"fmt"
	"github.com/cradoe/gopass"
)

func main() {
	password, err := gopass.GeneratePassword()
	if err != nil {
		fmt.Println("Error generating password:", err)
		return
	}

	fmt.Println("Generated Password:", password)
}

Custom Password Generation

You can customize the generated password by specifying options such as length, inclusion of uppercase letters, numbers, and symbols.

package main

import (
	"fmt"
	"github.com/cradoe/gopass"
)

func main() {
	password, err := gopass.GeneratePassword(gopass.GeneratePasswordOptions{
		Length:         16,
		IncludeUpper:   true,
		IncludeLower:   true,
		IncludeNumbers: true,
		IncludeSymbols: false,
	})
	if err != nil {
		fmt.Println("Error generating password:", err)
		return
	}

	fmt.Println("Custom Password:", password)
}

Password Validation

Ensure password is strong and meets security requirements:

package main

import (
	"fmt"
	"github.com/cradoe/gopass"
)

func main() {
	valid, errors := gopass.Validate("SecurePass123!")
	if valid {
		fmt.Println("Password is strong!")
	} else {
		fmt.Println("Password issues:")
		for _, err := range errors {
			fmt.Println("-", err)
		}
	}
}

Is common

Check if the given password is part of the 10k most used passwords:

package main

import (
	"fmt"
	"github.com/cradoe/gopass"
)

func main() {
	common := gopass.IsCommon("football")
	if common {
		fmt.Println("Password is too common")
		return
	}
}

Password Hashing and Comparison

Securely hash and verify passwords using Bcrypt hash algorithm:

package main

import (
	"fmt"
	"github.com/cradoe/gopass"
)

func main() {
	password := "SecurePass123!"
	hashedPassword, err := gopass.Hash(password)
	if err != nil {
		fmt.Println("Error hashing password:", err)
		return
	}

	fmt.Println("Hashed Password:", hashedPassword)

	match, err := gopass.ComparePasswordAndHash(password, hashedPassword)
	if err != nil {
		fmt.Println("Error comparing password:", err)
		return
	}

	if match {
		fmt.Println("Password matches!")
	} else {
		fmt.Println("Invalid password!")
	}
}

Generating One-Time Passwords (OTPs)

Generate a numeric OTP:

package main

import (
	"fmt"
	"github.com/cradoe/gopass"
)

func main() {
	otp, err := gopass.GenerateOTP(6) // using 6 as the length of the OTP
	if err != nil {
		fmt.Println("Error generating OTP:", err)
		return
	}
	fmt.Println("Generated OTP:", otp)
}

Errors and Limitations

gopass enforces security by rejecting:

• Passwords shorter than 8 characters or longer than 72 characters.
• Passwords missing uppercase, lowercase, numeric, or special characters.
• Commonly used passwords (from a predefined list).
• OTP lengths shorter than 4 digits.

Roadmap

• Support for additional hashing algorithms (e.g., Argon2, PBKDF2).
• Configurable password policies.

License

This project is licensed under the MIT License. See LICENSE for details.

Contributions

Contributions are welcome! Feel free to open issues or submit pull requests on GitHub.

Documentation

Index

• Variables
• func BcryptCost(hashedPassword string) (cost int, err error)
• func CompareBcryptPasswordAndHash(plaintextPassword, hashedPassword string) (match bool, err error)
• func ComparePasswordAndHash(plaintextPassword, hashedPassword string) (match bool, err error)
• func GenerateOTP(length int) (string, error)
• func GeneratePassword(params ...GeneratePasswordOptions) (string, error)
• func Hash(plaintextPassword string, cost ...int) (string, error)
• func HashWithBcrypt(plaintextPassword string, cost ...int) (string, error)
• func IsCommon(value string) bool
• func Validate(value string) (bool, []string)
• type GeneratePasswordOptions

Variables

var (
	// ErrEmptyPassword is returned by Hash* if the provided
	// plaintextPassword is ""
	ErrEmptyPassword = errors.New("password cannot be empty")

	// ErrPasswordTooShort is returned by Validate if the provided
	// password is less than 8 characters
	ErrPasswordTooShort = errors.New("password must be at least 8 characters long")

	// ErrPasswordTooLong is returned by Validate and Hash* functions if the provided
	// password is more than 72 characters
	ErrPasswordTooLong = errors.New("password length exceeds 72 characters")

	// ErrPasswordShouldHaveUppercase is returned by Validate if the provided
	// password does not have an uppercase letter
	ErrPasswordShouldHaveUppercase = errors.New("password must contain at least one uppercase letter")

	// ErrPasswordShouldHaveUppercase is returned by Validate if the provided
	// password does not have an uppercase letter
	ErrPasswordShouldHaveLowercase = errors.New("password must contain at least one lowercase letter")

	// ErrPasswordShouldHaveDigit is returned by Validate if the provided
	// password does not have a digit letter
	ErrPasswordShouldHaveDigit = errors.New("password must contain at least one number")

	// ErrPasswordShouldHaveSpecialChar is returned by Validate if the provided
	// password does not have a special character
	ErrPasswordShouldHaveSpecialChar = errors.New("password must contain at least one special character")

	// ErrPasswordTooCommon is returned by Validate if the provided
	// password is passed to IsCommon, which then returns true
	ErrPasswordTooCommon = errors.New("password is too common, please choose a stronger one")

	// ErrInvalidOTPLength is returned by GenerateOTP if the provided
	// length is less than 4
	ErrInvalidOTPLength = errors.New("OTP length must be at least 4 digits")
)

var CommonPasswords = []string{}/* 10000 elements not displayed */

CommonPasswords list is from https://github.com/danielmiessler/SecLists/blob/master/Passwords/Common-Credentials/10k-most-common.txt

Functions

func BcryptCost

func BcryptCost(hashedPassword string) (cost int, err error)

BcryptCost gets the bcrypt cost factor from a hashed password. Returns the cost factor or an error if the extraction fails.

func CompareBcryptPasswordAndHash

func CompareBcryptPasswordAndHash(plaintextPassword, hashedPassword string) (match bool, err error)

CompareBcryptPasswordAndHash compares a plaintext password with a bcrypt hash. Returns true if they match, false if they don't, and an error if something goes wrong.

func ComparePasswordAndHash

func ComparePasswordAndHash(plaintextPassword, hashedPassword string) (match bool, err error)

ComparePasswordAndHash verifies a plaintext password against a hashed password. It uses Bcrypt as default Returns true if they match, false otherwise.

func GenerateOTP

func GenerateOTP(length int) (string, error)

GenerateOTP generates a one-time password (OTP) of the specified length. The OTP consists only of numeric digits (0-9).

Returns the generated OTP as a string or an error if the length is invalid.

func GeneratePassword

func GeneratePassword(params ...GeneratePasswordOptions) (string, error)

GeneratePassword randomly generates a secure password, It has options for customizing it's behavior, option is used when custom isn't given

Returns the generated password as a string or an error if there's any

func Hash

func Hash(plaintextPassword string, cost ...int) (string, error)

Hash securely hashes a plaintext password, It uses Bcrypt by default

func HashWithBcrypt

func HashWithBcrypt(plaintextPassword string, cost ...int) (string, error)

HashWithBcrypt hashes a password using bcrypt it ensures the password is not empty and not more than 72 characters. There is an optional parameter for specifying the cost

func IsCommon

func IsCommon(value string) bool

IsCommon checks if the provided password is present in a list of 10k commonly used passwords see https://github.com/danielmiessler/SecLists/blob/master/Passwords/Common-Credentials/10k-most-common.txt

func Validate

func Validate(value string) (bool, []string)

Validate checks the strength of a password based on the following criteria: - Minimum length of 8 characters - Maximum length of 72 characters (bcrypt limitation) - At least one uppercase letter - At least one lowercase letter - At least one number - At least one special character - Is not common password

It returns a boolean indicating validity and a slice of strings describing any issues.

Types

type GeneratePasswordOptions

type GeneratePasswordOptions struct {
	Length         int
	IncludeUpper   bool
	IncludeLower   bool
	IncludeNumbers bool
	IncludeSymbols bool
}