Skip to content

Commit

Permalink
Script updating gh-pages from 72fb2da. [ci skip]
Browse files Browse the repository at this point in the history
  • Loading branch information
ID Bot committed Oct 26, 2024
1 parent 4c86815 commit f629b18
Show file tree
Hide file tree
Showing 2 changed files with 39 additions and 12 deletions.
33 changes: 21 additions & 12 deletions draft-lucas-bkdf.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1657,18 +1657,19 @@ <h3 id="name-usage-guidelines">
<a href="#section-9.1" class="section-number selfRef">9.1. </a><a href="#name-usage-guidelines" class="section-name selfRef">Usage Guidelines</a>
</h3>
<p id="section-9.1-1">Technically, only preimage resistance is required for password hashing to prevent the attacker learning information about the password from the hash. However, hash functions that are not collision resistant (e.g. MD5 <span>[<a href="#RFC6151" class="cite xref">RFC6151</a>]</span> and SHA-1 <span>[<a href="#RFC6194" class="cite xref">RFC6194</a>]</span>) <span class="bcp14">MUST NOT</span> be used. Such functions are cryptographically weak and unsuitable for new protocols.<a href="#section-9.1-1" class="pilcrow"></a></p>
<p id="section-9.1-2">If possible, store the password in protected memory and/or erase the password from memory once it is no longer required. Otherwise, an attacker may be able to recover the password from memory or the disk.<a href="#section-9.1-2" class="pilcrow"></a></p>
<p id="section-9.1-3">In all cases, it is <span class="bcp14">RECOMMENDED</span> to use a 128-bit <code>salt</code>. However, a 64-bit <code>salt</code> <span class="bcp14">MAY</span> be used if there are storage constraints. Regardless, the <code>salt</code> length <span class="bcp14">SHOULD NOT</span> vary in your protocol/application.<a href="#section-9.1-3" class="pilcrow"></a></p>
<p id="section-9.1-4">The salt <span class="bcp14">MUST</span> be unique each time you call the function unless verifying a password hash or deriving the same key. It <span class="bcp14">SHOULD</span> be randomly generated using a cryptographically secure pseudorandom number generator (CSPRNG). However, it <span class="bcp14">MAY</span> be deterministic and predictable if random generation is not possible.<a href="#section-9.1-4" class="pilcrow"></a></p>
<p id="section-9.1-5">The salt <span class="bcp14">SHOULD</span> be considered a non-secret value. It <span class="bcp14">SHOULD</span> be stored alongside the password hash for password hashing (see <a href="#encoding-password-hashes" class="auto internal xref">Section 8</a>) or in something like a file header for key derivation. If you have a secret key, the password hash <span class="bcp14">SHOULD</span> be encrypted or the <code>pepper</code> parameter <span class="bcp14">SHOULD</span> be used, as described below.<a href="#section-9.1-5" class="pilcrow"></a></p>
<p id="section-9.1-6">The <code>spaceCost</code>, <code>timeCost</code>, and <code>parallelism</code> parameters <span class="bcp14">MUST</span> be carefully chosen to avoid denial-of-service and user frustration whilst ensuring adequate protection against password cracking. See <a href="#choosing-the-cost-parameters" class="auto internal xref">Section 7</a> for more information about choosing these parameters.<a href="#section-9.1-6" class="pilcrow"></a></p>
<p id="section-9.1-7">Avoid using hardcoded <code>spaceCost</code>/<code>timeCost</code>/<code>parallelism</code> parameters when performing password hashing; these <span class="bcp14">SHOULD</span> be stored as part of the password hash, as described in <a href="#encoding-password-hashes" class="auto internal xref">Section 8</a>. With key derivation, hardcoded parameters are acceptable if protocol versioning is used.<a href="#section-9.1-7" class="pilcrow"></a></p>
<p id="section-9.1-8">For password hashing, it is <span class="bcp14">RECOMMENDED</span> to use a <code>length</code> of 128 or 256 bits. For key derivation, it is <span class="bcp14">RECOMMENDED</span> to use a <code>length</code> of at least 128 bits.<a href="#section-9.1-8" class="pilcrow"></a></p>
<p id="section-9.1-9">If you want to derive multiple keys (e.g. for encryption and authentication), you <span class="bcp14">MUST</span> only run the algorithm once and use different portions of the output as separate keys. Otherwise, the attacker may have an advantage, like only needing to run the algorithm once instead of twice to check a password, and you will be forced to use weaker parameters.<a href="#section-9.1-9" class="pilcrow"></a></p>
<p id="section-9.1-10">For password hashing, it is <span class="bcp14">RECOMMENDED</span> to encrypt password hashes using an unauthenticated encryption algorithm or an authenticated encryption with associated data (AEAD) scheme <span>[<a href="#RFC5116" class="cite xref">RFC5116</a>]</span> before storage. This forces an attacker to compromise the key, which is stored separately from the database, as well as the database before they can begin password cracking. If the key is compromised but the database is not, it can be rotated without having to reset any passwords. It is <span class="bcp14">RECOMMENDED</span> to use a 256-bit key.<a href="#section-9.1-10" class="pilcrow"></a></p>
<p id="section-9.1-11">For key derivation, one can feed a secret key into the <code>pepper</code> parameter for additional security. This forces an attacker to compromise the pepper before they can guess the password. It is <span class="bcp14">RECOMMENDED</span> to use a 256-bit pepper.<a href="#section-9.1-11" class="pilcrow"></a></p>
<p id="section-9.1-12">To bind context information to the output, like a user ID and server ID for password-authenticated key exchange (PAKE) algorithms, the <code>associatedData</code> parameter can be used. However, in most cases, this parameter is not required.<a href="#section-9.1-12" class="pilcrow"></a></p>
<p id="section-9.1-13">Importantly, if multiple values are concatenated to form the <code>associatedData</code> parameter, they <span class="bcp14">MUST</span> be unambiguously encoded. For example, by using fixed-length values or by prepending/appending the little-endian encoded length of each value.<a href="#section-9.1-13" class="pilcrow"></a></p>
<p id="section-9.1-2">It is <span class="bcp14">RECOMMENDED</span> to either restrict password characters to ASCII <span>[<a href="#RFC20" class="cite xref">RFC20</a>]</span> or to apply Unicode Normalization Form C (NFC) <span>[<a href="#RFC8265" class="cite xref">RFC8265</a>]</span> to the password prior to UTF-8 encoding <span>[<a href="#RFC3629" class="cite xref">RFC3629</a>]</span>. The former eliminates and the latter reduces the risk of password characters being encoded differently depending on the keyboard, operating system, and so on. Without taking these steps, a user might not always be able to log on, decrypt a file/disk, etc.<a href="#section-9.1-2" class="pilcrow"></a></p>
<p id="section-9.1-3">If possible, store the password in protected memory and/or erase the password from memory once it is no longer required. Otherwise, an attacker may be able to recover the password from memory or the disk.<a href="#section-9.1-3" class="pilcrow"></a></p>
<p id="section-9.1-4">In all cases, it is <span class="bcp14">RECOMMENDED</span> to use a 128-bit <code>salt</code>. However, a 64-bit <code>salt</code> <span class="bcp14">MAY</span> be used if there are storage constraints. Regardless, the <code>salt</code> length <span class="bcp14">SHOULD NOT</span> vary in your protocol/application.<a href="#section-9.1-4" class="pilcrow"></a></p>
<p id="section-9.1-5">The salt <span class="bcp14">MUST</span> be unique each time you call the function unless verifying a password hash or deriving the same key. It <span class="bcp14">SHOULD</span> be randomly generated using a cryptographically secure pseudorandom number generator (CSPRNG). However, it <span class="bcp14">MAY</span> be deterministic and predictable if random generation is not possible.<a href="#section-9.1-5" class="pilcrow"></a></p>
<p id="section-9.1-6">The salt <span class="bcp14">SHOULD</span> be considered a non-secret value. It <span class="bcp14">SHOULD</span> be stored alongside the password hash for password hashing (see <a href="#encoding-password-hashes" class="auto internal xref">Section 8</a>) or in something like a file header for key derivation. If you have a secret key, the password hash <span class="bcp14">SHOULD</span> be encrypted or the <code>pepper</code> parameter <span class="bcp14">SHOULD</span> be used, as described below.<a href="#section-9.1-6" class="pilcrow"></a></p>
<p id="section-9.1-7">The <code>spaceCost</code>, <code>timeCost</code>, and <code>parallelism</code> parameters <span class="bcp14">MUST</span> be carefully chosen to avoid denial-of-service and user frustration whilst ensuring adequate protection against password cracking. See <a href="#choosing-the-cost-parameters" class="auto internal xref">Section 7</a> for more information about choosing these parameters.<a href="#section-9.1-7" class="pilcrow"></a></p>
<p id="section-9.1-8">Avoid using hardcoded <code>spaceCost</code>/<code>timeCost</code>/<code>parallelism</code> parameters when performing password hashing; these <span class="bcp14">SHOULD</span> be stored as part of the password hash, as described in <a href="#encoding-password-hashes" class="auto internal xref">Section 8</a>. With key derivation, hardcoded parameters are acceptable if protocol versioning is used.<a href="#section-9.1-8" class="pilcrow"></a></p>
<p id="section-9.1-9">For password hashing, it is <span class="bcp14">RECOMMENDED</span> to use a <code>length</code> of 128 or 256 bits. For key derivation, it is <span class="bcp14">RECOMMENDED</span> to use a <code>length</code> of at least 128 bits.<a href="#section-9.1-9" class="pilcrow"></a></p>
<p id="section-9.1-10">If you want to derive multiple keys (e.g. for encryption and authentication), you <span class="bcp14">MUST</span> only run the algorithm once and use different portions of the output as separate keys. Otherwise, the attacker may have an advantage, like only needing to run the algorithm once instead of twice to check a password, and you will be forced to use weaker parameters.<a href="#section-9.1-10" class="pilcrow"></a></p>
<p id="section-9.1-11">For password hashing, it is <span class="bcp14">RECOMMENDED</span> to encrypt password hashes using an unauthenticated encryption algorithm or an authenticated encryption with associated data (AEAD) scheme <span>[<a href="#RFC5116" class="cite xref">RFC5116</a>]</span> before storage. This forces an attacker to compromise the key, which is stored separately from the database, as well as the database before they can begin password cracking. If the key is compromised but the database is not, it can be rotated without having to reset any passwords. It is <span class="bcp14">RECOMMENDED</span> to use a 256-bit key.<a href="#section-9.1-11" class="pilcrow"></a></p>
<p id="section-9.1-12">For key derivation, one can feed a secret key into the <code>pepper</code> parameter for additional security. This forces an attacker to compromise the pepper before they can guess the password. It is <span class="bcp14">RECOMMENDED</span> to use a 256-bit pepper.<a href="#section-9.1-12" class="pilcrow"></a></p>
<p id="section-9.1-13">To bind context information to the output, like a user ID and server ID for password-authenticated key exchange (PAKE) algorithms, the <code>associatedData</code> parameter can be used. However, in most cases, this parameter is not required.<a href="#section-9.1-13" class="pilcrow"></a></p>
<p id="section-9.1-14">Importantly, if multiple values are concatenated to form the <code>associatedData</code> parameter, they <span class="bcp14">MUST</span> be unambiguously encoded. For example, by using fixed-length values or by prepending/appending the little-endian encoded length of each value.<a href="#section-9.1-14" class="pilcrow"></a></p>
</section>
</div>
<div id="security-guarantees">
Expand Down Expand Up @@ -1777,6 +1778,10 @@ <h3 id="name-informative-references">
<dd>
<span class="refAuthor">Ren, L.</span> and <span class="refAuthor">S. Devadas</span>, <span class="refTitle">"Bandwidth Hard Functions for ASIC Resistance"</span>, <span class="refContent">Theory of Cryptography. TCC 2017. Lecture Notes in Computer Science(), vol 10677, pp. 466–492</span>, <time datetime="2017" class="refDate">2017</time>, <span>&lt;<a href="https://doi.org/10.1007/978-3-319-70500-2_16">https://doi.org/10.1007/978-3-319-70500-2_16</a>&gt;</span>. </dd>
<dd class="break"></dd>
<dt id="RFC20">[RFC20]</dt>
<dd>
<span class="refAuthor">Cerf, V.</span>, <span class="refTitle">"ASCII format for network interchange"</span>, <span class="seriesInfo">STD 80</span>, <span class="seriesInfo">RFC 20</span>, <span class="seriesInfo">DOI 10.17487/RFC0020</span>, <time datetime="1969-10" class="refDate">October 1969</time>, <span>&lt;<a href="https://www.rfc-editor.org/rfc/rfc20">https://www.rfc-editor.org/rfc/rfc20</a>&gt;</span>. </dd>
<dd class="break"></dd>
<dt id="RFC5116">[RFC5116]</dt>
<dd>
<span class="refAuthor">McGrew, D.</span>, <span class="refTitle">"An Interface and Algorithms for Authenticated Encryption"</span>, <span class="seriesInfo">RFC 5116</span>, <span class="seriesInfo">DOI 10.17487/RFC5116</span>, <time datetime="2008-01" class="refDate">January 2008</time>, <span>&lt;<a href="https://www.rfc-editor.org/rfc/rfc5116">https://www.rfc-editor.org/rfc/rfc5116</a>&gt;</span>. </dd>
Expand All @@ -1793,6 +1798,10 @@ <h3 id="name-informative-references">
<dd>
<span class="refAuthor">Percival, C.</span> and <span class="refAuthor">S. Josefsson</span>, <span class="refTitle">"The scrypt Password-Based Key Derivation Function"</span>, <span class="seriesInfo">RFC 7914</span>, <span class="seriesInfo">DOI 10.17487/RFC7914</span>, <time datetime="2016-08" class="refDate">August 2016</time>, <span>&lt;<a href="https://www.rfc-editor.org/rfc/rfc7914">https://www.rfc-editor.org/rfc/rfc7914</a>&gt;</span>. </dd>
<dd class="break"></dd>
<dt id="RFC8265">[RFC8265]</dt>
<dd>
<span class="refAuthor">Saint-Andre, P.</span> and <span class="refAuthor">A. Melnikov</span>, <span class="refTitle">"Preparation, Enforcement, and Comparison of Internationalized Strings Representing Usernames and Passwords"</span>, <span class="seriesInfo">RFC 8265</span>, <span class="seriesInfo">DOI 10.17487/RFC8265</span>, <time datetime="2017-10" class="refDate">October 2017</time>, <span>&lt;<a href="https://www.rfc-editor.org/rfc/rfc8265">https://www.rfc-editor.org/rfc/rfc8265</a>&gt;</span>. </dd>
<dd class="break"></dd>
<dt id="RFC9106">[RFC9106]</dt>
<dd>
<span class="refAuthor">Biryukov, A.</span>, <span class="refAuthor">Dinu, D.</span>, <span class="refAuthor">Khovratovich, D.</span>, and <span class="refAuthor">S. Josefsson</span>, <span class="refTitle">"Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications"</span>, <span class="seriesInfo">RFC 9106</span>, <span class="seriesInfo">DOI 10.17487/RFC9106</span>, <time datetime="2021-09" class="refDate">September 2021</time>, <span>&lt;<a href="https://www.rfc-editor.org/rfc/rfc9106">https://www.rfc-editor.org/rfc/rfc9106</a>&gt;</span>. </dd>
Expand Down
18 changes: 18 additions & 0 deletions draft-lucas-bkdf.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -544,6 +544,14 @@ $bkdf-sha256$v=1$m=32,t=3,p=1$ZXhhbXBsZXNhbHQ$cWBD3/d3tEqnuI3LqxLAeKvs+snSicW1GV
NOT be used. Such functions are cryptographically weak and
unsuitable for new protocols.

It is RECOMMENDED to either restrict password characters to ASCII
[RFC20] or to apply Unicode Normalization Form C (NFC) [RFC8265] to
the password prior to UTF-8 encoding [RFC3629]. The former
eliminates and the latter reduces the risk of password characters
being encoded differently depending on the keyboard, operating
system, and so on. Without taking these steps, a user might not
always be able to log on, decrypt a file/disk, etc.

If possible, store the password in protected memory and/or erase the
password from memory once it is no longer required. Otherwise, an
attacker may be able to recover the password from memory or the disk.
Expand Down Expand Up @@ -738,6 +746,10 @@ $bkdf-sha256$v=1$m=32,t=3,p=1$ZXhhbXBsZXNhbHQ$cWBD3/d3tEqnuI3LqxLAeKvs+snSicW1GV
Notes in Computer Science(), vol 10677, pp. 466–492, 2017,
<https://doi.org/10.1007/978-3-319-70500-2_16>.

[RFC20] Cerf, V., "ASCII format for network interchange", STD 80,
RFC 20, DOI 10.17487/RFC0020, October 1969,
<https://www.rfc-editor.org/rfc/rfc20>.

[RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated
Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008,
<https://www.rfc-editor.org/rfc/rfc5116>.
Expand All @@ -756,6 +768,12 @@ $bkdf-sha256$v=1$m=32,t=3,p=1$ZXhhbXBsZXNhbHQ$cWBD3/d3tEqnuI3LqxLAeKvs+snSicW1GV
Key Derivation Function", RFC 7914, DOI 10.17487/RFC7914,
August 2016, <https://www.rfc-editor.org/rfc/rfc7914>.

[RFC8265] Saint-Andre, P. and A. Melnikov, "Preparation,
Enforcement, and Comparison of Internationalized Strings
Representing Usernames and Passwords", RFC 8265,
DOI 10.17487/RFC8265, October 2017,
<https://www.rfc-editor.org/rfc/rfc8265>.

[RFC9106] Biryukov, A., Dinu, D., Khovratovich, D., and S.
Josefsson, "Argon2 Memory-Hard Function for Password
Hashing and Proof-of-Work Applications", RFC 9106,
Expand Down

0 comments on commit f629b18

Please sign in to comment.