Documentation
¶
Overview ¶
Package hash provides a unified and extensible framework for password hashing and verification.
It offers a consistent interface to work with a variety of hashing algorithms, from standard ones like SHA-256 and bcrypt to custom, user-defined implementations.
Key Features:
Unified Interface: The `Crypto` interface provides a simple `Hash` and `Verify` method, abstracting away the complexities of each underlying algorithm.
Extensible by Design: New algorithms can be easily integrated by implementing the `scheme.Scheme` and `scheme.Factory` interfaces and registering them using the `Register` function.
Automatic Algorithm Detection: The library automatically identifies the algorithm from the encoded hash string during verification, allowing for seamless algorithm upgrades.
Tunable Parameters: Algorithm-specific parameters, such as bcrypt's cost or Argon2's memory usage, can be configured at creation time using option functions.
Basic Usage:
// Create a new instance for a specific algorithm (e.g., bcrypt).
crypto, err := hash.NewCrypto(types.BCRYPT, bcrypt.WithCost(12))
if err != nil {
log.Fatal(err)
}
// Hash a password.
hashed, err := crypto.Hash("my-secret-password")
if err != nil {
log.Fatal(err)
}
// Verify the password against the hash.
if err := crypto.Verify(hashed, "my-secret-password"); err != nil {
fmt.Println("Password verification failed!")
}
Package hash implements the functions, types, and interfaces for the module.
Package hash implements the functions, types, and interfaces for the module.
Package hash implements the functions, types, and interfaces for the module.
Index ¶
- func AvailableAlgorithms() []string
- func ConfigFromHashParts(parts *types.HashParts) *types.Config
- func DefaultConfig() *types.Config
- func Generate(password string) (string, error)
- func GenerateWithSalt(password string, salt []byte) (string, error)
- func Register(factory scheme.Factory, canonicalSpec types.Spec, aliases ...string)
- func UseCrypto(algName string, opts ...Option) error
- func Verify(hashed, password string) error
- type Crypto
- type Factory
- func (f *Factory) AvailableAlgorithms() []string
- func (f *Factory) Create(spec types.Spec, cfg *types.Config) (scheme.Scheme, error)
- func (f *Factory) GetConfig(name string) *types.Config
- func (f *Factory) GetFactory(name string) (scheme.Factory, bool)
- func (f *Factory) GetSpec(specStr string) (types.Spec, bool)
- func (f *Factory) Register(factory scheme.Factory, canonicalSpec types.Spec, aliases ...string)
- type Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AvailableAlgorithms ¶ added in v0.3.18
func AvailableAlgorithms() []string
AvailableAlgorithms returns a list of all registered hash algorithm aliases from the default factory.
func ConfigFromHashParts ¶ added in v1.1.0
ConfigFromHashParts creates a Config from a HashParts object.
func DefaultConfig ¶ added in v1.2.0
DefaultConfig return to the default configuration
func GenerateWithSalt ¶
GenerateWithSalt is a convenience function that uses the active global crypto instance.
func Register ¶ added in v1.1.0
Register is a convenience function that registers a factory to the default global factory.
Types ¶
type Crypto ¶
type Crypto interface {
// Spec returns the configured default algorithm specification for this crypto instance.
Spec() types.Spec
// Hash creates a new hash for the given password using the default algorithm.
// The returned string is a fully encoded hash that includes all necessary metadata
// for verification, such as the algorithm, parameters, and salt.
Hash(password string) (string, error)
// HashWithSalt creates a new hash with a user-provided salt.
// This is useful for testing or specific use cases where salt generation is handled externally.
HashWithSalt(password string, salt []byte) (string, error)
// Verify checks if a password matches an encoded hash string.
// It automatically detects the algorithm from the hash string, creates the appropriate
// verification scheme, and performs the comparison. Results are cached for performance.
Verify(hashed, password string) error
}
Crypto defines the primary interface for cryptographic hashing operations. An instance of Crypto is configured with a default algorithm for creating new hashes, but it can verify hashes from any algorithm registered in its factory.
func NewCrypto ¶
NewCrypto is the primary convenience function for creating a Crypto instance. It uses the default global factory.
func NewCryptoWithFactory ¶ added in v1.1.0
NewCryptoWithFactory creates a Crypto instance using a specific, provided factory. This is useful for testing or creating isolated instances with different configurations.
type Factory ¶ added in v1.1.0
type Factory struct {
// contains filtered or unexported fields
}
Factory holds the registration of all scheme factories and spec mappings.
func NewFactory ¶ added in v1.1.0
func NewFactory() *Factory
NewFactory creates a new, empty factory.
func (*Factory) AvailableAlgorithms ¶ added in v1.1.0
AvailableAlgorithms returns a list of all registered hash algorithm aliases.
func (*Factory) Create ¶ added in v1.1.0
Create uses the registered providers to create a new Scheme instance.
func (*Factory) GetConfig ¶ added in v1.1.0
GetConfig returns the default configuration for a given algorithm module.
func (*Factory) GetFactory ¶ added in v1.1.0
type Option ¶ added in v1.1.0
Option is a function that modifies a Config
func WithHashParts ¶ added in v1.1.0
WithHashParts sets the salt length and parameters from a HashParts object.
func WithParamString ¶ added in v1.1.0
WithParamString sets the parameters for the hash algorithm using a type that implements fmt.Stringer.
func WithParams ¶ added in v1.1.0
WithParams sets the parameters for the hash algorithm directly from a map[string]string. This is the preferred way to set algorithm-specific parameters when they are already in map format.
func WithSaltLength ¶ added in v1.1.0
WithSaltLength sets the salt length
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
algorithms
|
|
|
argon2
Package argon2 implements the functions, types, and interfaces for the module.
|
Package argon2 implements the functions, types, and interfaces for the module. |
|
blake2
Package blake2 implements the functions, types, and interfaces for the module.
|
Package blake2 implements the functions, types, and interfaces for the module. |
|
crc
Package crc implements the functions, types, and interfaces for the module.
|
Package crc implements the functions, types, and interfaces for the module. |
|
hmac
Package hmac implements the functions, types, and interfaces for the module.
|
Package hmac implements the functions, types, and interfaces for the module. |
|
pbkdf2
Package pbkdf2 implements the functions, types, and interfaces for the module.
|
Package pbkdf2 implements the functions, types, and interfaces for the module. |
|
ripemd160
Package ripemd160 implements the functions, types, and interfaces for the module.
|
Package ripemd160 implements the functions, types, and interfaces for the module. |
|
sha
Package sha implements the functions, types, and interfaces for the module.
|
Package sha implements the functions, types, and interfaces for the module. |
|
examples
|
|
|
hash
command
Package main provides an example of using the hash package
|
Package main provides an example of using the hash package |
|
internal
|
|
|
Package scheme implements the functions, types, and interfaces for the module.
|
Package scheme implements the functions, types, and interfaces for the module. |
|
Package types implements the functions, types, and interfaces for the module.
|
Package types implements the functions, types, and interfaces for the module. |
|
Package validator provides a common interface for algorithm-specific parameters.
|
Package validator provides a common interface for algorithm-specific parameters. |