Skip to content

Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.

11.5 KB
Raw Blame
//-----------------------------------------------------------------------
// <copyright file="Signing.cs" company="aliasvault">
// Copyright (c) aliasvault. All rights reserved.
// Licensed under the AGPLv3 license. See LICENSE.md file in the project root for full license information.
// </copyright>
//-----------------------------------------------------------------------

namespace AliasVault.Cryptography;

using System.Buffers.Binary;
using System.Text;
using Org.BouncyCastle.Math.EC.Rfc8032;

/// <summary>
/// Verifies Ed25519 signatures made by account signing keys via the Rust core.
/// </summary>
public static class Signing
{
    /// <summary>
    /// The label of a user's signature over their own account encryption public key.
    /// </summary>
    public const string AccountPublicKeyLabel = "aliasvault/v1/sig/account-public-key";

    /// <summary>
    /// The label of a grant: a manifest's VEK encrypted for one recipient key, signed by whoever handed it out.
    /// </summary>
    public const string GrantLabel = "aliasvault/v1/sig/grant";

    /// <summary>
    /// The label of a manifest's mail delivery public key, signed by whoever published it.
    /// </summary>
    public const string DeliveryKeyLabel = "aliasvault/v1/sig/delivery-key";

    /// <summary>
    /// The label of the vault name an invitation carries, signed by the inviter.
    /// </summary>
    public const string InvitationNameLabel = "aliasvault/v1/sig/invitation-name";

    /// <summary>
    /// The label of moving an email alias to another manifest, signed by the user who moves it.
    /// </summary>
    public const string EmailClaimTransferLabel = "aliasvault/v1/sig/email-claim-transfer";

    /// <summary>
    /// The label of a Login with Mobile approval, signed by the approving user.
    /// </summary>
    public const string MobileLoginApprovalLabel = "aliasvault/v1/sig/mobile-login-approval";

    /// <summary>
    /// The label of a key certification: one user vouching that a signing public key belongs to another user.
    /// </summary>
    public const string KeyCertificationLabel = "aliasvault/v1/sig/key-certification";

    /// <summary>
    /// The label under which a signing public key is hashed into its fingerprint, the user's account fingerprint.
    /// </summary>
    public const string FingerprintLabel = "aliasvault/v1/signing-key-fingerprint";

    /// <summary>
    /// The decimal digits in a fingerprint (the value is reduced modulo 10^20).
    /// </summary>
    public const int FingerprintDigits = 20;

    /// <summary>
    /// Builds the bytes a signature covers: the label and each field, each prefixed with its length as a big-endian uint.
    /// </summary>
    /// <param name="label">The purpose label.</param>
    /// <param name="fields">The signed fields.</param>
    /// <returns>The message bytes.</returns>
    public static byte[] SignedMessage(string label, params byte[][] fields)
    {
        var parts = new[] { Encoding.UTF8.GetBytes(label) }.Concat(fields).ToList();
        var message = new byte[parts.Sum(p => 4 + p.Length)];
        var offset = 0;
        foreach (var part in parts)
        {
            BinaryPrimitives.WriteUInt32BigEndian(message.AsSpan(offset), (uint)part.Length);
            part.CopyTo(message, offset + 4);
            offset += 4 + part.Length;
        }

        return message;
    }

    /// <summary>
    /// Builds the signed message of a grant.
    /// </summary>
    /// <param name="manifestId">The manifest the VEK belongs to.</param>
    /// <param name="keyVersion">The version of the manifest's VEK.</param>
    /// <param name="signerUserId">The user who hands out the grant.</param>
    /// <param name="recipientPublicKey">The recipient public key (JWK) the VEK is encrypted for, as stored.</param>
    /// <param name="algorithm">The algorithm token of the encryption.</param>
    /// <param name="encryptedVek">The encrypted VEK.</param>
    /// <returns>The message bytes.</returns>
    public static byte[] GrantMessage(Guid manifestId, int keyVersion, string signerUserId, string recipientPublicKey, string algorithm, string encryptedVek)
    {
        return SignedMessage(GrantLabel, Utf8(manifestId.ToString()), Utf8(keyVersion.ToString(System.Globalization.CultureInfo.InvariantCulture)), Utf8(signerUserId), Utf8(recipientPublicKey), Utf8(algorithm), Utf8(encryptedVek));
    }

    /// <summary>
    /// Builds the signed message of the vault name an invitation carries.
    /// </summary>
    /// <param name="manifestId">The manifest the invitation is for.</param>
    /// <param name="signerUserId">The inviter.</param>
    /// <param name="recipientPublicKey">The recipient public key (JWK) the name is encrypted for, as stored.</param>
    /// <param name="encryptedName">The encrypted name.</param>
    /// <returns>The message bytes.</returns>
    public static byte[] InvitationNameMessage(Guid manifestId, string signerUserId, string recipientPublicKey, string encryptedName)
    {
        return SignedMessage(InvitationNameLabel, Utf8(manifestId.ToString()), Utf8(signerUserId), Utf8(recipientPublicKey), Utf8(encryptedName));
    }

    /// <summary>
    /// Builds the signed message of a delivery key publish, bound to the manifest revision the write is based on so it
    /// cannot be replayed in a later write.
    /// </summary>
    /// <param name="manifestId">The manifest the key delivers mail for.</param>
    /// <param name="publicKey">The delivery public key (JWK).</param>
    /// <param name="currentRevision">The revision the write is based on.</param>
    /// <returns>The message bytes.</returns>
    public static byte[] DeliveryKeyMessage(Guid manifestId, string publicKey, long currentRevision)
    {
        return SignedMessage(DeliveryKeyLabel, Utf8(manifestId.ToString()), Utf8(publicKey), Utf8(currentRevision.ToString(System.Globalization.CultureInfo.InvariantCulture)));
    }

    /// <summary>
    /// Builds the signed message of moving an email alias to another manifest, bound to the claim version so it cannot be replayed.
    /// </summary>
    /// <param name="address">The alias address, trimmed and lowercased.</param>
    /// <param name="sourceManifestId">The manifest that owns the alias before the move.</param>
    /// <param name="targetManifestId">The manifest that owns the alias after the move.</param>
    /// <param name="claimVersion">The claim version the client was served.</param>
    /// <returns>The message bytes.</returns>
    public static byte[] EmailClaimTransferMessage(string address, Guid sourceManifestId, Guid targetManifestId, long claimVersion)
    {
        return SignedMessage(EmailClaimTransferLabel, Utf8(address), Utf8(sourceManifestId.ToString()), Utf8(targetManifestId.ToString()), Utf8(claimVersion.ToString(System.Globalization.CultureInfo.InvariantCulture)));
    }

    /// <summary>
    /// Builds the signed message of a Login with Mobile approval: the Account Key encrypted for the requesting client.
    /// </summary>
    /// <param name="requestId">The Login with Mobile request.</param>
    /// <param name="algorithm">The algorithm of the encrypted Account Key.</param>
    /// <param name="encryptedAccountKey">The encrypted Account Key.</param>
    /// <returns>The message bytes.</returns>
    public static byte[] MobileLoginApprovalMessage(string requestId, string algorithm, string encryptedAccountKey)
    {
        return SignedMessage(MobileLoginApprovalLabel, Utf8(requestId), Utf8(algorithm), Utf8(encryptedAccountKey));
    }

    /// <summary>
    /// Builds the signed message of a key certification: the certifier vouches that a signing public key belongs to the subject.
    /// </summary>
    /// <param name="certifierUserId">The user vouching for the key.</param>
    /// <param name="subjectUserId">The user the key belongs to.</param>
    /// <param name="subjectSigningPublicKey">The certified signing public key (base64).</param>
    /// <returns>The message bytes.</returns>
    public static byte[] KeyCertificationMessage(string certifierUserId, string subjectUserId, string subjectSigningPublicKey)
    {
        return SignedMessage(KeyCertificationLabel, Utf8(certifierUserId), Utf8(subjectUserId), Utf8(subjectSigningPublicKey));
    }

    /// <summary>
    /// The fingerprint of a signing public key as <see cref="FingerprintDigits"/> digits without separators, the same digits the
    /// Rust core prints in groups of four. Null for a value that is not an Ed25519 public key.
    /// </summary>
    /// <param name="publicKeyBase64">The signing public key (base64).</param>
    /// <returns>The fingerprint digits, or null.</returns>
    public static string? Fingerprint(string? publicKeyBase64)
    {
        var publicKey = TryDecode(publicKeyBase64, Ed25519.PublicKeySize);
        if (publicKey == null)
        {
            return null;
        }

        var digest = System.Security.Cryptography.SHA256.HashData(SignedMessage(FingerprintLabel, publicKey));
        var value = BinaryPrimitives.ReadUInt128BigEndian(digest) % UInt128.Parse("100000000000000000000", System.Globalization.CultureInfo.InvariantCulture);
        return value.ToString("D" + FingerprintDigits, System.Globalization.CultureInfo.InvariantCulture);
    }

    /// <summary>
    /// The digits of a code a user typed, ignoring spaces and dashes.
    /// </summary>
    /// <param name="code">The typed code.</param>
    /// <returns>Only its digits.</returns>
    public static string NormalizeFingerprint(string? code)
    {
        return new string((code ?? string.Empty).Where(char.IsAsciiDigit).ToArray());
    }

    /// <summary>
    /// Whether a base64 signature over a message verifies under a base64 Ed25519 public key.
    /// </summary>
    /// <param name="publicKeyBase64">The signer's public key.</param>
    /// <param name="message">The signed message, see <see cref="SignedMessage"/>.</param>
    /// <param name="signatureBase64">The signature.</param>
    /// <returns>True when the signature is valid.</returns>
    public static bool Verify(string? publicKeyBase64, byte[] message, string? signatureBase64)
    {
        var publicKey = TryDecode(publicKeyBase64, Ed25519.PublicKeySize);
        var signature = TryDecode(signatureBase64, Ed25519.SignatureSize);
        if (publicKey == null || signature == null || !Ed25519.ValidatePublicKeyFull(publicKey, 0))
        {
            return false;
        }

        return Ed25519.Verify(signature, 0, publicKey, 0, message, 0, message.Length);
    }

    /// <summary>
    /// Whether a signature is the signing key's signature over an account encryption public key.
    /// </summary>
    /// <param name="signingPublicKey">The signer's public key.</param>
    /// <param name="accountPublicKey">The signed account public key (JWK) as sent.</param>
    /// <param name="signature">The signature.</param>
    /// <returns>True when the signature is valid.</returns>
    public static bool VerifyAccountPublicKey(string? signingPublicKey, string? accountPublicKey, string? signature)
    {
        return accountPublicKey != null && Verify(signingPublicKey, SignedMessage(AccountPublicKeyLabel, Encoding.UTF8.GetBytes(accountPublicKey)), signature);
    }

    private static byte[] Utf8(string value) => Encoding.UTF8.GetBytes(value);

    private static byte[]? TryDecode(string? base64, int expectedLength)
    {
        if (string.IsNullOrEmpty(base64))
        {
            return null;
        }

        try
        {
            var bytes = Convert.FromBase64String(base64);
            return bytes.Length == expectedLength ? bytes : null;
        }
        catch (FormatException)
        {
            return null;
        }
    }
}