std.crypto.aes_gcm_siv.Aes128GcmSiv
类型
std.crypto.aes_gcm_siv.Aes256GcmSiv
类型
std.crypto.aes_gcm_siv.AesGcmSiv
类型函数
AES-GCM-SIV:即使意外复用 nonce,仍保持安全的认证加密。
作用:加密数据并防止篡改。也可附带未加密的元数据,例如报头;这些数据会经过认证,但不会加密。
适用场景:
- 无法保证 nonce 唯一时,尽管仍应尽量使用唯一 nonce。
应改用普通 AES-GCM 的场景:
- 能够保证 nonce 唯一,例如使用计数器。
- 需要稍高性能。
安全性:若使用相同密钥时意外复用 nonce,AES-GCM-SIV 只会泄露两条消息是否相同。而普通 AES-GCM 在此情况下会灾难性失效,可能泄露认证密钥。
性能:由于增加了密钥派生步骤,速度略慢于 AES-GCM。
定义于 RFC 8452。
fn AesGcmSiv(comptime Aes: anytype) type
std.crypto.aes_gcm_siv.AesGcmSiv.decrypt
函数
使用 AES-GCM-SIV 解密并认证消息。
m:用于写入解密数据的消息缓冲区。
c:待解密密文。
tag:认证标签。
ad:关联数据。
npub:nonce。
key:解密密钥。
断言 c.len == m.len。
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
参数
错误
- AuthenticationFailed AuthenticationError
std.crypto.aes_gcm_siv.AesGcmSiv.deriveKeys
函数
从主密钥与 nonce 派生认证密钥和消息加密密钥。 实现 RFC 8452 第 4 节规定的密钥派生。 生成用于 POLYVAL 的 128 位认证密钥,以及消息加密密钥,后者根据 AES 变体为 128 位或 256 位。
fn deriveKeys(message_key: *[key_length]u8, auth_key: *[16]u8, key: [key_length]u8, nonce: [nonce_length]u8) void
参数
std.crypto.aes_gcm_siv.AesGcmSiv.encrypt
函数
使用 AES-GCM-SIV 加密并认证消息。
c:用于写入加密数据的密文缓冲区。
tag:用于写入计算所得标签的认证标签缓冲区。
m:要加密的明文消息。
ad:要认证的关联数据。
npub:加密使用的 nonce。
key:加密密钥。
pub fn encrypt(c: []u8, tag: *[tag_length]u8, m: []const u8, ad: []const u8, npub: [nonce_length]u8, key: [key_length]u8) void
参数
c: []u8
tag: *[tag_length]u8
m: []const u8
ad: []const u8
npub: [nonce_length]u8
key: [key_length]u8
std.crypto.aes_gcm_siv.AesGcmSiv.key_length
常量
std.crypto.aes_gcm_siv.AesGcmSiv.nonce_length
常量
std.crypto.aes_gcm_siv.AesGcmSiv.tag_length
常量
std.crypto.aes_gcm_siv.AesGcmSiv.zeros
常量
[16]u8
std.crypto.aes_gcm_siv.assert
别名
别名目标 std.debug.assert
std.crypto.aes_gcm_siv.AuthenticationError
别名
std.crypto.aes_gcm_siv.crypto
别名
别名目标 std.crypto
std.crypto.aes_gcm_siv.debug
别名
别名目标 std.debug
std.crypto.aes_gcm_siv.htest
常量
std.crypto.aes_gcm_siv.math
别名
别名目标 std.math
std.crypto.aes_gcm_siv.mem
别名
别名目标 std.mem
std.crypto.aes_gcm_siv.modes
别名
别名目标 std.crypto.modes
std.crypto.aes_gcm_siv.Polyval
别名
std.crypto.aes_gcm_siv.std
别名
别名目标 std
std.crypto.aes_gcm_siv.testing
别名
别名目标 std.testing
源码
std/crypto/aes_gcm_siv.zig
const std = @import("std");
const assert = std.debug.assert;
const crypto = std.crypto;
const debug = std.debug;
const mem = std.mem;
const math = std.math;
const modes = @import("modes.zig");
const Polyval = @import("ghash_polyval.zig").Polyval;
const AuthenticationError = crypto.errors.AuthenticationError;
pub const Aes128GcmSiv = AesGcmSiv(crypto.core.aes.Aes128);
pub const Aes256GcmSiv = AesGcmSiv(crypto.core.aes.Aes256);
/// AES-GCM-SIV:即使意外复用 nonce,仍保持安全的认证加密。
///
/// 作用:加密数据并防止篡改。也可附带未加密的元数据,例如报头;这些数据会经过认证,但不会加密。
///
/// 适用场景:
/// - 无法保证 nonce 唯一时,尽管仍应尽量使用唯一 nonce。
///
/// 应改用普通 AES-GCM 的场景:
/// - 能够保证 nonce 唯一,例如使用计数器。
/// - 需要稍高性能。
///
/// 安全性:若使用相同密钥时意外复用 nonce,AES-GCM-SIV 只会泄露两条消息是否相同。而普通 AES-GCM 在此情况下会灾难性失效,可能泄露认证密钥。
///
/// 性能:由于增加了密钥派生步骤,速度略慢于 AES-GCM。
///
/// 定义于 RFC 8452。
///
///
///
fn AesGcmSiv(comptime Aes: anytype) type {
debug.assert(Aes.block.block_length == 16);
return struct {
pub const tag_length = 16;
pub const nonce_length = 12;
pub const key_length = Aes.key_bits / 8;
const zeros: [16]u8 = @splat(0);
/// 从主密钥与 nonce 派生认证密钥和消息加密密钥。
/// 实现 RFC 8452 第 4 节规定的密钥派生。
/// 生成用于 POLYVAL 的 128 位认证密钥,以及消息加密密钥,后者根据 AES 变体为 128 位或 256 位。
///
fn deriveKeys(message_key: *[key_length]u8, auth_key: *[16]u8, key: [key_length]u8, nonce: [nonce_length]u8) void {
const aes = Aes.initEnc(key);
// 按 RFC 8452 第 4 节派生认证密钥和消息密钥
// 每次加密产生 16 字节,但每个块只使用前 8 字节
if (key_length == 16) {
// AES-128-GCM-SIV:并行处理 4 个分组
var key_blocks: [4 * 16]u8 = undefined;
var cipher_outs: [4 * 16]u8 = undefined;
// 使用计数器 0–3 和 nonce 设置全部 4 个块
inline for (0..4) |i| {
mem.writeInt(u32, key_blocks[i * 16 ..][0..4], @intCast(i), .little);
key_blocks[i * 16 + 4 .. i * 16 + 16].* = nonce;
}
// 并行加密全部 4 个分组
aes.encryptWide(4, &cipher_outs, &key_blocks);
// 提取密钥材料(每个数据块的前 8 字节)。
@memcpy(auth_key[0..8], cipher_outs[0..8]);
@memcpy(auth_key[8..16], cipher_outs[16..24]);
@memcpy(message_key[0..8], cipher_outs[32..40]);
@memcpy(message_key[8..16], cipher_outs[48..56]);
} else {
// AES-256-GCM-SIV:并行处理 6 个块
var key_blocks: [6 * 16]u8 = undefined;
var cipher_outs: [6 * 16]u8 = undefined;
// 设置全部 6 个块,计数器为 0-5,并设置 nonce
inline for (0..6) |i| {
mem.writeInt(u32, key_blocks[i * 16 ..][0..4], @intCast(i), .little);
key_blocks[i * 16 + 4 .. i * 16 + 16].* = nonce;
}
// 并行加密全部 6 个块
aes.encryptWide(6, &cipher_outs, &key_blocks);
// 提取密钥材料(每个数据块的前 8 字节)。
@memcpy(auth_key[0..8], cipher_outs[0..8]);
@memcpy(auth_key[8..16], cipher_outs[16..24]);
@memcpy(message_key[0..8], cipher_outs[32..40]);
@memcpy(message_key[8..16], cipher_outs[48..56]);
@memcpy(message_key[16..24], cipher_outs[64..72]);
@memcpy(message_key[24..32], cipher_outs[80..88]);
}
}
/// 使用 AES-GCM-SIV 加密并认证消息。
///
/// `c`:用于写入加密数据的密文缓冲区。
/// `tag`:用于写入计算所得标签的认证标签缓冲区。
/// `m`:要加密的明文消息。
/// `ad`:要认证的关联数据。
/// `npub`:加密使用的 nonce。
/// `key`:加密密钥。
pub fn encrypt(c: []u8, tag: *[tag_length]u8, m: []const u8, ad: []const u8, npub: [nonce_length]u8, key: [key_length]u8) void {
debug.assert(c.len == m.len);
debug.assert(m.len <= (1 << 36));
debug.assert(ad.len <= (1 << 36));
var auth_key: [16]u8 = undefined;
var message_key: [key_length]u8 = undefined;
deriveKeys(&message_key, &auth_key, key, npub);
// 对附加数据和明文计算 POLYVAL
const block_count = (math.divCeil(usize, ad.len, Polyval.block_length) catch unreachable) +
(math.divCeil(usize, m.len, Polyval.block_length) catch unreachable) + 1;
var mac = Polyval.initForBlockCount(&auth_key, block_count);
// 处理附加数据
mac.update(ad);
mac.pad();
// 处理明文
mac.update(m);
mac.pad();
// 长度块
var length_block: [16]u8 = undefined;
mem.writeInt(u64, length_block[0..8], @as(u64, ad.len) * 8, .little);
mem.writeInt(u64, length_block[8..16], @as(u64, m.len) * 8, .little);
mac.update(&length_block);
// 获取 POLYVAL 结果
var s: [16]u8 = undefined;
mac.final(&s);
// 与 nonce 异或以获得预备标签
for (npub, 0..) |b, i| {
s[i] ^= b;
}
// 清除最后一个字节的最高有效位
s[15] &= 0x7f;
// 加密以获取标签
const tag_aes = Aes.initEnc(message_key);
tag_aes.encrypt(tag, &s);
// 使用标签作为 CTR 模式的初始计数器
var counter: [16]u8 = tag.*;
counter[15] |= 0x80; // 设置最高有效位
// 使用具有 32 位小端计数器的 CTR 模式加密消息
const aes_ctx = Aes.initEnc(message_key);
modes.ctrSlice(@TypeOf(aes_ctx), aes_ctx, c, m, counter, .little, 0, 4);
}
/// 使用 AES-GCM-SIV 解密并认证消息。
///
/// `m`:用于写入解密数据的消息缓冲区。
/// `c`:待解密密文。
/// `tag`:认证标签。
/// `ad`:关联数据。
/// `npub`:nonce。
/// `key`:解密密钥。
/// 断言 `c.len == m.len`。
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 {
assert(c.len == m.len);
assert(c.len <= (1 << 36));
assert(ad.len <= (1 << 36));
var auth_key: [16]u8 = undefined;
var message_key: [key_length]u8 = undefined;
deriveKeys(&message_key, &auth_key, key, npub);
// 使用带 32 位小端序计数器的 CTR 模式解密消息。
var counter: [16]u8 = tag;
counter[15] |= 0x80; // 设置最高有效位
const aes_ctx = Aes.initEnc(message_key);
modes.ctrSlice(@TypeOf(aes_ctx), aes_ctx, m, c, counter, .little, 0, 4);
// 通过重新计算 POLYVAL 验证标签
const block_count = (math.divCeil(usize, ad.len, Polyval.block_length) catch unreachable) +
(math.divCeil(usize, m.len, Polyval.block_length) catch unreachable) + 1;
var mac = Polyval.initForBlockCount(&auth_key, block_count);
// 处理附加数据
mac.update(ad);
mac.pad();
// 处理解密后的明文
mac.update(m);
mac.pad();
// 长度块
var length_block: [16]u8 = undefined;
mem.writeInt(u64, length_block[0..8], @as(u64, ad.len) * 8, .little);
mem.writeInt(u64, length_block[8..16], @as(u64, m.len) * 8, .little);
mac.update(&length_block);
// 获取 POLYVAL 结果
var s: [16]u8 = undefined;
mac.final(&s);
// 与 nonce 异或以获得预备标签
for (npub, 0..) |b, i| {
s[i] ^= b;
}
// 清除最后一个字节的最高有效位
s[15] &= 0x7f;
// 通过加密获得预期标签
const tag_aes = Aes.initEnc(message_key);
var computed_tag: [tag_length]u8 = undefined;
tag_aes.encrypt(&computed_tag, &s);
// 验证标签
const verify = crypto.timing_safe.eql([tag_length]u8, computed_tag, tag);
if (!verify) {
crypto.secureZero(u8, &computed_tag);
@memset(m, undefined);
return error.AuthenticationFailed;
}
}
};
}
const htest = @import("test.zig");
const testing = std.testing;
test "Aes128GcmSiv - RFC 8452 Test Vector 1" {
// 来自 RFC 8452 附录 C.1 的测试向量
const key = [_]u8{
0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
};
const nonce = [_]u8{
0x03, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
};
const ad = "";
const m = "";
var c: [m.len]u8 = undefined;
var tag: [Aes128GcmSiv.tag_length]u8 = undefined;
Aes128GcmSiv.encrypt(&c, &tag, m, ad, nonce, key);
try htest.assertEqual("dc20e2d83f25705bb49e439eca56de25", &tag);
}
test "Aes128GcmSiv - RFC 8452 Test Vector 2" {
// 来自 RFC 8452 附录 C.1 的测试向量
const key = [_]u8{
0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
};
const nonce = [_]u8{
0x03, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
};
const plaintext = [_]u8{
0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
};
const ad = "";
var c: [plaintext.len]u8 = undefined;
var tag: [Aes128GcmSiv.tag_length]u8 = undefined;
Aes128GcmSiv.encrypt(&c, &tag, &plaintext, ad, nonce, key);
try htest.assertEqual("b5d839330ac7b786", &c);
try htest.assertEqual("578782fff6013b815b287c22493a364c", &tag);
var m2: [plaintext.len]u8 = undefined;
try Aes128GcmSiv.decrypt(&m2, &c, tag, ad, nonce, key);
try testing.expectEqualSlices(u8, &plaintext, &m2);
}
test "Aes128GcmSiv - RFC 8452 Test Vector 3" {
// 来自 RFC 8452 附录 C.1 的测试向量
const key = [_]u8{
0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
};
const nonce = [_]u8{
0x03, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
};
const plaintext = [_]u8{
0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
};
const ad = "";
var c: [plaintext.len]u8 = undefined;
var tag: [Aes128GcmSiv.tag_length]u8 = undefined;
Aes128GcmSiv.encrypt(&c, &tag, &plaintext, ad, nonce, key);
try htest.assertEqual("7323ea61d05932260047d942", &c);
try htest.assertEqual("a4978db357391a0bc4fdec8b0d106639", &tag);
var m2: [plaintext.len]u8 = undefined;
try Aes128GcmSiv.decrypt(&m2, &c, tag, ad, nonce, key);
try testing.expectEqualSlices(u8, &plaintext, &m2);
}
test "Aes256GcmSiv - RFC 8452 Test Vector" {
// 来自 RFC 8452 附录 C.2 的测试向量
const key = [_]u8{
0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
};
const nonce = [_]u8{
0x03, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
};
const ad = "";
const m = "";
var c: [m.len]u8 = undefined;
var tag: [Aes256GcmSiv.tag_length]u8 = undefined;
Aes256GcmSiv.encrypt(&c, &tag, m, ad, nonce, key);
try htest.assertEqual("07f5f4169bbf55a8400cd47ea6fd400f", &tag);
}
test "Aes128GcmSiv - Decrypt with wrong tag" {
const key: [Aes128GcmSiv.key_length]u8 = @splat(0x69);
const nonce: [Aes128GcmSiv.nonce_length]u8 = @splat(0x42);
const m = "Test message";
const ad = "";
var c: [m.len]u8 = undefined;
var tag: [Aes128GcmSiv.tag_length]u8 = undefined;
Aes128GcmSiv.encrypt(&c, &tag, m, ad, nonce, key);
// 破坏标签
tag[0] ^= 0x01;
var m2: [m.len]u8 = undefined;
try testing.expectError(error.AuthenticationFailed, Aes128GcmSiv.decrypt(&m2, &c, tag, ad, nonce, key));
}