argon2

package module
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Jan 17, 2024 License: BSD-3-Clause Imports: 5 Imported by: 1

README

argon2

This package is a fork off the https://pkg.go.dev/golang.org/x/crypto/argon2 package. It is generally recommended to use the officially supported package rather than this one. The only reason this fork exists is because keepass selected argon2 in 2d mode, which was chosen not to be exposed in the implementation. In order to be able to implement a compatible version for keepass. Read up here about more details as to why it was not exposed.

Documentation

Overview

Package argon2 implements the key derivation function Argon2. Argon2 was selected as the winner of the Password Hashing Competition and can be used to derive cryptographic keys from passwords.

For a detailed specification of Argon2 see [1].

If you aren't sure which function you need, use Argon2id (IDKey) and the parameter recommendations for your scenario.

Argon2i

Argon2i (implemented by Key) is the side-channel resistant version of Argon2. It uses data-independent memory access, which is preferred for password hashing and password-based key derivation. Argon2i requires more passes over memory than Argon2id to protect from trade-off attacks. The recommended parameters (taken from [2]) for non-interactive operations are time=3 and to use the maximum available memory.

Argon2id

Argon2id (implemented by IDKey) is a hybrid version of Argon2 combining Argon2i and Argon2d. It uses data-independent memory access for the first half of the first iteration over the memory and data-dependent memory access for the rest. Argon2id is side-channel resistant and provides better brute- force cost savings due to time-memory tradeoffs than Argon2i. The recommended parameters for non-interactive operations (taken from [2]) are time=1 and to use the maximum available memory.

[1] https://github.com/P-H-C/phc-winner-argon2/blob/master/argon2-specs.pdf [2] https://tools.ietf.org/html/draft-irtf-cfrg-argon2-03#section-9.3

Package argon2 implements the key derivation function Argon2. Argon2 was selected as the winner of the Password Hashing Competition and can be used to derive cryptographic keys from passwords.

For a detailed specification of Argon2 see [1].

If you aren't sure which function you need, use Argon2id (IDKey) and the parameter recommendations for your scenario.

Argon2d

Argon2d (implemented by DKey) is a version that is not side channel resistent but provideds maximum security for brute force attacks. This is not exposed by golang.org/x/crypto/argon2. It is in a separate file to avoid conflicts when updating the remaining code.

[1] https://github.com/P-H-C/phc-winner-argon2/blob/master/argon2-specs.pdf [2] https://tools.ietf.org/html/draft-irtf-cfrg-argon2-03#section-9.3

Index

Constants

View Source
const Version = 0x13

The Argon2 version implemented by this package.

Variables

This section is empty.

Functions

func DKey

func DKey(password, salt []byte, time, memory uint32, threads uint8, keyLen uint32) []byte

DKey derives a key from the password, salt, and cost parameters using Argon2d returning a byte slice of length keyLen that can be used as cryptographic key. The CPU cost and parallelism degree must be greater than zero.

For example, you can get a derived key for e.g. AES-256 (which needs a 32-byte key) by doing:

key := argon2.DKey([]byte("some password"), salt, 1, 64*1024, 4, 32)

The draft RFC recommends[2] time=3, and memory=32*1024 is a sensible number. If using that amount of memory (32 MB) is not possible in some contexts then the time parameter can be increased to compensate.

The time parameter specifies the number of passes over the memory and the memory parameter specifies the size of the memory in KiB. For example memory=32*1024 sets the memory cost to ~32 MB. The number of threads can be adjusted to the number of available CPUs. The cost parameters should be increased as memory latency and CPU parallelism increases. Remember to get a good random salt.

func IDKey

func IDKey(password, salt []byte, time, memory uint32, threads uint8, keyLen uint32) []byte

IDKey derives a key from the password, salt, and cost parameters using Argon2id returning a byte slice of length keyLen that can be used as cryptographic key. The CPU cost and parallelism degree must be greater than zero.

For example, you can get a derived key for e.g. AES-256 (which needs a 32-byte key) by doing:

key := argon2.IDKey([]byte("some password"), salt, 1, 64*1024, 4, 32)

The draft RFC recommends[2] time=1, and memory=64*1024 is a sensible number. If using that amount of memory (64 MB) is not possible in some contexts then the time parameter can be increased to compensate.

The time parameter specifies the number of passes over the memory and the memory parameter specifies the size of the memory in KiB. For example memory=64*1024 sets the memory cost to ~64 MB. The number of threads can be adjusted to the numbers of available CPUs. The cost parameters should be increased as memory latency and CPU parallelism increases. Remember to get a good random salt.

func Key

func Key(password, salt []byte, time, memory uint32, threads uint8, keyLen uint32) []byte

Key derives a key from the password, salt, and cost parameters using Argon2i returning a byte slice of length keyLen that can be used as cryptographic key. The CPU cost and parallelism degree must be greater than zero.

For example, you can get a derived key for e.g. AES-256 (which needs a 32-byte key) by doing:

key := argon2.Key([]byte("some password"), salt, 3, 32*1024, 4, 32)

The draft RFC recommends[2] time=3, and memory=32*1024 is a sensible number. If using that amount of memory (32 MB) is not possible in some contexts then the time parameter can be increased to compensate.

The time parameter specifies the number of passes over the memory and the memory parameter specifies the size of the memory in KiB. For example memory=32*1024 sets the memory cost to ~32 MB. The number of threads can be adjusted to the number of available CPUs. The cost parameters should be increased as memory latency and CPU parallelism increases. Remember to get a good random salt.

Types

This section is empty.

Jump to

Keyboard shortcuts

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