std.crypto: better names for everything in utils

std.crypto has quite a few instances of breaking naming conventions.
This is the beginning of an effort to address that.

Deprecates `std.crypto.utils`.

Author: andrewrk

doc/langref.html.in

@@ -5053,7 +5053,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
       It may have any alignment, and it may have any element type.</p>
       <p>{#syntax#}elem{#endsyntax#} is coerced to the element type of {#syntax#}dest{#endsyntax#}.</p>
       <p>For securely zeroing out sensitive contents from memory, you should use
-      {#syntax#}std.crypto.utils.secureZero{#endsyntax#}</p>
+      {#syntax#}std.crypto.secureZero{#endsyntax#}</p>
       {#header_close#}
 
       {#header_open|@min#}

lib/std/crypto.zig

@@ -2,6 +2,8 @@
 
 const root = @import("root");
 
+pub const timing_safe = @import("crypto/timing_safe.zig");
+
 /// Authenticated Encryption with Associated Data
 pub const aead = struct {
     pub const aegis = struct {
@@ -180,8 +182,6 @@ pub const nacl = struct {
     pub const SealedBox = salsa20.SealedBox;
 };
 
-pub const utils = @import("crypto/utils.zig");
-
 /// Finite-field arithmetic.
 pub const ff = @import("crypto/ff.zig");
 
@@ -301,7 +301,8 @@ test {
     _ = nacl.SecretBox;
     _ = nacl.SealedBox;
 
-    _ = utils;
+    _ = secureZero;
+    _ = timing_safe;
     _ = ff;
     _ = random;
     _ = errors;
@@ -353,3 +354,36 @@ test "issue #4532: no index out of bounds" {
         try std.testing.expectEqual(out1, out2);
     }
 }
+
+/// Sets a slice to zeroes.
+/// Prevents the store from being optimized out.
+pub inline fn secureZero(comptime T: type, s: []volatile T) void {
+    @memset(s, 0);
+}
+
+test secureZero {
+    var a = [_]u8{0xfe} ** 8;
+    var b = [_]u8{0xfe} ** 8;
+
+    @memset(&a, 0);
+    secureZero(u8, &b);
+
+    try std.testing.expectEqualSlices(u8, &a, &b);
+}
+
+/// Deprecated in favor of `std.crypto`. To be removed after Zig 0.14.0 is released.
+///
+/// As a reminder, never use "utils" in a namespace (in any programming language).
+/// https://ziglang.org/documentation/0.13.0/#Avoid-Redundancy-in-Names
+pub const utils = struct {
+    /// Deprecated in favor of `std.crypto.secureZero`.
+    pub const secureZero = std.crypto.secureZero;
+    /// Deprecated in favor of `std.crypto.timing_safe.eql`.
+    pub const timingSafeEql = timing_safe.eql;
+    /// Deprecated in favor of `std.crypto.timing_safe.compare`.
+    pub const timingSafeCompare = timing_safe.compare;
+    /// Deprecated in favor of `std.crypto.timing_safe.add`.
+    pub const timingSafeAdd = timing_safe.add;
+    /// Deprecated in favor of `std.crypto.timing_safe.sub`.
+    pub const timingSafeSub = timing_safe.sub;
+};

lib/std/crypto/aegis.zig

@@ -208,9 +208,9 @@ fn Aegis128LGeneric(comptime tag_bits: u9) type {
                 blocks[4] = blocks[4].xorBlocks(AesBlock.fromBytes(dst[16..32]));
             }
             var computed_tag = state.mac(tag_bits, ad.len, m.len);
-            const verify = crypto.utils.timingSafeEql([tag_length]u8, computed_tag, tag);
+            const verify = crypto.timing_safe.eql([tag_length]u8, computed_tag, tag);
             if (!verify) {
-                crypto.utils.secureZero(u8, &computed_tag);
+                crypto.secureZero(u8, &computed_tag);
                 @memset(m, undefined);
                 return error.AuthenticationFailed;
             }
@@ -390,9 +390,9 @@ fn Aegis256Generic(comptime tag_bits: u9) type {
                 blocks[0] = blocks[0].xorBlocks(AesBlock.fromBytes(&dst));
             }
             var computed_tag = state.mac(tag_bits, ad.len, m.len);
-            const verify = crypto.utils.timingSafeEql([tag_length]u8, computed_tag, tag);
+            const verify = crypto.timing_safe.eql([tag_length]u8, computed_tag, tag);
             if (!verify) {
-                crypto.utils.secureZero(u8, &computed_tag);
+                crypto.secureZero(u8, &computed_tag);
                 @memset(m, undefined);
                 return error.AuthenticationFailed;
             }

lib/std/crypto/aes_gcm.zig

@@ -95,9 +95,9 @@ fn AesGcm(comptime Aes: anytype) type {
                 computed_tag[i] ^= x;
             }
 
-            const verify = crypto.utils.timingSafeEql([tag_length]u8, computed_tag, tag);
+            const verify = crypto.timing_safe.eql([tag_length]u8, computed_tag, tag);
             if (!verify) {
-                crypto.utils.secureZero(u8, &computed_tag);
+                crypto.secureZero(u8, &computed_tag);
                 @memset(m, undefined);
                 return error.AuthenticationFailed;
             }

lib/std/crypto/aes_ocb.zig

@@ -234,9 +234,9 @@ fn AesOcb(comptime Aes: anytype) type {
             var e = xorBlocks(xorBlocks(sum, offset), lx.dol);
             aes_enc_ctx.encrypt(&e, &e);
             var computed_tag = xorBlocks(e, hash(aes_enc_ctx, &lx, ad));
-            const verify = crypto.utils.timingSafeEql([tag_length]u8, computed_tag, tag);
+            const verify = crypto.timing_safe.eql([tag_length]u8, computed_tag, tag);
             if (!verify) {
-                crypto.utils.secureZero(u8, &computed_tag);
+                crypto.secureZero(u8, &computed_tag);
                 @memset(m, undefined);
                 return error.AuthenticationFailed;
             }

lib/std/crypto/ascon.zig

@@ -152,7 +152,7 @@ pub fn State(comptime endian: std.builtin.Endian) type {
 
         /// Clear the entire state, disabling compiler optimizations.
         pub fn secureZero(self: *Self) void {
-            std.crypto.utils.secureZero(u64, &self.st);
+            std.crypto.secureZero(u64, &self.st);
         }
 
         /// Apply a reduced-round permutation to the state.

lib/std/crypto/bcrypt.zig

@@ -9,7 +9,6 @@ const pwhash = crypto.pwhash;
 const testing = std.testing;
 const HmacSha512 = crypto.auth.hmac.sha2.HmacSha512;
 const Sha512 = crypto.hash.sha2.Sha512;
-const utils = crypto.utils;
 
 const phc_format = @import("phc_encoding.zig");
 
@@ -446,7 +445,7 @@ pub fn bcrypt(
         state.expand0(passwordZ);
         state.expand0(salt[0..]);
     }
-    utils.secureZero(u8, &password_buf);
+    crypto.secureZero(u8, &password_buf);
 
     var cdata = [6]u32{ 0x4f727068, 0x65616e42, 0x65686f6c, 0x64657253, 0x63727944, 0x6f756274 }; // "OrpheanBeholderScryDoubt"
     k = 0;
@@ -556,8 +555,8 @@ const pbkdf_prf = struct {
         }
 
         // zap
-        crypto.utils.secureZero(u32, &cdata);
-        crypto.utils.secureZero(u32, &state.subkeys);
+        crypto.secureZero(u32, &cdata);
+        crypto.secureZero(u32, &state.subkeys);
 
         return out;
     }

lib/std/crypto/chacha20.zig

@@ -714,9 +714,9 @@ fn ChaChaPoly1305(comptime rounds_nb: usize) type {
             var computed_tag: [16]u8 = undefined;
             mac.final(computed_tag[0..]);
 
-            const verify = crypto.utils.timingSafeEql([tag_length]u8, computed_tag, tag);
+            const verify = crypto.timing_safe.eql([tag_length]u8, computed_tag, tag);
             if (!verify) {
-                crypto.utils.secureZero(u8, &computed_tag);
+                crypto.secureZero(u8, &computed_tag);
                 @memset(m, undefined);
                 return error.AuthenticationFailed;
             }

lib/std/crypto/ff.zig

@@ -225,12 +225,12 @@ pub fn Uint(comptime max_bits: comptime_int) type {
 
         /// Returns `true` if both integers are equal.
         pub fn eql(x: Self, y: Self) bool {
-            return crypto.utils.timingSafeEql([max_limbs_count]Limb, x.limbs_buffer, y.limbs_buffer);
+            return crypto.timing_safe.eql([max_limbs_count]Limb, x.limbs_buffer, y.limbs_buffer);
         }
 
         /// Compares two integers.
         pub fn compare(x: Self, y: Self) math.Order {
-            return crypto.utils.timingSafeCompare(
+            return crypto.timing_safe.compare(
                 Limb,
                 x.limbsConst(),
                 y.limbsConst(),

lib/std/crypto/ghash_polyval.zig

@@ -3,7 +3,6 @@ const builtin = @import("builtin");
 const assert = std.debug.assert;
 const math = std.math;
 const mem = std.mem;
-const utils = std.crypto.utils;
 
 const Precomp = u128;
 
@@ -403,7 +402,7 @@ fn Hash(comptime endian: std.builtin.Endian, comptime shift_key: bool) type {
             st.pad();
             mem.writeInt(u128, out[0..16], st.acc, endian);
 
-            utils.secureZero(u8, @as([*]u8, @ptrCast(st))[0..@sizeOf(Self)]);
+            std.crypto.secureZero(u8, @as([*]u8, @ptrCast(st))[0..@sizeOf(Self)]);
         }
 
         /// Compute the GHASH of a message.

lib/std/crypto/isap.zig

@@ -158,9 +158,9 @@ pub const IsapA128A = struct {
     /// Contents of `m` are undefined if an error is returned.
     pub fn decrypt(m: []u8, c: []const u8, tag: [tag_length]u8, ad: []const u8, npub: [nonce_length]u8, key: [key_length]u8) AuthenticationError!void {
         var computed_tag = mac(c, ad, npub, key);
-        const verify = crypto.utils.timingSafeEql([tag_length]u8, computed_tag, tag);
+        const verify = crypto.timing_safe.eql([tag_length]u8, computed_tag, tag);
         if (!verify) {
-            crypto.utils.secureZero(u8, &computed_tag);
+            crypto.secureZero(u8, &computed_tag);
             @memset(m, undefined);
             return error.AuthenticationFailed;
         }

lib/std/crypto/keccak_p.zig

@@ -132,7 +132,7 @@ pub fn KeccakF(comptime f: u11) type {
 
         /// Clear the entire state, disabling compiler optimizations.
         pub fn secureZero(self: *Self) void {
-            std.crypto.utils.secureZero(T, &self.st);
+            std.crypto.secureZero(T, &self.st);
         }
 
         inline fn round(self: *Self, rc: T) void {

lib/std/crypto/ml_kem.zig

@@ -1508,7 +1508,7 @@ fn Mat(comptime K: u8) type {
 
 // Returns `true` if a ≠ b.
 fn ctneq(comptime len: usize, a: [len]u8, b: [len]u8) u1 {
-    return 1 - @intFromBool(crypto.utils.timingSafeEql([len]u8, a, b));
+    return 1 - @intFromBool(crypto.timing_safe.eql([len]u8, a, b));
 }
 
 // Copy src into dst given b = 1.

lib/std/crypto/pcurves/common.zig

@@ -57,7 +57,7 @@ pub fn Field(comptime params: FieldParams) type {
                 mem.writeInt(std.meta.Int(.unsigned, encoded_length * 8), &fos, field_order, .little);
                 break :fos fos;
             };
-            if (crypto.utils.timingSafeCompare(u8, &s, &field_order_s, .little) != .lt) {
+            if (crypto.timing_safe.compare(u8, &s, &field_order_s, .little) != .lt) {
                 return error.NonCanonical;
             }
         }

lib/std/crypto/poly1305.zig

@@ -1,5 +1,4 @@
 const std = @import("../std.zig");
-const utils = std.crypto.utils;
 const mem = std.mem;
 const mulWide = std.math.mulWide;
 
@@ -185,7 +184,7 @@ pub const Poly1305 = struct {
         mem.writeInt(u64, out[0..8], st.h[0], .little);
         mem.writeInt(u64, out[8..16], st.h[1], .little);
 
-        utils.secureZero(u8, @as([*]u8, @ptrCast(st))[0..@sizeOf(Poly1305)]);
+        std.crypto.secureZero(u8, @as([*]u8, @ptrCast(st))[0..@sizeOf(Poly1305)]);
     }
 
     pub fn create(out: *[mac_length]u8, msg: []const u8, key: *const [key_length]u8) void {

lib/std/crypto/salsa20.zig

@@ -4,7 +4,6 @@ const crypto = std.crypto;
 const debug = std.debug;
 const math = std.math;
 const mem = std.mem;
-const utils = std.crypto.utils;
 
 const Poly1305 = crypto.onetimeauth.Poly1305;
 const Blake2b = crypto.hash.blake2.Blake2b;
@@ -419,9 +418,9 @@ pub const XSalsa20Poly1305 = struct {
         var computed_tag: [tag_length]u8 = undefined;
         mac.final(&computed_tag);
 
-        const verify = utils.timingSafeEql([tag_length]u8, computed_tag, tag);
+        const verify = crypto.timing_safe.eql([tag_length]u8, computed_tag, tag);
         if (!verify) {
-            utils.secureZero(u8, &computed_tag);
+            crypto.secureZero(u8, &computed_tag);
             @memset(m, undefined);
             return error.AuthenticationFailed;
         }
@@ -540,7 +539,7 @@ pub const SealedBox = struct {
         const nonce = createNonce(ekp.public_key, public_key);
         c[0..public_length].* = ekp.public_key;
         try Box.seal(c[Box.public_length..], m, nonce, public_key, ekp.secret_key);
-        utils.secureZero(u8, ekp.secret_key[0..]);
+        crypto.secureZero(u8, ekp.secret_key[0..]);
     }
 
     /// Decrypt a message using a key pair.