Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Key ¶
func Key(passphrase string, salt []byte, params *CostParams, keyLen uint32) []byte
Key derives a key of the desired length from the supplied passphrase and salt using the Argon2i algorithm with the supplied cost parameters.
By design, this function consumes a lot of memory depending on the supplied parameters. It may be desirable to execute it in a short-lived utility process.
func KeyDuration ¶
func KeyDuration(params *CostParams, keyLen uint32) time.Duration
KeyDuration runs a key derivation with the built-in benchmarking values and the specified cost parameters and length, and then returns the amount of time taken to execute.
By design, this function consumes a lot of memory depending on the supplied parameters. It may be desirable to execute it in a short-lived utility process.
Types ¶
type BenchmarkParams ¶
type BenchmarkParams struct {
// MaxMemoryCostKiB sets the upper memory usage limit in KiB.
MaxMemoryCostKiB uint32
// TargetDuration sets the target time for which the benchmark will
// compute cost parameters.
TargetDuration time.Duration
// Threads is the number of parallel threads that will be used
// for the key derivation. Set this to zero to derive it from
// the number of CPUs.
Threads uint8
}
BenchmarkParams defines the parameters for benchmarking the Argon2 algorithm
type CostParams ¶
type CostParams struct {
// Time corresponds to the number of iterations of the algorithm
// that the key derivation will use.
Time uint32
// MemoryKiB is the amount of memory in KiB that the key derivation
// will use.
MemoryKiB uint32
// Threads is the number of parallel threads that will be used
// for the key derivation.
Threads uint8
}
CostParams defines the cost parameters for key derivation using Argon2. It can either be generated by Benchmark or supplied with well known values.
func Benchmark ¶
func Benchmark(params *BenchmarkParams, keyFn KeyDurationFunc) (*CostParams, error)
Benchmark computes the cost parameters for the desired duration and maximum memory cost.
The algorithm is based on the one implemented in cryptsetup. If the current duration is shorter than the target duration, then increasing the memory cost is prioritized over increasing the time cost. The time cost is only increased once the maximum memory cost has been reached. If the current duration is longer than the target duration, then decreasing the time cost is prioritized over decreasing the memory cost. The memory cost is only decreased once the hard-coded minimum time cost has been reached.
The package hard codes a minimum time cost of 4 iterations, and a minimum memory cost of 32MiB. A maximum memory cost of half of the total RAM or 4GB provides a ceiling to the supplied maximum memory cost. The algorithm will set 1 thread per CPU, up to a limit of 4 threads.
The supplied callback is used to actually run the key derivation measurement, which will consume a lot of memory depending on the supplied parameters. Each measurement should generally be delegated to a short-lived utility process, which should call the KeyDuration function from this package. If the measurement is performed in the current process, the garbage collector must be executed at the end of each measurement.
type KeyDurationFunc ¶
type KeyDurationFunc func(params *CostParams) (time.Duration, error)
KeyDurationFunc provides a mechanism to delegate key derivation measurements to a short-lived utility process during benchmarking.
Source Files