File: DigestUtils.cs
Web Access
Project: Microsoft.NET.Build.Containers.csproj (Microsoft.NET.Build.Containers)
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using System.Security.Cryptography;
using System.Text.RegularExpressions;

namespace Microsoft.NET.Build.Containers;

internal sealed class DigestUtils
{
    /// <summary>
    /// The set of registered algorithm identifiers from the OCI image-spec,
    /// mapped to the regex pattern that the encoded portion of the digest must
    /// match. Taken directly from the OCI image specification:
    /// <see href="https://github.com/opencontainers/image-spec/blob/a4c6ade7bb82b316d45391f572727a63e268b252/descriptor.md#registered-algorithms">
    /// Registered Algorithms
    /// </see>
    ///
    /// The OCI specification also defines sha512 and blake3 as optional
    /// registered algorithms. They are not included here because the rest of
    /// the containers pipeline (blob storage paths, digest creation, content
    /// verification) is currently SHA-256 only. Supporting additional
    /// algorithms requires changes across ContentStore, Layer, ImageBuilder,
    /// and the registry push/pull paths.
    /// </summary>
    private static readonly Dictionary<string, Regex> s_registeredAlgorithms = new(StringComparer.Ordinal)
    {
        // TODO: Use GeneratedRegexAttribute when
        // https://github.com/dotnet/sdk/pull/53547 is merged.
        ["sha256"] = new Regex(@"^[a-f0-9]{64}$"),
    };

    /// <summary>
    /// Computes the SHA-256 digest of <paramref name="content"/> and returns
    /// the full digest string.
    /// </summary>
    /// <remarks>
    /// <c>ComputeSha256Digest("")</c> returns <c>"sha256:e3b0c4..."</c>.
    /// </remarks>
    internal static string ComputeSha256Digest(string content) => FormatSha256Digest(ComputeSha256(content));

    /// <summary>
    /// Formats a SHA-256 digest string from an already-computed encoded hash
    /// value. The encoded value is lowercased to conform to the OCI spec.
    /// Throws <see cref="ArgumentException"/> if <paramref name="encoded"/>
    /// is not exactly 64 hex characters.
    /// </summary>
    /// <remarks>
    /// <c>FormatSha256Digest("abcdef...")</c> returns
    /// <c>"sha256:abcdef..."</c>.
    /// </remarks>
    internal static string FormatSha256Digest(string encoded)
    {
        encoded = encoded.ToLowerInvariant();

        if (!s_registeredAlgorithms["sha256"].IsMatch(encoded))
        {
            throw new ArgumentException(
                message: $"SHA-256 value '{encoded}' does not match expected format '{s_registeredAlgorithms["sha256"]}'",
                paramName: nameof(encoded));
        }

        return $"sha256:{encoded}";
    }

    /// <summary>
    /// Validates a digest string against the OCI grammar and algorithms supported by this implementation.
    /// </summary>
    /// <remarks>
    /// Does not check the digest against any actual content.
    /// </remarks>
    /// <throws cref="InvalidDigestException">Thrown if the digest is invalid.</throws>
    internal static void ValidateSupportedDigestFormat(string digest, out string algorithm, out ReadOnlySpan<byte> encodedValue)
    {
        if (TryParseDigest(digest, out algorithm, out encodedValue, out DigestParseFailure parseFailure))
        {
            return;
        }

        string message = parseFailure switch
        {
            DigestParseFailure.InvalidFormat =>
                $"Digest '{digest}' does not match expected pattern '{ReferenceParser.AnchoredDigestRegexp}'.",
            DigestParseFailure.UnsupportedAlgorithm =>
                $"Unsupported digest algorithm '{algorithm}'. Supported algorithms: {string.Join(", ", s_registeredAlgorithms.Keys)}.",
            DigestParseFailure.InvalidEncodedValue =>
                $"Digest '{digest}' encoded value does not match expected pattern for algorithm '{algorithm}': '{s_registeredAlgorithms[algorithm]}'.",
            _ => throw new InvalidOperationException($"Unexpected digest parse failure '{parseFailure}'."),
        };

        throw new InvalidDigestException(message);
    }

    /// <summary>
    /// Validates that digest is correctly formatted and that it matches the
    /// digest of the provided content.
    /// </summary>
    /// <throws cref="InvalidDigestException">
    /// Thrown if the digest is invalid or does not match the content.
    /// </throws>
    internal static void ValidateDigestContent(string digest, ReadOnlySpan<byte> content)
    {
        ValidateSupportedDigestFormat(digest, out _, out _);
        string actualDigest = FormatSha256Digest(ComputeSha256(content));
        if (!string.Equals(actualDigest, digest, StringComparison.Ordinal))
        {
            throw new InvalidDigestException(
                $"Content does not match expected digest '{digest}'. Computed digest was '{actualDigest}'.");
        }
    }

    /// <summary>
    /// Validates a digest string against the OCI grammar and registered
    /// algorithms, then returns the encoded portion as a string.
    /// </summary>
    /// <remarks>
    /// <c>GetEncoded("sha256:e3b0c4...")</c> returns <c>"e3b0c4..."</c>.
    /// </remarks>
    internal static string GetEncoded(string digest)
    {
        ValidateSupportedDigestFormat(digest, out _, out ReadOnlySpan<byte> encoded);
        return Convert.ToHexStringLower(encoded);
    }

    /// <summary>
    /// Validates a digest string against the OCI grammar and registered
    /// algorithms, then returns the encoded portion as bytes.
    /// </summary>
    /// <remarks>
    /// <c>GetEncoded("sha256:e3b0c4...")</c> returns <c>"e3b0c4..."</c>.
    /// </remarks>
    internal static ReadOnlySpan<byte> GetEncodedValue(string digest)
    {
        ValidateSupportedDigestFormat(digest, out _, out ReadOnlySpan<byte> encodedValue);
        return encodedValue;
    }

    /// <summary>
    /// Computes the SHA-256 hash of <paramref name="content"/> and returns it
    /// as a lowercase hex string.
    /// </summary>
    /// <remarks>
    /// <c>ComputeSha256("")</c> returns <c>"e3b0c4..."</c>.
    /// </remarks>
    internal static string ComputeSha256(string content) => ComputeSha256(Encoding.UTF8.GetBytes(content));

    private static string ComputeSha256(ReadOnlySpan<byte> content)
    {
        Span<byte> hash = stackalloc byte[SHA256.HashSizeInBytes];
        SHA256.HashData(content, hash);
        return Convert.ToHexStringLower(hash);
    }

    /// <summary>
    /// Validates hash value against the expected hash, failing with a
    /// consistent error message if they don't match.
    /// </summary>
    internal static void ValidateHashValueAsync(ReadOnlySpan<byte> actualHash, ReadOnlySpan<byte> expectedHash)
    {
        InvalidDigestException.ThrowIfMismatched(expectedHash, actualHash);
    }

    /// <summary>
    /// Attempts to parse a digest string against the OCI grammar and registered algorithms.
    /// </summary>
    /// <remarks>
    /// For "sha256:e3b0c4...", algorithm="sha256" and encoded="e3b0c4..."
    /// </remarks>
    internal static bool TryParseDigest(string digest, out string algorithm, out ReadOnlySpan<byte> encodedValue) =>
        TryParseDigest(digest, out algorithm, out encodedValue, out _);

    private static bool TryParseDigest(
        string digest,
        out string algorithm,
        out ReadOnlySpan<byte> encodedValue,
        out DigestParseFailure parseFailure)
    {
        algorithm = string.Empty;
        encodedValue = default;
        parseFailure = DigestParseFailure.None;

        Match match = ReferenceParser.AnchoredDigestRegexp.Match(digest);

        if (!match.Success)
        {
            parseFailure = DigestParseFailure.InvalidFormat;
            return false;
        }

        algorithm = match.Groups[1].Value;
        string encoded = match.Groups[2].Value;

        if (!s_registeredAlgorithms.TryGetValue(algorithm, out Regex? encodedPattern))
        {
            parseFailure = DigestParseFailure.UnsupportedAlgorithm;
            return false;
        }

        if (!encodedPattern.IsMatch(encoded))
        {
            parseFailure = DigestParseFailure.InvalidEncodedValue;
            return false;
        }
        encodedValue = Convert.FromHexString(encoded);
        return true;
    }

    private enum DigestParseFailure
    {
        None,
        InvalidFormat,
        UnsupportedAlgorithm,
        InvalidEncodedValue,
    }
}