Add E2EE recovery and device rotation

Add signed, encrypted recovery archives with revision checks, account-certified device enrollment and key rotation, and historical signer lookup. Include the database migration, API endpoints, tests, and updated E2EE documentation.
This commit is contained in:
Artemy
2026-10-24 16:54:56 +07:00
parent 2d99c57a3b
commit a049a80e04
15 changed files with 2259 additions and 130 deletions
+23 -7
View File
@@ -17,6 +17,10 @@ public sealed record DeviceKey(
string Signature)
{
public string Fingerprint => E2eeProtocol.Fingerprint(IdentityKey, EncryptionKey);
public string? AccountIdentityKey { get; init; }
public string? AccountSignature { get; init; }
public long Generation { get; init; }
public string? PreviousFingerprint { get; init; }
}
public sealed record ConversationKeys(
@@ -50,6 +54,7 @@ public static class E2eeProtocol
public const int MaxEnvelopeLength = 1_000_000;
public const int MaxDevices = 500;
public const string EncryptedMimeType = "application/vnd.govor.encrypted";
public const string DevicesChangedError = "E2EE_DEVICES_CHANGED";
public static readonly JsonSerializerOptions Json = new() { PropertyNameCaseInsensitive = true };
public static bool IsEncrypted(string? value)
@@ -91,6 +96,8 @@ public static class E2eeProtocol
!signing.VerifyData(KeyBinding(key.EncryptionKey), Convert.FromBase64String(key.Signature),
HashAlgorithmName.SHA256, DSASignatureFormat.IeeeP1363FixedFieldConcatenation))
throw new CryptographicException("Invalid E2EE key binding signature.");
if (key.AccountIdentityKey is not null || key.AccountSignature is not null)
E2eeRecoveryProtocol.VerifyCertificate(key);
}
public static string Fingerprint(string identity, string encryption)
@@ -187,17 +194,26 @@ public static class E2eeProtocol
public static MessagePlaintext Decrypt(string value, DevicePrivateKeys keys, Guid expectedMessage,
Guid expectedConversation, int expectedType, Guid expectedAuthor, Guid? expectedReply = null,
bool? expectedEdit = null)
{
using var signing = SigningPrivateKey(keys);
return DecryptHistory(value, new HistoryKey(Convert.ToBase64String(signing.ExportSubjectPublicKeyInfo()),
keys.EncryptionKey), expectedMessage, expectedConversation, expectedType, expectedAuthor, expectedReply, expectedEdit);
}
public static MessagePlaintext DecryptHistory(string value, HistoryKey keys, Guid expectedMessage,
Guid expectedConversation, int expectedType, Guid expectedAuthor, Guid? expectedReply = null,
bool? expectedEdit = null)
{
var envelope = Verify(value);
if (envelope.MessageId != expectedMessage || envelope.ConversationId != expectedConversation ||
envelope.RecipientType != expectedType || envelope.Sender.UserId != expectedAuthor ||
envelope.ReplyToMessageId != expectedReply ||
(expectedEdit.HasValue && envelope.IsEdit != expectedEdit))
envelope.ReplyToMessageId != expectedReply || (expectedEdit.HasValue && envelope.IsEdit != expectedEdit))
throw new CryptographicException("E2EE message context does not match.");
using var rsa = EncryptionPrivateKey(keys);
using var signing = SigningPrivateKey(keys);
var fingerprint = Fingerprint(Convert.ToBase64String(signing.ExportSubjectPublicKeyInfo()),
Convert.ToBase64String(rsa.ExportSubjectPublicKeyInfo()));
var fingerprint = keys.Fingerprint;
using var rsa = RSA.Create();
var privateBytes = Convert.FromBase64String(keys.EncryptionKey);
try { rsa.ImportPkcs8PrivateKey(privateBytes, out _); }
finally { CryptographicOperations.ZeroMemory(privateBytes); }
if (!envelope.Recipients.Contains(fingerprint, StringComparer.Ordinal))
throw new CryptographicException("This device cannot decrypt this message.");
// Select our recipient explicitly. In particular Windows CNG can throw an
@@ -336,4 +352,4 @@ public static class E2eeProtocol
throw;
}
}
}
}
@@ -0,0 +1,159 @@
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;
using Jose;
namespace Govor.Application.E2ee;
public sealed record RecoveryVault(Guid UserId, long Revision, string IdentityKey, string Ciphertext, string Signature);
public sealed record RecoveryState(RecoveryVault? Vault);
public sealed record SaveRecoveryVault(long ExpectedRevision, string IdentityKey, string Ciphertext, string Signature);
public sealed record HistoryKey(string IdentityKey, string EncryptionKey)
{
private string? _fingerprint;
[JsonIgnore]
public string Fingerprint
{
get
{
if (_fingerprint is not null) return _fingerprint;
using var rsa = RSA.Create();
var bytes = Convert.FromBase64String(EncryptionKey);
try { rsa.ImportPkcs8PrivateKey(bytes, out _); }
finally { CryptographicOperations.ZeroMemory(bytes); }
return _fingerprint = E2eeProtocol.Fingerprint(IdentityKey, Convert.ToBase64String(rsa.ExportSubjectPublicKeyInfo()));
}
}
}
// Recovery is a separate security domain from message encryption. Possession of
// the random 256-bit recovery code authorizes enrollment and archive recovery.
public static class E2eeRecoveryProtocol
{
public const int MaxVaultLength = 4_000_000;
public static string GenerateCode() => Base64Url.Encode(RandomNumberGenerator.GetBytes(32));
public static string GenerateIdentity()
{
using var key = ECDsa.Create(ECCurve.NamedCurves.nistP256);
return Convert.ToBase64String(key.ExportPkcs8PrivateKey());
}
public static string PublicIdentity(string privateKey)
{
using var key = PrivateIdentity(privateKey);
return Convert.ToBase64String(key.ExportSubjectPublicKeyInfo());
}
public static string AccountFingerprint(string identity) =>
Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes("govor-account-v1\n" + identity)));
public static DeviceKey Certify(DeviceKey device, string privateIdentity, long generation = 0,
string? previousFingerprint = null)
{
var certified = device with { AccountIdentityKey = PublicIdentity(privateIdentity),
Generation = generation, PreviousFingerprint = previousFingerprint };
using var key = PrivateIdentity(privateIdentity);
return certified with { AccountSignature = Sign(key, DeviceBinding(certified)) };
}
public static void VerifyCertificate(DeviceKey device)
{
if (device.AccountIdentityKey is null || device.AccountSignature is null || device.Generation < 0 ||
(device.Generation == 0 ? device.PreviousFingerprint is not null : device.PreviousFingerprint?.Length != 64))
throw new CryptographicException("Invalid account device certificate.");
using var key = PublicIdentityKey(device.AccountIdentityKey);
Verify(key, DeviceBinding(device), device.AccountSignature);
}
public static RecoveryVault Seal(Guid user, long revision, string privateIdentity, string code, string plaintext)
{
if (user == Guid.Empty || revision < 1) throw new CryptographicException("Invalid archive context.");
var secret = CodeBytes(code);
string encrypted;
try { encrypted = JWT.Encode(new ArchivePayload(1, user, revision, plaintext), secret, JweAlgorithm.DIR, JweEncryption.A256GCM); }
finally { CryptographicOperations.ZeroMemory(secret); }
var vault = new RecoveryVault(user, revision, PublicIdentity(privateIdentity), encrypted, "");
using var identity = PrivateIdentity(privateIdentity);
return vault with { Signature = Sign(identity, VaultBinding(vault)) };
}
public static string Open(RecoveryVault vault, Guid user, string code)
{
Validate(vault);
if (vault.UserId != user) throw new CryptographicException("Archive belongs to another account.");
var secret = CodeBytes(code);
try
{
var payload = JsonSerializer.Deserialize<ArchivePayload>(
JWT.Decode(vault.Ciphertext, secret, JweAlgorithm.DIR, JweEncryption.A256GCM), E2eeProtocol.Json)
?? throw new CryptographicException("Invalid archive.");
if (payload.Version != 1 || payload.UserId != user || payload.Revision != vault.Revision)
throw new CryptographicException("Archive context mismatch.");
return payload.Plaintext;
}
finally { CryptographicOperations.ZeroMemory(secret); }
}
public static void Validate(RecoveryVault vault)
{
if (vault.UserId == Guid.Empty || vault.Revision < 1 || vault.Ciphertext is null ||
vault.Ciphertext.Length is < 50 or > MaxVaultLength || vault.Signature is null)
throw new CryptographicException("Invalid archive.");
// Fix the algorithms even on the server, which cannot decrypt the archive.
var parts = vault.Ciphertext.Split('.');
if (parts.Length != 5 || parts[1].Length != 0) throw new CryptographicException("Invalid archive JWE.");
using var header = JsonDocument.Parse(Base64Url.Decode(parts[0]));
if (header.RootElement.EnumerateObject().Count() != 2 ||
header.RootElement.GetProperty("alg").GetString() != "dir" ||
header.RootElement.GetProperty("enc").GetString() != "A256GCM")
throw new CryptographicException("Unsupported archive encryption.");
using var key = PublicIdentityKey(vault.IdentityKey);
Verify(key, VaultBinding(vault), vault.Signature);
}
private static byte[] CodeBytes(string code)
{
var bytes = Base64Url.Decode(code.Trim());
if (bytes.Length == 32) return bytes;
CryptographicOperations.ZeroMemory(bytes);
throw new CryptographicException("Invalid recovery code.");
}
private static byte[] DeviceBinding(DeviceKey key) => JsonSerializer.SerializeToUtf8Bytes(new
{ purpose = "govor-account-device-v1", key.UserId, key.SessionId, key.Fingerprint, key.Generation, key.PreviousFingerprint });
private static byte[] VaultBinding(RecoveryVault vault) => JsonSerializer.SerializeToUtf8Bytes(new
{ purpose = "govor-recovery-v1", vault.UserId, vault.Revision, vault.IdentityKey, vault.Ciphertext });
private static string Sign(ECDsa key, byte[] bytes) => Convert.ToBase64String(key.SignData(bytes,
HashAlgorithmName.SHA256, DSASignatureFormat.IeeeP1363FixedFieldConcatenation));
private static void Verify(ECDsa key, byte[] bytes, string signature)
{
if (signature.Length > 100 || !key.VerifyData(bytes, Convert.FromBase64String(signature),
HashAlgorithmName.SHA256, DSASignatureFormat.IeeeP1363FixedFieldConcatenation))
throw new CryptographicException("Invalid account signature.");
}
private static ECDsa PublicIdentityKey(string encoded)
{
if (encoded is null || encoded.Length > 200) throw new CryptographicException("Invalid account identity.");
var key = ECDsa.Create();
try
{
var bytes = Convert.FromBase64String(encoded);
key.ImportSubjectPublicKeyInfo(bytes, out var read);
if (read != bytes.Length || key.ExportParameters(false).Curve.Oid.Value != "1.2.840.10045.3.1.7")
throw new CryptographicException("Invalid account identity curve.");
return key;
}
catch { key.Dispose(); throw; }
}
private static ECDsa PrivateIdentity(string encoded)
{
var bytes = Convert.FromBase64String(encoded);
var key = ECDsa.Create();
try { key.ImportPkcs8PrivateKey(bytes, out _); return key; }
catch { key.Dispose(); throw; }
finally { CryptographicOperations.ZeroMemory(bytes); }
}
private sealed record ArchivePayload(int Version, Guid UserId, long Revision, string Plaintext);
}
+110 -6
View File
@@ -33,7 +33,8 @@ public sealed class E2eeService(GovorDbContext context)
// remain available for offline devices until their session is explicitly revoked.
var sessions = await context.UserCryptoSessions.AsNoTracking().Include(c => c.SignedPreKey)
.Include(c => c.UserSession)
.Where(c => members.Contains(c.UserSession.UserId) && !c.UserSession.IsRevoked)
.Where(c => members.Contains(c.UserSession.UserId) && !c.UserSession.IsRevoked &&
(c.AccountIdentityKey != null || !context.E2eeRecoveryVaults.Any(v => v.UserId == c.UserSession.UserId)))
.Take(E2eeProtocol.MaxDevices + 1).ToListAsync();
var devices = sessions.Select(s => ToDeviceKey(s)).ToArray();
if (devices.Length > E2eeProtocol.MaxDevices)
@@ -49,6 +50,11 @@ public sealed class E2eeService(GovorDbContext context)
if (key.UserId != user || key.SessionId != sessionId)
throw new UnauthorizedAccessException("E2EE key must belong to the current session.");
E2eeProtocol.ValidatePublicKey(key);
var account = await context.E2eeRecoveryVaults.AsNoTracking().SingleOrDefaultAsync(v => v.UserId == user);
if (account is not null && key.AccountIdentityKey != account.IdentityKey)
throw new UnauthorizedAccessException("Restore the account archive before enrolling this device.");
if (key.AccountIdentityKey is not null && account is null)
throw new InvalidOperationException("Upload the encrypted recovery archive before registering device keys.");
var session = await context.UserSessions.Include(s => s.CryptoSession)
.ThenInclude(c => c.SignedPreKey).SingleOrDefaultAsync(s => s.Id == sessionId &&
s.UserId == user && !s.IsRevoked && s.ExpiresAt > DateTime.UtcNow)
@@ -56,10 +62,30 @@ public sealed class E2eeService(GovorDbContext context)
if (session.CryptoSession is not null)
{
var existing = ToDeviceKey(session.CryptoSession, user);
if (existing.Fingerprint != key.Fingerprint)
throw new InvalidOperationException("Session keys are immutable. Create a new session to change devices.");
if (existing.Fingerprint == key.Fingerprint)
{
if (existing.AccountIdentityKey is null && key.AccountIdentityKey is not null && key.Generation == 0)
{
ApplyCertificate(session.CryptoSession, key);
await context.SaveChangesAsync();
}
else if (existing.Generation != key.Generation || existing.AccountIdentityKey != key.AccountIdentityKey)
throw new InvalidOperationException("Device generation mismatch.");
return;
}
if (account is null || key.AccountIdentityKey != account.IdentityKey ||
key.Generation != existing.Generation + 1 || key.PreviousFingerprint != existing.Fingerprint ||
key.IdentityKey != existing.IdentityKey)
throw new InvalidOperationException("A signed, consecutive device key rotation is required.");
var rotating = session.CryptoSession;
rotating.SignedPreKey.PublicSignedPreKey = Convert.FromBase64String(key.EncryptionKey);
rotating.SignedPreKey.SignedPreKeySignature = Convert.FromBase64String(key.Signature);
ApplyCertificate(rotating, key);
await context.SaveChangesAsync();
return;
}
if (key.Generation != 0 || key.PreviousFingerprint is not null)
throw new InvalidOperationException("A newly enrolled device must start at generation zero.");
var cryptoId = Guid.NewGuid();
var crypto = new UserCryptoSession
{
@@ -74,10 +100,82 @@ public sealed class E2eeService(GovorDbContext context)
OneTimePreKeys = new List<OneTimePreKey>()
};
context.UserCryptoSessions.Add(crypto);
ApplyCertificate(crypto, key);
session.CryptoSession = crypto;
await context.SaveChangesAsync();
}
public async Task<RecoveryState> GetRecoveryAsync(Guid user)
{
var value = await context.E2eeRecoveryVaults.AsNoTracking().SingleOrDefaultAsync(v => v.UserId == user);
return new(value is null ? null : new(user, value.Revision, value.IdentityKey, value.Ciphertext, value.Signature));
}
public async Task<RecoveryVault> SaveRecoveryAsync(Guid user, SaveRecoveryVault request)
{
if (request.ExpectedRevision < 0 || request.ExpectedRevision == long.MaxValue)
throw new ArgumentException("Invalid archive revision.");
var value = new RecoveryVault(user, request.ExpectedRevision + 1, request.IdentityKey, request.Ciphertext, request.Signature);
E2eeRecoveryProtocol.Validate(value);
var existing = await context.E2eeRecoveryVaults.SingleOrDefaultAsync(v => v.UserId == user);
if (existing is null)
{
if (request.ExpectedRevision != 0) throw new InvalidOperationException("Archive revision conflict.");
context.E2eeRecoveryVaults.Add(new E2eeRecoveryVault { UserId = user, Revision = value.Revision,
IdentityKey = value.IdentityKey, Ciphertext = value.Ciphertext, Signature = value.Signature });
}
else
{
if (existing.IdentityKey != request.IdentityKey || existing.Revision != request.ExpectedRevision)
throw new InvalidOperationException("Archive identity or revision conflict.");
existing.Revision = value.Revision;
existing.Ciphertext = value.Ciphertext;
existing.Signature = value.Signature;
}
try { await context.SaveChangesAsync(); }
catch (DbUpdateException) { context.ChangeTracker.Clear(); throw new InvalidOperationException("Archive revision conflict."); }
return value;
}
private static void ApplyCertificate(UserCryptoSession crypto, DeviceKey key)
{
crypto.AccountIdentityKey = key.AccountIdentityKey;
crypto.AccountSignature = key.AccountSignature;
crypto.Generation = key.Generation;
crypto.PreviousFingerprint = key.PreviousFingerprint;
}
public async Task<DeviceKey[]> GetOwnDevicesAsync(Guid user) =>
(await context.UserCryptoSessions.AsNoTracking().Include(c => c.SignedPreKey).Include(c => c.UserSession)
.Where(c => c.UserSession.UserId == user).ToListAsync()).Select(c => ToDeviceKey(c)).ToArray();
public async Task CertifyHistoricalDeviceAsync(Guid user, DeviceKey key)
{
E2eeProtocol.ValidatePublicKey(key);
E2eeRecoveryProtocol.VerifyCertificate(key);
var root = await context.E2eeRecoveryVaults.AsNoTracking().SingleOrDefaultAsync(v => v.UserId == user);
var crypto = await context.UserCryptoSessions.Include(c => c.SignedPreKey).Include(c => c.UserSession)
.SingleOrDefaultAsync(c => c.UserSessionId == key.SessionId && c.UserSession.UserId == user);
if (root is null || root.IdentityKey != key.AccountIdentityKey || key.UserId != user || crypto is null)
throw new UnauthorizedAccessException("Only the account owner may certify historical device keys.");
var stored = ToDeviceKey(crypto);
if (stored.Fingerprint != key.Fingerprint || stored.Generation != key.Generation ||
stored.PreviousFingerprint != key.PreviousFingerprint)
throw new InvalidOperationException("Historical device keys cannot be changed.");
ApplyCertificate(crypto, key);
await context.SaveChangesAsync();
}
public async Task<DeviceKey?> GetHistoricalSignerAsync(Guid user, Guid conversation, RecipientType type, Guid session)
{
if (!await context.HasChatAccessAsync(user, conversation, type)) throw new UnauthorizedAccessException();
var crypto = await context.UserCryptoSessions.AsNoTracking().Include(c => c.SignedPreKey).Include(c => c.UserSession)
.SingleOrDefaultAsync(c => c.UserSessionId == session);
if (crypto is null || !await context.Messages.AnyAsync(m => m.RecipientId == conversation &&
m.RecipientType == type && m.SenderId == crypto.UserSession.UserId)) return null;
return ToDeviceKey(crypto);
}
public async Task<EncryptedMessage?> ValidateAsync(string content, Guid sender, Guid conversation,
RecipientType type, Guid? replyTo, Guid[] media, Guid? editedMessage = null)
{
@@ -104,12 +202,14 @@ public sealed class E2eeService(GovorDbContext context)
.ThenInclude(c => c.SignedPreKey).SingleOrDefaultAsync(s => s.Id == envelope.Sender.SessionId &&
s.UserId == sender && !s.IsRevoked && s.ExpiresAt > DateTime.UtcNow);
if (signingSession?.CryptoSession is null ||
ToDeviceKey(signingSession.CryptoSession, sender).Fingerprint != envelope.Sender.Fingerprint)
ToDeviceKey(signingSession.CryptoSession, sender).Fingerprint != envelope.Sender.Fingerprint ||
signingSession.CryptoSession.AccountIdentityKey != envelope.Sender.AccountIdentityKey ||
signingSession.CryptoSession.Generation != envelope.Sender.Generation)
throw new UnauthorizedAccessException("E2EE signing device is unknown or revoked.");
var directory = await GetConversationKeysAsync(sender, conversation, type);
var expected = directory.Devices.Select(k => k.Fingerprint).Distinct().Order(StringComparer.Ordinal);
if (!expected.SequenceEqual(envelope.Recipients.Order(StringComparer.Ordinal)))
throw new ArgumentException("Conversation devices changed. Reload and verify the recipient keys.");
throw new ArgumentException(E2eeProtocol.DevicesChangedError);
return envelope;
}
@@ -117,5 +217,9 @@ public sealed class E2eeService(GovorDbContext context)
new(user ?? session.UserSession.UserId, session.UserSessionId,
Convert.ToBase64String(session.PublicIdentityKey),
Convert.ToBase64String(session.SignedPreKey.PublicSignedPreKey),
Convert.ToBase64String(session.SignedPreKey.SignedPreKeySignature));
Convert.ToBase64String(session.SignedPreKey.SignedPreKeySignature))
{
AccountIdentityKey = session.AccountIdentityKey, AccountSignature = session.AccountSignature,
Generation = session.Generation, PreviousFingerprint = session.PreviousFingerprint
};
}