Skip to content

Commit 0b316e7

Browse files
harjothkhararolandshoemaker
authored andcommitted
argon2: update RFC 9106 parameter recommendations
Update the IDKey example to use RFC 9106's first recommended Argon2id option and clarify the relationship between the first and second recommended options. Fixes golang/go#79823 Change-Id: If44a86a5a8112b02fab97b4d5e325fe91d6049ee GitHub-Last-Rev: a764ae6 GitHub-Pull-Request: #357 Reviewed-on: https://go-review.googlesource.com/c/crypto/+/789020 Reviewed-by: Roland Shoemaker <[email protected]> Reviewed-by: Dmitri Shuralyov <[email protected]> LUCI-TryBot-Result: [email protected] <[email protected]>
1 parent 55aec0a commit 0b316e7

1 file changed

Lines changed: 18 additions & 17 deletions

File tree

‎argon2/argon2.go‎

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -17,20 +17,23 @@
1717
// It uses data-independent memory access, which is preferred for password
1818
// hashing and password-based key derivation. Argon2i requires more passes over
1919
// memory than Argon2id to protect from trade-off attacks. The recommended
20-
// parameters (taken from [RFC 9106 Section 7.3]) for non-interactive operations are time=3 and to
21-
// use the maximum available memory.
20+
// parameters (taken from [RFC 9106 Section 7.3]) for non-interactive
21+
// operations are time=3 and to use the maximum available memory.
2222
//
2323
// # Argon2id
2424
//
2525
// Argon2id (implemented by IDKey) is a hybrid version of Argon2 combining
2626
// Argon2i and Argon2d. It uses data-independent memory access for the first
2727
// half of the first iteration over the memory and data-dependent memory access
2828
// for the rest. Argon2id is side-channel resistant and provides better brute-
29-
// force cost savings due to time-memory tradeoffs than Argon2i. The recommended
30-
// parameters for non-interactive operations (taken from [RFC 9106 Section 7.3]) are time=1 and to
31-
// use the maximum available memory.
29+
// force cost savings due to time-memory tradeoffs than Argon2i. [RFC 9106
30+
// Section 4] recommends time=1, memory=2*1024*1024 KiB (2 GiB), and threads=4
31+
// as the first recommended option. If much less memory is available, it
32+
// recommends time=3, memory=64*1024 KiB (64 MiB), and threads=4 as the second
33+
// recommended option.
3234
//
3335
// [argon2-specs.pdf]: https://github.com/P-H-C/phc-winner-argon2/blob/master/argon2-specs.pdf
36+
// [RFC 9106 Section 4]: https://www.rfc-editor.org/rfc/rfc9106.html#section-4
3437
// [RFC 9106 Section 7.3]: https://www.rfc-editor.org/rfc/rfc9106.html#section-7.3
3538
package argon2
3639

@@ -59,18 +62,16 @@ const (
5962
//
6063
// key := argon2.Key([]byte("some password"), salt, 3, 32*1024, 4, 32)
6164
//
62-
// [RFC 9106 Section 7.3] recommends time=3, and memory=32*1024 as a sensible number.
63-
// If using that amount of memory (32 MB) is not possible in some contexts then
64-
// the time parameter can be increased to compensate.
65+
// The example above uses time=3 and memory=32*1024. Argon2i generally
66+
// requires more passes over memory than Argon2id. If in doubt, prefer IDKey
67+
// and its Argon2id parameter recommendations.
6568
//
6669
// The time parameter specifies the number of passes over the memory and the
6770
// memory parameter specifies the size of the memory in KiB. For example
6871
// memory=32*1024 sets the memory cost to ~32 MB. The number of threads can be
6972
// adjusted to the number of available CPUs. The cost parameters should be
7073
// increased as memory latency and CPU parallelism increases. Remember to get a
7174
// good random salt.
72-
//
73-
// [RFC 9106 Section 7.3]: https://www.rfc-editor.org/rfc/rfc9106.html#section-7.3
7475
func Key(password, salt []byte, time, memory uint32, threads uint8, keyLen uint32) []byte {
7576
return deriveKey(argon2i, password, salt, nil, nil, time, memory, threads, keyLen)
7677
}
@@ -83,20 +84,20 @@ func Key(password, salt []byte, time, memory uint32, threads uint8, keyLen uint3
8384
// For example, you can get a derived key for e.g. AES-256 (which needs a
8485
// 32-byte key) by doing:
8586
//
86-
// key := argon2.IDKey([]byte("some password"), salt, 1, 64*1024, 4, 32)
87+
// key := argon2.IDKey([]byte("some password"), salt, 1, 2*1024*1024, 4, 32)
8788
//
88-
// [RFC 9106 Section 7.3] recommends time=1, and memory=64*1024 as a sensible number.
89-
// If using that amount of memory (64 MB) is not possible in some contexts then
90-
// the time parameter can be increased to compensate.
89+
// The example above uses the first [RFC 9106 Section 4] recommended option.
90+
// If much less memory is available, the second recommended option is time=3,
91+
// memory=64*1024 KiB (64 MiB), and threads=4.
9192
//
9293
// The time parameter specifies the number of passes over the memory and the
9394
// memory parameter specifies the size of the memory in KiB. For example
94-
// memory=64*1024 sets the memory cost to ~64 MB. The number of threads can be
95-
// adjusted to the numbers of available CPUs. The cost parameters should be
95+
// memory=2*1024*1024 sets the memory cost to ~2 GiB. The number of threads can
96+
// be adjusted to the numbers of available CPUs. The cost parameters should be
9697
// increased as memory latency and CPU parallelism increases. Remember to get a
9798
// good random salt.
9899
//
99-
// [RFC 9106 Section 7.3]: https://www.rfc-editor.org/rfc/rfc9106.html#section-7.3
100+
// [RFC 9106 Section 4]: https://www.rfc-editor.org/rfc/rfc9106.html#section-4
100101
func IDKey(password, salt []byte, time, memory uint32, threads uint8, keyLen uint32) []byte {
101102
return deriveKey(argon2id, password, salt, nil, nil, time, memory, threads, keyLen)
102103
}

0 commit comments

Comments
 (0)