From 8a1a40276fb1577f46b89e3aefc17f9e82a933d6 Mon Sep 17 00:00:00 2001
From: Rob Napier <rob@neverwood.org>
Date: Sun, 13 Sep 2020 11:08:06 -0400
Subject: [PATCH] Extract kdf.zig to provide namespace documentation

---
 lib/std/crypto.zig        | 11 ++---------
 lib/std/crypto/kdf.zig    | 17 +++++++++++++++++
 lib/std/crypto/pbkdf2.zig |  2 --
 3 files changed, 19 insertions(+), 11 deletions(-)
 create mode 100644 lib/std/crypto/kdf.zig

diff --git a/lib/std/crypto.zig b/lib/std/crypto.zig
index c375c02906..64ec22894c 100644
--- a/lib/std/crypto.zig
+++ b/lib/std/crypto.zig
@@ -35,14 +35,7 @@ pub const onetimeauth = struct {
     pub const Poly1305 = @import("crypto/poly1305.zig").Poly1305;
 };
 
-/// A Key Derivation Function (KDF) is intended to turn a weak, human generated password into a
-/// strong key, suitable for cryptographic uses. It does this by salting and stretching the
-/// password. Salting injects non-secret random data, so that identical passwords will be converted
-/// into unique keys. Stretching applies a deliberately slow hashing function to frustrate
-/// brute-force guessing.
-pub const kdf = struct {
-    pub const pbkdf2 = @import("crypto/pbkdf2.zig").pbkdf2;
-};
+pub const kdf = @import("crypto/kdf.zig");
 
 /// Core functions, that should rarely be used directly by applications.
 pub const core = struct {
@@ -86,7 +79,7 @@ test "crypto" {
     _ = @import("crypto/gimli.zig");
     _ = @import("crypto/hmac.zig");
     _ = @import("crypto/md5.zig");
-    _ = @import("crypto/pbkdf2.zig");
+    _ = @import("crypto/kdf.zig");
     _ = @import("crypto/poly1305.zig");
     _ = @import("crypto/sha1.zig");
     _ = @import("crypto/sha2.zig");
diff --git a/lib/std/crypto/kdf.zig b/lib/std/crypto/kdf.zig
new file mode 100644
index 0000000000..06bf67bbbd
--- /dev/null
+++ b/lib/std/crypto/kdf.zig
@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2015-2020 Zig Contributors
+// This file is part of [zig](https://ziglang.org/), which is MIT licensed.
+// The MIT license requires this copyright notice to be included in all copies
+// and substantial portions of the software.
+
+//! A Key Derivation Function (KDF) is intended to turn a weak, human generated password into a
+//! strong key, suitable for cryptographic uses. It does this by salting and stretching the
+//! password. Salting injects non-secret random data, so that identical passwords will be converted
+//! into unique keys. Stretching applies a deliberately slow hashing function to frustrate
+//! brute-force guessing.
+
+pub const pbkdf2 = @import("pbkdf2.zig").pbkdf2;
+
+test "kdf" {
+    _ = @import("pbkdf2.zig");
+}
diff --git a/lib/std/crypto/pbkdf2.zig b/lib/std/crypto/pbkdf2.zig
index dfa6b1c022..424e2d6f62 100644
--- a/lib/std/crypto/pbkdf2.zig
+++ b/lib/std/crypto/pbkdf2.zig
@@ -56,8 +56,6 @@ const mem = std.mem;
 ///         the derivedKey. It is common to tune this parameter to achieve approximately 100ms.
 ///
 /// Prf: Pseudo-random function to use. A common choice is std.crypto.auth.hmac.HmacSha256.
-///
-/// PBKDF2 is defined in RFC 2898, and is a recommendation of NIST SP 800-132.
 pub fn pbkdf2(derivedKey: []u8, password: []const u8, salt: []const u8, rounds: u32, comptime Prf: type) void {
     assert(rounds >= 1);