crypt

README

github.com/go-crypt/crypt

Password Hashing / Digest / Crypt library.

Intent

This library aims to provide a convenient layer over the go password hashing crypto functions.

Tasks

A list of tasks that need to be accomplished are listed in the
General Project.

Algorithms

Supported

Algorithm	Variants	Identifiers
Argon2	Argon2id, Argon2i, Argon2d	argon2id, argon2i, argon2d
SHA-crypt	SHA256, SHA512	5, 6
PBKDF2	SHA1, SHA224, SHA256, SHA384, SHA512	pbkdf2, pbkdf2-sha1, pbkdf2-sha224, pbkdf2-sha256, pbkdf2-sha384, pbkdf2-sha512
bcrypt	bcrypt, bcrypt-sha256	2, 2a, 2b, 2x, 2y, bcrypt-sha256
scrypt	scrypt	scrypt
md5crypt	standard, sun	1, md5
sha1crypt	standard	sha1
PlainText	plaintext, base64	plaintext, base64

Plain Text Format

In addition to the standard crypt functions we also support a plain text storage format which has a regular plain text variant and a Base64 format (for storage, not security).

The PHC string format we decided to use is as follows:

$<id>$<data>

Where id is either plaintext or base64, and data is either the password string or the Base64 (Adapted) encoded string.

bcrypt-sha256

This algorithm was thought of by the developers of Passlib. It circumvents the issue in bcrypt where the maximum password length is effectively 72 bytes by passing the password via a HMAC-SHA-256 function which uses the salt bytes as the key.

Note: Only bcrypt-sha256 version 2 which uses the PHC string format and passes the password through a HMAC-SHA-256 function the salt as the key is supported. The bcrypt-sha256 version 1 which uses the Modular Crypt Format and only passes the password via a SHA-256 sum function not supported at all.

Possible Future Support

Algorithm	Reasoning
Type 7 (cisco)	Explicit Backwards Compatibility and Interoperability
Type 8 (cisco)	Explicit Backwards Compatibility and Interoperability
Type 9 (cisco)	Explicit Backwards Compatibility and Interoperability
Type 10 (cisco)	Explicit Backwards Compatibility and Interoperability
LDAP RFC2307	Explicit Backwards Compatibility and Interoperability

Additional support for LDAP specific formats is also very likely, either via normalization and encoding options or via explicit algorithm variants and/or specific algorithms.

Base64 (Adapted)

Many password storage formats use Base64 with an Adapted charset to store the bytes of the salt or hash key. This uses the standard Base64 encoding without padding as per RFC4648 section 4 but replaces the + chars with a ..

Installation

Use go get to add this module to your project with go get github.com/go-crypt/crypt.

Requirements

• go 1.21+

Usage

The following examples show how easy it is to interact with the argon2 algorithm. Most other algorithm implementations are relatively similar.

Functional Options Pattern

The algorithm.Hasher implementations use a functional options pattern. This pattern is accessible via the New function in each algorithm package or via a receiver function of the individual algorithm.Hasher implementation called WithOptions.

Most algorithm implementations have at least the following functional option signatures:

• WithVariant(variant Variant) Opt
• WithVariantName(identifier string) Opt
• WithIterations(iterations int) Opt

With the exception of WithVariantName which takes a string, and WithVariant which takes a Variant type (which is technically a int), nearly every functional option takes a single int. There are a few functional options which take a single uint32 where the maximum value exceeds the maximum value for an untyped int on 32bit architectures.

If the uint32 methods are an issue for anyone using this module we suggest opening an issue and describing why and we'll consider adding another functional option which takes an int.

Creating a Decoder

While several convenience functions exist for building password decoders and checking individual passwords it is STRONGLY RECOMMENDED that users implementing this library explicitly create a decoder that fits their particular use case after sufficiently researching each algorithm and their benefits. At the time of this writing we strongly recommend the argon2id variant of argon2.

This can be done via the crypt.NewDecoder function as shown below.

package main

import (
    "fmt"

    "github.com/go-crypt/crypt"
    "github.com/go-crypt/crypt/algorithm"
    "github.com/go-crypt/crypt/algorithm/argon2"
)

func main() {
    var (
        decoder *crypt.Decoder
        err    error
        digest algorithm.Digest
    )
    
    if decoder, err = NewDecoderArgon2idOnly(); err != nil {
        panic(err)
    }
    
    if digest, err = decoder.Decode("$argon2id$v=19$m=2097152,t=1,p=4$BjVeoTI4ntTQc0WkFQdLWg$OAUnkkyx5STI0Ixl+OSpv4JnI6J1TYWKuCuvIbUGHTY"); err != nil {
        panic(err)
    }

    fmt.Printf("Digest Matches Password 'example': %t\n", digest.Match("example"))
    fmt.Printf("Digest Matches Password 'invalid': %t\n", digest.Match("invalid"))
}


// NewDecoderArgon2idOnly returns a decoder which can only decode argon2id encoded digests.
func NewDecoderArgon2idOnly() (decoder *crypt.Decoder, err error) {
    decoder = crypt.NewDecoder()

    if err = argon2.RegisterDecoderArgon2id(decoder); err != nil {
        return nil, err
    }
    
    return decoder, nil
}

Decoding a Password and Validating It

This method of checking passwords is recommended if you have a database of hashes which are going to live in memory. The crypt.Digest and crypt.NullDigest types provide helpful interface implementations to simplify Marshal/Unmarshal and database operations.

package main

import (
    "fmt"

    "github.com/go-crypt/crypt"
    "github.com/go-crypt/crypt/algorithm"
)

func main() {
    var (
        decoder *crypt.Decoder
        err error
        digest algorithm.Digest
    )
    
    if decoder, err = crypt.NewDefaultDecoder(); err != nil {
        panic(err)
    }
    
    if digest, err = decoder.Decode("$argon2id$v=19$m=2097152,t=1,p=4$BjVeoTI4ntTQc0WkFQdLWg$OAUnkkyx5STI0Ixl+OSpv4JnI6J1TYWKuCuvIbUGHTY"); err != nil {
        panic(err)
    }
    
    fmt.Printf("Digest Matches Password 'example': %t\n", digest.Match("example"))
    fmt.Printf("Digest Matches Password 'invalid': %t\n", digest.Match("invalid"))
}

Checking a Password Against a Hash

This method of checking passwords is quick and dirty and most useful when users are providing the hash as the input such as in situations where you are allowing them to check a password themselves via a CLI or otherwise.

package main

import (
    "fmt"

    "github.com/go-crypt/crypt"
)

func main() {
    var (
        valid bool
        err error
    )
    
    if valid, err = crypt.CheckPassword("example","$argon2id$v=19$m=2097152,t=1,p=4$BjVeoTI4ntTQc0WkFQdLWg$OAUnkkyx5STI0Ixl+OSpv4JnI6J1TYWKuCuvIbUGHTY"); err != nil {
        panic(err)
    }
    
    fmt.Printf("Digest Matches Password 'example': %t\n", valid)

    if valid, err = crypt.CheckPassword("invalid","$argon2id$v=19$m=2097152,t=1,p=4$BjVeoTI4ntTQc0WkFQdLWg$OAUnkkyx5STI0Ixl+OSpv4JnI6J1TYWKuCuvIbUGHTY"); err != nil {
        panic(err)
    }

    fmt.Printf("Digest Matches Password 'invalid': %t\n", valid)
}

Generating an Encoded Digest from a Password

package main

import (
    "fmt"

    "github.com/go-crypt/crypt/algorithm"
    "github.com/go-crypt/crypt/algorithm/argon2"
)

func main() {
    var (
        hasher *argon2.Hasher
        err error
        digest algorithm.Digest
    )
    
    if hasher, err = argon2.New(
        argon2.WithProfileRFC9106LowMemory(),
    ); err != nil {
        panic(err)
    }

    if digest, err = hasher.Hash("example"); err != nil {
        panic(err)
    }
    
    fmt.Printf("Encoded Digest With Password 'example': %s\n", digest.Encode())
}

Documentation

Overview

Package crypt provides helpful abstractions for github.com/go-crypt/x. These abstractions allow generating password hashes, encoding them in a common storage format, and comparing them to ensure they are valid.

It's recommended that you either use crypt.NewDefaultDecoder for decoding existing encoded digests into the algorithm.Digest. The Match function on the algorithm.Digest as well as the other methods described by algorithm.Matcher can be utilized to validate passwords.

The algorithm.Digest implementations include an Encode method which encodes the algorithm.Digest in the PHC String Format.

To create new algorithm.Digest results you can utilize the algorithm.Hash implementations which exist for each algorithm. The implementations utilize the functional options pattern where all options methods have the pattern With* or Without*.

Index

• Constants
• func CheckPassword(password, encodedDigest string) (valid bool, err error)
• func CheckPasswordWithPlainText(password, encodedDigest string) (valid bool, err error)
• func Decode(encodedDigest string) (digest algorithm.Digest, err error)
• func Normalize(encodedDigest string) string
• type Decoder
  • func NewDecoder() *Decoder
  • func NewDecoderAll() (d *Decoder, err error)
  • func NewDefaultDecoder() (d *Decoder, err error)
  • func (d *Decoder) Decode(encodedDigest string) (digest algorithm.Digest, err error)
  • func (d *Decoder) RegisterDecodeFunc(identifier string, decoder algorithm.DecodeFunc) (err error)
  • func (d *Decoder) RegisterDecodePrefix(prefix, identifier string) (err error)
• type Digest
  • func NewDigest(d algorithm.Digest) (digest *Digest, err error)
  • func NewDigestDecode(encodedDigest string) (digest *Digest, err error)
  • func (d *Digest) Encode() string
  • func (d *Digest) MarshalBinary() (data []byte, err error)
  • func (d *Digest) MarshalText() (data []byte, err error)
  • func (d *Digest) Match(password string) (match bool)
  • func (d *Digest) MatchAdvanced(password string) (match bool, err error)
  • func (d *Digest) MatchBytes(passwordBytes []byte) (match bool)
  • func (d *Digest) MatchBytesAdvanced(passwordBytes []byte) (match bool, err error)
  • func (d *Digest) Scan(src any) (err error)
  • func (d *Digest) String() string
  • func (d *Digest) UnmarshalBinary(data []byte) (err error)
  • func (d *Digest) UnmarshalText(data []byte) (err error)
  • func (d *Digest) Value() (value driver.Value, err error)
• type NullDigest
  • func NewNullDigest(d algorithm.Digest) (digest *NullDigest)
  • func NewNullDigestDecode(encodedDigest string) (digest *NullDigest, err error)
  • func (d *NullDigest) Encode() string
  • func (d *NullDigest) MarshalBinary() (data []byte, err error)
  • func (d *NullDigest) MarshalText() (data []byte, err error)
  • func (d *NullDigest) Match(password string) (match bool)
  • func (d *NullDigest) MatchAdvanced(password string) (match bool, err error)
  • func (d *NullDigest) MatchBytes(passwordBytes []byte) (match bool)
  • func (d *NullDigest) MatchBytesAdvanced(passwordBytes []byte) (match bool, err error)
  • func (d *NullDigest) Scan(src any) (err error)
  • func (d *NullDigest) String() string
  • func (d *NullDigest) UnmarshalBinary(data []byte) (err error)
  • func (d *NullDigest) UnmarshalText(data []byte) (err error)
  • func (d *NullDigest) Value() (value driver.Value, err error)

Constants

const (
	// StorageFormatPrefixLDAPCrypt is a prefix used by OpenLDAP for crypt format encoded digests.
	StorageFormatPrefixLDAPCrypt = "{CRYPT}"

	// StorageFormatPrefixLDAPArgon2 is a prefix used by OpenLDAP for argon2 format encoded digests.
	StorageFormatPrefixLDAPArgon2 = "{ARGON2}"
)

const (
	// Delimiter for all storage formats.
	Delimiter = encoding.DelimiterStr
)

Functions

func CheckPassword

func CheckPassword(password, encodedDigest string) (valid bool, err error)

CheckPassword takes the string password and an encoded digest. It decodes the Digest, then performs the MatchAdvanced() function on the Digest. If any process returns an error it returns false with the error, otherwise it returns the result of MatchAdvanced(). This is just a helper function and implementers can manually invoke this process themselves in situations where they may want to store the Digest to perform matches at a later date to avoid decoding multiple times for example.

CRITICAL STABILITY NOTE: the decoders loaded via this function are not guaranteed to remain the same. It is strongly recommended that users implementing this library use the NewDecoder function and explicitly register each decoder which they wish to support.

func CheckPasswordWithPlainText

func CheckPasswordWithPlainText(password, encodedDigest string) (valid bool, err error)

CheckPasswordWithPlainText is the same as CheckPassword however it also allows the plaintext passwords.

CRITICAL STABILITY NOTE: the decoders loaded via this function are not guaranteed to remain the same. It is strongly recommended that users implementing this library use the NewDecoder function and explicitly register each decoder which they wish to support.

func Decode

func Decode(encodedDigest string) (digest algorithm.Digest, err error)

Decode is a convenience function which wraps the Decoder functionality. It's recommended to create your own decoder instead via NewDecoder or NewDefaultDecoder.

CRITICAL STABILITY NOTE: the decoders loaded via this function are not guaranteed to remain the same. It is strongly recommended that users implementing this library use the NewDecoder function and explicitly register each decoder which they wish to support.

func Normalize

func Normalize(encodedDigest string) string

Normalize performs normalization on an encoded digest. This removes prefixes which are not necessary and performs minimal modification to the encoded digest to make it possible for decoding.

Types

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

Decoder is a struct which allows registering algorithm.DecodeFunc's and utilizing the programmatically to decode an encoded digest with them.

func NewDecoder

func NewDecoder() *Decoder

NewDecoder returns a new empty *Decoder.

See Also: NewDefaultDecoder and NewDecoderAll.

func NewDecoderAll

func NewDecoderAll() (d *Decoder, err error)

NewDecoderAll is the same as NewDefaultDecoder but it also adds legacy and/or insecure decoders.

Loaded Decoders (in addition to NewDefaultDecoder): plaintext, md5crypt, sha1crypt.

CRITICAL STABILITY NOTE: the decoders loaded via this function are not guaranteed to remain the same. It is strongly recommended that users implementing this library use this or NewDecodersAll only as an example for building their own decoder via NewDecoder instead which returns an empty decoder. It is much safer for security and stability to be explicit in harmony with your specific use case. It is the responsibility of the implementer to determine which password algorithms are sufficiently safe for their particular use case.

func NewDefaultDecoder

func NewDefaultDecoder() (d *Decoder, err error)

NewDefaultDecoder returns the default decoder recommended for new implementations.

Loaded Decoders: argon2, bcrypt, pbkdf2, scrypt, shacrypt.

CRITICAL STABILITY NOTE: the decoders loaded via this function are not guaranteed to remain the same. It is strongly recommended that users implementing this library use this or NewDecodersAll only as an example for building their own decoder via NewDecoder instead which returns an empty decoder. It is much safer for security and stability to be explicit in harmony with your specific use case. It is the responsibility of the implementer to determine which password algorithms are sufficiently safe for their particular use case.

func (*Decoder) Decode

func (d *Decoder) Decode(encodedDigest string) (digest algorithm.Digest, err error)

Decode an encoded digest into a algorithm.Digest.

func (*Decoder) RegisterDecodeFunc

func (d *Decoder) RegisterDecodeFunc(identifier string, decoder algorithm.DecodeFunc) (err error)

RegisterDecodeFunc registers a new algorithm.DecodeFunc with this Decoder against a specific identifier.

func (*Decoder) RegisterDecodePrefix

func (d *Decoder) RegisterDecodePrefix(prefix, identifier string) (err error)

RegisterDecodePrefix registers a prefix which is matched by strings.HasPrefix.

type Digest

type Digest struct {
	// contains filtered or unexported fields
}

Digest is a decorator struct which wraps the algorithm.Digest and adds sql.Scanner/driver.Valuer, encoding.TextMarshaler/encoding.TextUnmarshaler, and encoding.BinaryMarshaler/encoding.BinaryUnmarshaler implementations.

func NewDigest

func NewDigest(d algorithm.Digest) (digest *Digest, err error)

NewDigest wraps an algorithm.Digest in the convenience layer of the crypt.Digest.

func NewDigestDecode

func NewDigestDecode(encodedDigest string) (digest *Digest, err error)

NewDigestDecode decodes a string into a algorithm.Digest and wraps it in the convenience layer of the crypt.Digest.

func (*Digest) Encode

func (d *Digest) Encode() string

Encode decorates the algorithm.Digest Encode function.

func (*Digest) MarshalBinary

func (d *Digest) MarshalBinary() (data []byte, err error)

MarshalBinary implements encoding.BinaryMarshaler.

func (*Digest) MarshalText

func (d *Digest) MarshalText() (data []byte, err error)

MarshalText implements encoding.TextMarshaler.

func (*Digest) Match

func (d *Digest) Match(password string) (match bool)

Match decorates the algorithm.Digest Match function.

func (*Digest) MatchAdvanced

func (d *Digest) MatchAdvanced(password string) (match bool, err error)

MatchAdvanced decorates the algorithm.Digest MatchAdvanced function.

func (*Digest) MatchBytes

func (d *Digest) MatchBytes(passwordBytes []byte) (match bool)

MatchBytes decorates the algorithm.Digest MatchBytes function.

func (*Digest) MatchBytesAdvanced

func (d *Digest) MatchBytesAdvanced(passwordBytes []byte) (match bool, err error)

MatchBytesAdvanced decorates the algorithm.Digest MatchBytesAdvanced function.

func (*Digest) Scan

func (d *Digest) Scan(src any) (err error)

Scan implements sql.Scanner.

func (*Digest) String

func (d *Digest) String() string

String decorates the algorithm.Digest String function.

func (*Digest) UnmarshalBinary

func (d *Digest) UnmarshalBinary(data []byte) (err error)

UnmarshalBinary implements encoding.BinaryUnmarshaler.

func (*Digest) UnmarshalText

func (d *Digest) UnmarshalText(data []byte) (err error)

UnmarshalText implements encoding.TextUnmarshaler.

func (*Digest) Value

func (d *Digest) Value() (value driver.Value, err error)

Value implements driver.Valuer.

type NullDigest

type NullDigest struct {
	// contains filtered or unexported fields
}

NullDigest is variation of crypt.Digest which accepts nulls.

func NewNullDigest

func NewNullDigest(d algorithm.Digest) (digest *NullDigest)

NewNullDigest wraps an algorithm.Digest in the convenience layer of the crypt.NullDigest.

func NewNullDigestDecode

func NewNullDigestDecode(encodedDigest string) (digest *NullDigest, err error)

NewNullDigestDecode decodes a string into a algorithm.Digest and wraps it in the convenience layer of the crypt.NullDigest.

func (*NullDigest) Encode

func (d *NullDigest) Encode() string

Encode decorates the algorithm.Digest Encode function.

func (*NullDigest) MarshalBinary

func (d *NullDigest) MarshalBinary() (data []byte, err error)

MarshalBinary implements encoding.BinaryMarshaler.

func (*NullDigest) MarshalText

func (d *NullDigest) MarshalText() (data []byte, err error)

MarshalText implements encoding.TextMarshaler.

func (*NullDigest) Match

func (d *NullDigest) Match(password string) (match bool)

Match decorates the algorithm.Digest Match function.

func (*NullDigest) MatchAdvanced

func (d *NullDigest) MatchAdvanced(password string) (match bool, err error)

MatchAdvanced decorates the algorithm.Digest MatchAdvanced function.

func (*NullDigest) MatchBytes

func (d *NullDigest) MatchBytes(passwordBytes []byte) (match bool)

MatchBytes decorates the algorithm.Digest MatchBytes function.

func (*NullDigest) MatchBytesAdvanced

func (d *NullDigest) MatchBytesAdvanced(passwordBytes []byte) (match bool, err error)

MatchBytesAdvanced decorates the algorithm.Digest MatchBytesAdvanced function.

func (*NullDigest) Scan

func (d *NullDigest) Scan(src any) (err error)

Scan implements sql.Scanner.

func (*NullDigest) String

func (d *NullDigest) String() string

String decorates the algorithm.Digest String function.

func (*NullDigest) UnmarshalBinary

func (d *NullDigest) UnmarshalBinary(data []byte) (err error)

UnmarshalBinary implements encoding.BinaryUnmarshaler.

func (*NullDigest) UnmarshalText

func (d *NullDigest) UnmarshalText(data []byte) (err error)

UnmarshalText implements encoding.TextUnmarshaler.

func (*NullDigest) Value

func (d *NullDigest) Value() (value driver.Value, err error)

Value implements driver.Valuer.