crypt

package module
Version: v0.2.5 Latest Latest
Warning

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

Go to latest
Published: Feb 2, 2023 License: MIT Imports: 15 Imported by: 0

README

Go Reference Go Report Card

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.18+

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

View Source
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}"
)
View Source
const (
	// Delimiter for all storage formats.
	Delimiter = encoding.DelimiterStr
)

Variables

This section is empty.

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 added in v0.2.0

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 added in v0.2.0

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 added in v0.2.0

func NewDecoder() *Decoder

NewDecoder returns a new empty *Decoder.

See Also: NewDefaultDecoder and NewDecoderAll.

func NewDecoderAll added in v0.2.0

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 added in v0.2.0

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 added in v0.2.0

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

Decode an encoded digest into a algorithm.Digest.

func (*Decoder) RegisterDecodeFunc added in v0.2.0

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 added in v0.2.0

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 added in v0.2.0

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 added in v0.2.0

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

MarshalBinary implements encoding.BinaryMarshaler.

func (*Digest) MarshalText added in v0.2.0

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

MarshalText implements encoding.TextMarshaler.

func (*Digest) Match added in v0.2.0

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

Match decorates the algorithm.Digest Match function.

func (*Digest) MatchAdvanced added in v0.2.0

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

MatchAdvanced decorates the algorithm.Digest MatchAdvanced function.

func (*Digest) MatchBytes added in v0.2.0

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

MatchBytes decorates the algorithm.Digest MatchBytes function.

func (*Digest) MatchBytesAdvanced added in v0.2.0

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

MatchBytesAdvanced decorates the algorithm.Digest MatchBytesAdvanced function.

func (*Digest) Scan added in v0.2.0

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

Scan implements sql.Scanner.

func (*Digest) String added in v0.2.0

func (d *Digest) String() string

String decorates the algorithm.Digest String function.

func (*Digest) UnmarshalBinary added in v0.2.0

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

UnmarshalBinary implements encoding.BinaryUnmarshaler.

func (*Digest) UnmarshalText added in v0.2.0

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

UnmarshalText implements encoding.TextUnmarshaler.

func (*Digest) Value added in v0.2.0

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

Value implements driver.Valuer.

type NullDigest added in v0.2.0

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

NullDigest is variation of crypt.Digest which accepts nulls.

func NewNullDigest added in v0.2.0

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

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

func NewNullDigestDecode added in v0.2.0

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 added in v0.2.0

func (d *NullDigest) Encode() string

Encode decorates the algorithm.Digest Encode function.

func (*NullDigest) MarshalBinary added in v0.2.0

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

MarshalBinary implements encoding.BinaryMarshaler.

func (*NullDigest) MarshalText added in v0.2.0

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

MarshalText implements encoding.TextMarshaler.

func (*NullDigest) Match added in v0.2.0

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

Match decorates the algorithm.Digest Match function.

func (*NullDigest) MatchAdvanced added in v0.2.0

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

MatchAdvanced decorates the algorithm.Digest MatchAdvanced function.

func (*NullDigest) MatchBytes added in v0.2.0

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

MatchBytes decorates the algorithm.Digest MatchBytes function.

func (*NullDigest) MatchBytesAdvanced added in v0.2.0

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

MatchBytesAdvanced decorates the algorithm.Digest MatchBytesAdvanced function.

func (*NullDigest) Scan added in v0.2.0

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

Scan implements sql.Scanner.

func (*NullDigest) String added in v0.2.0

func (d *NullDigest) String() string

String decorates the algorithm.Digest String function.

func (*NullDigest) UnmarshalBinary added in v0.2.0

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

UnmarshalBinary implements encoding.BinaryUnmarshaler.

func (*NullDigest) UnmarshalText added in v0.2.0

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

UnmarshalText implements encoding.TextUnmarshaler.

func (*NullDigest) Value added in v0.2.0

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

Value implements driver.Valuer.

Directories

Path Synopsis
Package algorithm is a package which contains the individual algorithms and interfaces related to their implementation.
Package algorithm is a package which contains the individual algorithms and interfaces related to their implementation.
argon2
Package argon2 provides helpful abstractions for an implementation of RFC9106 and implements github.com/go-crypt/crypt interfaces.
Package argon2 provides helpful abstractions for an implementation of RFC9106 and implements github.com/go-crypt/crypt interfaces.
bcrypt
Package bcrypt provides helpful abstractions for an implementation of bcrypt and implements github.com/go-crypt/crypt interfaces.
Package bcrypt provides helpful abstractions for an implementation of bcrypt and implements github.com/go-crypt/crypt interfaces.
md5crypt
Package md5crypt provides helpful abstractions for an implementation of crypt (MD5) and implements github.com/go-crypt/crypt interfaces.
Package md5crypt provides helpful abstractions for an implementation of crypt (MD5) and implements github.com/go-crypt/crypt interfaces.
pbkdf2
Package pbkdf2 provides helpful abstractions for an implementation of PBKDF2 and implements github.com/go-crypt/crypt interfaces.
Package pbkdf2 provides helpful abstractions for an implementation of PBKDF2 and implements github.com/go-crypt/crypt interfaces.
plaintext
Package plaintext implements github.com/go-crypt/crypt interfaces with variants of plaintext useful for easy uptake of previously unhashed passwords.
Package plaintext implements github.com/go-crypt/crypt interfaces with variants of plaintext useful for easy uptake of previously unhashed passwords.
scrypt
Package scrypt provides helpful abstractions for an implementation of RFC7914 and implements github.com/go-crypt/crypt interfaces.
Package scrypt provides helpful abstractions for an implementation of RFC7914 and implements github.com/go-crypt/crypt interfaces.
sha1crypt
Package sha1crypt provides helpful abstractions for an implementation of crypt (SHA1) and implements github.com/go-crypt/crypt interfaces.
Package sha1crypt provides helpful abstractions for an implementation of crypt (SHA1) and implements github.com/go-crypt/crypt interfaces.
shacrypt
Package shacrypt provides helpful abstractions for an implementation of SHA-crypt and implements github.com/go-crypt/crypt interfaces.
Package shacrypt provides helpful abstractions for an implementation of SHA-crypt and implements github.com/go-crypt/crypt interfaces.
internal
encoding
Package encoding is an internal encoding helper package.
Package encoding is an internal encoding helper package.
math
Package math is an internal mathematics helper package.
Package math is an internal mathematics helper package.
random
Package random is an internal helper package.
Package random is an internal helper package.

Jump to

Keyboard shortcuts

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