Public Access
Add the server client and client-side enrollment
A typed client over DodoSSH.Contracts, and the orchestration that turns a passphrase into an enrolled identity: generate keys, have the identity provider sign over them, wrap the bundle three ways, create the personal vault, publish. Ordering here is forced, not chosen. The secret bundle's AAD binds to the server-assigned user id, so /me has to be read before anything can be wrapped -- which is exactly why /me provisions the account and returns its id even while reporting that enrollment is required. That constraint was designed into the server earlier; this is the first code that depends on it. The grant tuple now has a real canonical encoding (crypto.md 7.3) rather than the placeholder signature I would otherwise have had to invent and then keep. §7 named the tuple without specifying how to encode it; this fills that in with the same conventions as 7.1, and the self-grant at enrollment is already in its final format. The signature covers SHA-256(wrappedKey) rather than the key, so a verifier can check attribution without holding the vault key at all. The most valuable tests are the negative ones about the request body: the server is meant to be unable to read what it stores, and a refactor that put a passphrase or a private key into the enrollment request would be invisible to every other test in the repository. So one asserts the body contains neither the passphrase, the recovery code, nor any private key in base64 or hex. Another opens the same bundle three ways -- passphrase, recovery code and device key -- which is what makes a passphrase change a one-row update. ClientEnrollment depends on IKeyBindingAuthorizer rather than the whole OidcClient. It needs exactly one capability, and depending on the full client would drag discovery and token exchange into every test of key binding. Two things fixed while building it. The recovery code buffer was sized one separator short, so every enrollment threw IndexOutOfRange -- caught immediately because nine of ten tests failed identically. And the crypto enum collided with Domain.GrantKind in the server, so it is GrantPurpose there; the numeric values still have to match, which the doc and a test both say. 448 tests pass, zero warnings on a clean rebuild, format clean.
This commit is contained in:
@@ -0,0 +1,315 @@
|
||||
using System.Security.Cryptography;
|
||||
using DodoSSH.Client.Auth;
|
||||
using DodoSSH.Contracts;
|
||||
using DodoSSH.Crypto;
|
||||
using NSec.Cryptography;
|
||||
|
||||
namespace DodoSSH.Client.Api;
|
||||
|
||||
/// <summary>What enrolling produced, for the caller to hold and persist.</summary>
|
||||
/// <remarks>
|
||||
/// The bundle and the vault key are live secrets. The caller owns their lifetime and must dispose the
|
||||
/// bundle; neither is ever written anywhere but the OS keystore and the encrypted local cache.
|
||||
/// </remarks>
|
||||
/// <param name="Response">The server's answer, including the vault and key log position.</param>
|
||||
/// <param name="Bundle">The identity key pair, unlocked for this session.</param>
|
||||
/// <param name="PersonalVaultKey">The personal vault's key, in plaintext for this session.</param>
|
||||
/// <param name="DevicePrivateKey">
|
||||
/// The enrolled device's X25519 private key. Belongs in the OS keystore — it is what lets a later
|
||||
/// launch unlock without the passphrase.
|
||||
/// </param>
|
||||
/// <param name="RecoveryCode">
|
||||
/// The generated recovery code, which must be shown to the user once and never stored. Losing this
|
||||
/// along with the passphrase and every device means the vault is unrecoverable, and no server-side
|
||||
/// reset is possible by design.
|
||||
/// </param>
|
||||
public sealed record EnrollmentOutcome(
|
||||
EnrollmentResponse Response,
|
||||
UserSecretBundle Bundle,
|
||||
byte[] PersonalVaultKey,
|
||||
byte[] DevicePrivateKey,
|
||||
string RecoveryCode);
|
||||
|
||||
/// <summary>
|
||||
/// Runs enrollment: generate keys, have the identity provider sign over them, and publish.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Ordering here is not a matter of taste. The secret bundle's AAD binds to the server-assigned user
|
||||
/// id, so <c>/me</c> must be read before anything can be wrapped — which is why <c>/me</c> provisions
|
||||
/// the account and returns its id even when it reports that enrollment is required.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Everything the server receives is opaque to it. It gets public keys, wrapped blobs it cannot open,
|
||||
/// and signatures it does not verify beyond the statement's own. That is the whole point: the server
|
||||
/// stores the vault and cannot read it.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed class ClientEnrollment(
|
||||
DodoSshApiClient api,
|
||||
IKeyBindingAuthorizer keyBinding,
|
||||
TimeProvider clock)
|
||||
{
|
||||
/// <summary>Bytes of entropy behind a recovery code.</summary>
|
||||
private const int RecoveryEntropyBytes = 20;
|
||||
|
||||
/// <summary>
|
||||
/// Enrolls the caller.
|
||||
/// </summary>
|
||||
/// <param name="me">
|
||||
/// The result of <see cref="DodoSshApiClient.GetMeAsync"/>, which supplies the user id the wraps
|
||||
/// bind to.
|
||||
/// </param>
|
||||
/// <param name="passphrase">The vault passphrase. Never transmitted or stored.</param>
|
||||
/// <param name="deviceName">Human-readable name for this machine.</param>
|
||||
/// <param name="vaultName">Display name for the personal vault. Plaintext, as vault names are.</param>
|
||||
/// <param name="cancellationToken">Cancellation token.</param>
|
||||
public async Task<EnrollmentOutcome> EnrollAsync(
|
||||
MeResponse me,
|
||||
string passphrase,
|
||||
string deviceName,
|
||||
string vaultName,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(me);
|
||||
ArgumentException.ThrowIfNullOrWhiteSpace(passphrase);
|
||||
ArgumentException.ThrowIfNullOrWhiteSpace(deviceName);
|
||||
|
||||
var now = clock.GetUtcNow();
|
||||
var bundle = UserSecretBundle.Create(now);
|
||||
|
||||
try
|
||||
{
|
||||
var statement = BuildStatement(me, bundle, now, deviceName);
|
||||
|
||||
// The provider signs over the statement's hash, which is what stops the DodoSSH server
|
||||
// fabricating a key for a user who never enrolled. See ADR 0001.
|
||||
var idToken = await keyBinding
|
||||
.AuthorizeKeyBindingAsync(
|
||||
KeyStatementCodec.ComputeNonce(ToFields(statement)),
|
||||
cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
var request = BuildRequest(
|
||||
me, bundle, statement, idToken, passphrase, vaultName, now, out var material);
|
||||
|
||||
var response = await api.EnrollAsync(request, cancellationToken).ConfigureAwait(false);
|
||||
|
||||
return new EnrollmentOutcome(
|
||||
response,
|
||||
bundle,
|
||||
material.VaultKey,
|
||||
material.DevicePrivateKey,
|
||||
material.RecoveryCode);
|
||||
}
|
||||
catch
|
||||
{
|
||||
// The caller never receives the bundle on failure, so this is the only place that can
|
||||
// release its guarded memory.
|
||||
bundle.Dispose();
|
||||
throw;
|
||||
}
|
||||
}
|
||||
|
||||
private static KeyStatement BuildStatement(
|
||||
MeResponse me,
|
||||
UserSecretBundle bundle,
|
||||
DateTimeOffset now,
|
||||
string deviceName) =>
|
||||
new(
|
||||
Version: KeyStatementCodec.CurrentVersion,
|
||||
Issuer: me.Issuer,
|
||||
Subject: me.Subject,
|
||||
Email: me.Email,
|
||||
EncryptionPublicKey: bundle.EncryptionPublicKey,
|
||||
SigningPublicKey: bundle.SigningPublicKey,
|
||||
KeyGeneration: 1,
|
||||
CreatedAt: now,
|
||||
DeviceName: deviceName);
|
||||
|
||||
/// <summary>Secrets the caller keeps after a successful enrollment.</summary>
|
||||
private readonly record struct SessionMaterial(
|
||||
byte[] VaultKey,
|
||||
byte[] DevicePrivateKey,
|
||||
string RecoveryCode);
|
||||
|
||||
/// <remarks>
|
||||
/// The passphrase is a parameter rather than a field, so it lives only for the duration of this call
|
||||
/// and never becomes state on a long-lived object that a heap dump would find.
|
||||
/// </remarks>
|
||||
private static EnrollmentRequest BuildRequest(
|
||||
MeResponse me,
|
||||
UserSecretBundle bundle,
|
||||
KeyStatement statement,
|
||||
string idToken,
|
||||
string passphrase,
|
||||
string vaultName,
|
||||
DateTimeOffset now,
|
||||
out SessionMaterial material)
|
||||
{
|
||||
var descriptor = DshAad.UserSecretBundle(me.UserId);
|
||||
|
||||
// A fresh salt per wrap, and the parameters travel with it — so raising the cost later is a
|
||||
// per-user migration at next unlock rather than a breaking change.
|
||||
var passphraseSalt = RandomNumberGenerator.GetBytes(CryptoSpec.SaltSize);
|
||||
var recoverySalt = RandomNumberGenerator.GetBytes(CryptoSpec.SaltSize);
|
||||
var recoveryCode = GenerateRecoveryCode();
|
||||
|
||||
byte[] passphraseWrap;
|
||||
byte[] recoveryWrap;
|
||||
|
||||
using (var master = MasterKey.Derive(
|
||||
passphrase, passphraseSalt, Argon2Profile.PassphraseDefault))
|
||||
{
|
||||
passphraseWrap = master.WrapBundle(bundle, descriptor);
|
||||
}
|
||||
|
||||
// The recovery code carries real entropy, so it needs far less stretching than a passphrase.
|
||||
using (var recoveryMaster = MasterKey.Derive(
|
||||
recoveryCode, recoverySalt, Argon2Profile.RandomSecret))
|
||||
{
|
||||
recoveryWrap = recoveryMaster.WrapBundle(bundle, descriptor);
|
||||
}
|
||||
|
||||
using var deviceKey = Key.Create(
|
||||
KeyAgreementAlgorithm.X25519,
|
||||
new KeyCreationParameters { ExportPolicy = KeyExportPolicies.AllowPlaintextExport });
|
||||
|
||||
var devicePublicKey = deviceKey.PublicKey.Export(KeyBlobFormat.RawPublicKey);
|
||||
var deviceWrap = bundle.SealTo(devicePublicKey, descriptor);
|
||||
|
||||
var vault = BuildPersonalVault(me, bundle, vaultName, now, out var vaultKey);
|
||||
|
||||
material = new SessionMaterial(
|
||||
vaultKey,
|
||||
deviceKey.Export(KeyBlobFormat.RawPrivateKey),
|
||||
recoveryCode);
|
||||
|
||||
return new EnrollmentRequest(
|
||||
Statement: statement,
|
||||
StatementSignature: DshSignatures.SignKeyStatement(
|
||||
bundle.SigningKey,
|
||||
KeyStatementCodec.Encode(ToFields(statement))),
|
||||
IdentityProviderToken: idToken,
|
||||
WrappedPrivateKey: passphraseWrap,
|
||||
KdfParameters: ToContract(passphraseSalt, Argon2Profile.PassphraseDefault),
|
||||
DevicePublicKey: devicePublicKey,
|
||||
DeviceWrappedPrivateKey: deviceWrap,
|
||||
RecoveryWrappedPrivateKey: recoveryWrap,
|
||||
RecoveryKdfParameters: ToContract(recoverySalt, Argon2Profile.RandomSecret),
|
||||
PersonalVault: vault);
|
||||
}
|
||||
|
||||
/// <remarks>
|
||||
/// The vault id is chosen here rather than by the server, which is what makes enrollment safely
|
||||
/// retryable and is required by the grant signature — the signed tuple covers the vault id.
|
||||
/// <para>
|
||||
/// A self-grant carries no key log head: there is no third party whose key could have been
|
||||
/// substituted, and the log entry that would supply one is written by the server in the same
|
||||
/// transaction, so it cannot be signed over here.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
private static PersonalVaultRequest BuildPersonalVault(
|
||||
MeResponse me,
|
||||
UserSecretBundle bundle,
|
||||
string vaultName,
|
||||
DateTimeOffset now,
|
||||
out byte[] vaultKey)
|
||||
{
|
||||
var vaultId = Guid.CreateVersion7();
|
||||
vaultKey = VaultKeys.Create();
|
||||
|
||||
var wrappedVaultKey = VaultKeys.WrapTo(vaultKey, bundle.EncryptionPublicKey, vaultId, 1);
|
||||
|
||||
var fingerprint = DshCrypto.ComputeFingerprint(
|
||||
bundle.EncryptionPublicKey,
|
||||
bundle.SigningPublicKey);
|
||||
|
||||
var grant = GrantStatementCodec.Encode(
|
||||
vaultId,
|
||||
keyGeneration: 1,
|
||||
GrantPurpose.Member,
|
||||
granteeUserId: me.UserId,
|
||||
granteeKeyFingerprint: fingerprint,
|
||||
wrappedKey: wrappedVaultKey,
|
||||
granterUserId: me.UserId,
|
||||
granterKeyFingerprint: fingerprint,
|
||||
keyLogHead: default,
|
||||
grantedAt: now);
|
||||
|
||||
return new PersonalVaultRequest(
|
||||
VaultId: vaultId,
|
||||
Name: vaultName,
|
||||
WrappedVaultKey: wrappedVaultKey,
|
||||
GrantSignature: GrantStatementCodec.Sign(bundle.SigningKey, grant),
|
||||
GrantedAt: now);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Generates a printable recovery code.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Base32 over Crockford's alphabet, which omits I, L, O and U — so a code read aloud or copied off
|
||||
/// a screen cannot be mistranscribed into a different valid code, and cannot spell anything
|
||||
/// unfortunate. Grouped for legibility, and the groups are not part of the secret: the derivation
|
||||
/// uses the string exactly as shown, dashes included, because that is what the user will type back.
|
||||
/// </remarks>
|
||||
private static string GenerateRecoveryCode()
|
||||
{
|
||||
const string Alphabet = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
|
||||
const int BitsPerCharacter = 5;
|
||||
const int CharactersPerGroup = 5;
|
||||
|
||||
// 20 bytes is 160 bits, which divides evenly into 32 five-bit characters — so no bits are
|
||||
// discarded and no padding is needed. Separators go between groups, hence one fewer than the
|
||||
// number of groups.
|
||||
var totalCharacters = RecoveryEntropyBytes * 8 / BitsPerCharacter;
|
||||
var separators = (totalCharacters - 1) / CharactersPerGroup;
|
||||
|
||||
var entropy = RandomNumberGenerator.GetBytes(RecoveryEntropyBytes);
|
||||
var characters = new char[totalCharacters + separators];
|
||||
|
||||
var index = 0;
|
||||
|
||||
for (var position = 0; position < totalCharacters; position++)
|
||||
{
|
||||
if (position > 0 && position % CharactersPerGroup == 0)
|
||||
{
|
||||
characters[index++] = '-';
|
||||
}
|
||||
|
||||
var value = 0;
|
||||
for (var offset = 0; offset < BitsPerCharacter; offset++)
|
||||
{
|
||||
var bit = (position * BitsPerCharacter) + offset;
|
||||
value = (value << 1) | ((entropy[bit / 8] >> (7 - (bit % 8))) & 1);
|
||||
}
|
||||
|
||||
characters[index++] = Alphabet[value];
|
||||
}
|
||||
|
||||
CryptographicOperations.ZeroMemory(entropy);
|
||||
|
||||
return new string(characters);
|
||||
}
|
||||
|
||||
private static KdfParameters ToContract(byte[] salt, Argon2Profile profile) =>
|
||||
new(
|
||||
Algorithm: "argon2id",
|
||||
Salt: salt,
|
||||
MemoryKibibytes: profile.MemoryKibibytes,
|
||||
Passes: profile.Passes,
|
||||
Parallelism: Argon2Profile.Parallelism);
|
||||
|
||||
private static KeyStatementFields ToFields(KeyStatement statement) =>
|
||||
new(
|
||||
statement.Version,
|
||||
statement.Issuer,
|
||||
statement.Subject,
|
||||
statement.Email,
|
||||
statement.EncryptionPublicKey,
|
||||
statement.SigningPublicKey,
|
||||
statement.KeyGeneration,
|
||||
statement.CreatedAt,
|
||||
statement.DeviceName);
|
||||
}
|
||||
Reference in New Issue
Block a user