MAA POC (#5339)

* init

* pr comments

* pr comments

* typos

---------

Co-authored-by: Gladwin Johnson <[email protected]>

Author: gladjohn

prototype/KeyGuardMaa/AttestationClient.cs

@@ -0,0 +1,116 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using Microsoft.Win32.SafeHandles;
+using System;
+using System.Runtime.InteropServices;
+using static KeyGuard.Attestation.AttestationErrors;
+
+namespace KeyGuard.Attestation
+{
+    /// <summary>
+    /// Managed façade for <c>AttestationClientLib.dll</c>.  Holds initialization state,
+    /// does ref-count hygiene on <see cref="SafeNCryptKeyHandle"/>, and returns a JWT.
+    /// </summary>
+    public sealed class AttestationClient : IDisposable
+    {
+        private bool _initialized;
+
+        /// <summary>
+        /// AttestationClient constructor.  Pro-actively verifies the native DLL,
+        /// </summary>
+        /// <exception cref="InvalidOperationException"></exception>
+        public AttestationClient()
+        {
+            /* step 0 ── pro-actively verify the native DLL */
+            string? dllError = NativeDiagnostics.ProbeNativeDll();
+            if (dllError is not null)
+                throw new InvalidOperationException(dllError);
+
+            /* step 1 ── load & initialize */
+            NativeDllResolver.EnsureLoaded();
+
+            var info = new NativeMethods.AttestationLogInfo
+            {
+                Log = AttestationLogger.ConsoleLogger,
+                Ctx = IntPtr.Zero
+            };
+
+            _initialized = NativeMethods.InitAttestationLib(ref info) == 0;
+            if (!_initialized)
+                throw new InvalidOperationException("Failed to initialize AttestationClientLib.");
+        }
+
+        /// <summary>
+        /// Calls the native <c>AttestKeyGuardImportKey</c> and returns a structured result.
+        /// </summary>
+        public AttestationResult Attest(string endpoint,
+                                        SafeNCryptKeyHandle keyHandle,
+                                        string clientId = "kg-sample-client")
+        {
+            if (!_initialized)
+                return new(AttestationStatus.NotInitialized, null, -1,
+                           "Native library not initialized.");
+
+            IntPtr buf = IntPtr.Zero;
+            bool addRef = false;
+
+            try
+            {
+                keyHandle.DangerousAddRef(ref addRef);
+
+                int rc = NativeMethods.AttestKeyGuardImportKey(
+                             endpoint, null, null, keyHandle, out buf, clientId);
+
+                if (rc != 0)
+                    return new(AttestationStatus.NativeError, null, rc, null);
+
+                if (buf == IntPtr.Zero)
+                    return new(AttestationStatus.TokenEmpty, null, 0,
+                               "rc==0 but token buffer was null.");
+
+                string jwt = Marshal.PtrToStringAnsi(buf)!;
+                return new(AttestationStatus.Success, jwt, 0, null);
+            }
+            catch (DllNotFoundException ex)
+            {
+                return new(AttestationStatus.Exception, null, -1,
+                    $"Native DLL not found: {ex.Message}");
+            }
+            catch (BadImageFormatException ex)
+            {
+                return new(AttestationStatus.Exception, null, -1,
+                    $"Architecture mismatch (x86/x64) or corrupted DLL: {ex.Message}");
+            }
+            catch (SEHException ex)
+            {
+                return new(AttestationStatus.Exception, null, -1,
+                    $"Native library raised SEHException: {ex.Message}");
+            }
+            catch (Exception ex)
+            {
+                return new(AttestationStatus.Exception, null, -1, ex.Message);
+            }
+            finally
+            {
+                if (buf != IntPtr.Zero)
+                    NativeMethods.FreeAttestationToken(buf);
+                if (addRef)
+                    keyHandle.DangerousRelease();
+            }
+        }
+
+        /// <summary>
+        /// Disposes the client, releasing any resources and un-initializing the native library.
+        /// </summary>
+        public void Dispose()
+        {
+            if (_initialized)
+            {
+                NativeMethods.UninitAttestationLib();
+                _initialized = false;
+            }
+            GC.SuppressFinalize(this);
+        }
+    }
+}

prototype/KeyGuardMaa/AttestationErrors.cs

@@ -0,0 +1,23 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace KeyGuard.Attestation
+{
+    internal static class AttestationErrors
+    {
+        internal static string Describe(AttestationResultErrorCode rc) => rc switch
+        {
+            AttestationResultErrorCode.ERRORCURLINITIALIZATION
+                => "libcurl failed to initialize (DLL missing or version mismatch).",
+            AttestationResultErrorCode.ERRORHTTPREQUESTFAILED
+                => "Could not reach the attestation service (network / proxy?).",
+            AttestationResultErrorCode.ERRORATTESTATIONFAILED
+                => "The enclave rejected the evidence (key type / PCR policy).",
+            AttestationResultErrorCode.ERRORJWTDECRYPTIONFAILED
+                => "The JWT returned by the service could not be decrypted.",
+            AttestationResultErrorCode.ERRORLOGGERINITIALIZATION
+                => "Native logger setup failed (rare).",
+            _ => rc.ToString()         // default: enum name
+        };
+    }
+}

prototype/KeyGuardMaa/AttestationInterop.cs

@@ -0,0 +1,46 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using Microsoft.Win32.SafeHandles;
+using System;
+using System.IO;
+using System.Runtime.InteropServices;
+
+namespace KeyGuard.Attestation
+{
+    /// <summary>P/Invoke signatures – nothing managed should leak beyond this class.</summary>
+    internal static class NativeMethods
+    {
+        internal enum LogLevel { Error, Warn, Info, Debug }
+
+        internal delegate void LogFunc(
+            IntPtr ctx, string tag, LogLevel lvl, string func, int line, string msg);
+
+        [StructLayout(LayoutKind.Sequential)]
+        internal struct AttestationLogInfo
+        {
+            public LogFunc Log;
+            public IntPtr Ctx;
+        }
+
+        [DllImport("AttestationClientLib.dll", CallingConvention = CallingConvention.Cdecl,
+                   CharSet = CharSet.Ansi)]
+        internal static extern int InitAttestationLib(ref AttestationLogInfo info);
+
+        [DllImport("AttestationClientLib.dll", CallingConvention = CallingConvention.Cdecl,
+                   CharSet = CharSet.Ansi)]
+        internal static extern int AttestKeyGuardImportKey(
+            string? endpoint,
+            string? authToken,
+            string? clientPayload,
+            SafeNCryptKeyHandle keyHandle,
+            out IntPtr token,
+            string clientId);
+
+        [DllImport("AttestationClientLib.dll", CallingConvention = CallingConvention.Cdecl)]
+        internal static extern void FreeAttestationToken(IntPtr token);
+
+        [DllImport("AttestationClientLib.dll", CallingConvention = CallingConvention.Cdecl)]
+        internal static extern void UninitAttestationLib();
+    }
+}

prototype/KeyGuardMaa/AttestationLogger.cs

@@ -0,0 +1,13 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace KeyGuard.Attestation
+{
+    internal static class AttestationLogger
+    {
+        /// <summary>Default logger that pipes native messages to <c>Console.WriteLine</c>.</summary>
+        internal static readonly NativeMethods.LogFunc ConsoleLogger = (_,
+            tag, lvl, func, line, msg) =>
+            Console.WriteLine($"[{lvl}] {tag} {func}:{line}  {msg}");
+    }
+}

prototype/KeyGuardMaa/AttestationResultErrorCode.cs

@@ -0,0 +1,121 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace KeyGuard.Attestation
+{
+    /// <summary>
+    /// Error codes returned by <c>AttestationClientLib.dll</c>.
+    /// A value of <see cref="SUCCESS"/> (0) indicates success; all other
+    /// values are negative and represent specific failure categories.
+    /// </summary>
+    public enum AttestationResultErrorCode
+    {
+        /// <summary>The operation completed successfully.</summary>
+        SUCCESS = 0,
+
+        /// <summary>libcurl could not be initialized inside the native library.</summary>
+        ERRORCURLINITIALIZATION = -1,
+
+        /// <summary>The HTTP response body could not be parsed (malformed JSON, invalid JWT, etc.).</summary>
+        ERRORRESPONSEPARSING = -2,
+
+        /// <summary>Managed-Identity (MSI) access token could not be obtained.</summary>
+        ERRORMSITOKENNOTFOUND = -3,
+
+        /// <summary>The HTTP request exceeded the maximum retry count configured by the native client.</summary>
+        ERRORHTTPREQUESTEXCEEDEDRETRIES = -4,
+
+        /// <summary>An HTTP request to the attestation service failed (network error, non-200 status, timeout, etc.).</summary>
+        ERRORHTTPREQUESTFAILED = -5,
+
+        /// <summary>The attestation enclave rejected the supplied evidence (policy or signature failure).</summary>
+        ERRORATTESTATIONFAILED = -6,
+
+        /// <summary>libcurl reported “couldn’t send” (DNS resolution, TLS handshake, or socket error).</summary>
+        ERRORSENDINGCURLREQUESTFAILED = -7,
+
+        /// <summary>One or more input parameters passed to the native API were invalid or null.</summary>
+        ERRORINVALIDINPUTPARAMETER = -8,
+
+        /// <summary>Validation of the attestation parameters failed on the client side.</summary>
+        ERRORATTESTATIONPARAMETERSVALIDATIONFAILED = -9,
+
+        /// <summary>Native client failed to allocate heap memory.</summary>
+        ERRORFAILEDMEMORYALLOCATION = -10,
+
+        /// <summary>Could not retrieve OS build / version information required for the attestation payload.</summary>
+        ERRORFAILEDTOGETOSINFO = -11,
+
+        /// <summary>Internal TPM failure while gathering quotes or PCR values.</summary>
+        ERRORTPMINTERNALFAILURE = -12,
+
+        /// <summary>TPM operation (e.g., signing the quote) failed.</summary>
+        ERRORTPMOPERATIONFAILURE = -13,
+
+        /// <summary>The returned JWT could not be decrypted on the client.</summary>
+        ERRORJWTDECRYPTIONFAILED = -14,
+
+        /// <summary>JWT decryption failed due to a TPM error.</summary>
+        ERRORJWTDECRYPTIONTPMERROR = -15,
+
+        /// <summary>JSON in the service response was invalid or lacked required fields.</summary>
+        ERRORINVALIDJSONRESPONSE = -16,
+
+        /// <summary>The VCEK certificate blob returned from the service was empty.</summary>
+        ERROREMPTYVCEKCERT = -17,
+
+        /// <summary>The service response body was empty.</summary>
+        ERROREMPTYRESPONSE = -18,
+
+        /// <summary>The HTTP request body generated by the client was empty.</summary>
+        ERROREMPTYREQUESTBODY = -19,
+
+        /// <summary>Failed to parse the host-configuration-level (HCL) report.</summary>
+        ERRORHCLREPORTPARSINGFAILURE = -20,
+
+        /// <summary>The retrieved HCL report was empty.</summary>
+        ERRORHCLREPORTEMPTY = -21,
+
+        /// <summary>Could not extract JWK information from the attestation evidence.</summary>
+        ERROREXTRACTINGJWKINFO = -22,
+
+        /// <summary>Failed converting a JWK structure to an RSA public key.</summary>
+        ERRORCONVERTINGJWKTORSAPUB = -23,
+
+        /// <summary>EVP initialization for RSA encryption failed (OpenSSL).</summary>
+        ERROREVPPKEYENCRYPTINITFAILED = -24,
+
+        /// <summary>EVP encryption failed when building the attestation claim.</summary>
+        ERROREVPPKEYENCRYPTFAILED = -25,
+
+        /// <summary>Failed to decrypt data due to a TPM error.</summary>
+        ERRORDATADECRYPTIONTPMERROR = -26,
+
+        /// <summary>Parsing DNS information for the attestation service endpoint failed.</summary>
+        ERRORPARSINGDNSINFO = -27,
+
+        /// <summary>Failed to parse the attestation response envelope.</summary>
+        ERRORPARSINGATTESTATIONRESPONSE = -28,
+
+        /// <summary>Provisioning of the Attestation Key (AK) certificate failed.</summary>
+        ERRORAKCERTPROVISIONINGFAILED = -29,
+
+        /// <summary>Initialising the native attestation client failed.</summary>
+        ERRORCLIENTINITFAILED = -30,
+
+        /// <summary>The service returned an empty JWT.</summary>
+        ERROREMPTYJWTRESPONSE = -31,
+
+        /// <summary>Creating the KeyGuard attestation report failed on the client.</summary>
+        ERRORCREATEKGATTESTATIONREPORT = -32,
+
+        /// <summary>Failed to extract the public key from the import-only key.</summary>
+        ERROREXTRACTIMPORTKEYPUB = -33,
+
+        /// <summary>An unexpected C++ exception occurred inside the native client.</summary>
+        ERRORUNEXPECTEDEXCEPTION = -34,
+
+        /// <summary>Initialising the native logger failed (file I/O / permissions / path issues).</summary>
+        ERRORLOGGERINITIALIZATION = -35
+    }
+}

prototype/KeyGuardMaa/AttestationStatus.cs

@@ -0,0 +1,42 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace KeyGuard.Attestation;
+
+/// <summary>
+/// High-level outcome categories returned by <see cref="AttestationClient.Attest"/>.
+/// </summary>
+public enum AttestationStatus
+{
+    /// <summary>Everything succeeded; <see cref="AttestationResult.Jwt"/> is populated.</summary>
+    Success = 0,
+
+    /// <summary>Native library returned a non-zero <c>AttestationResultErrorCode</c>.</summary>
+    NativeError = 1,
+
+    /// <summary>rc == 0 but the token buffer was null/empty.</summary>
+    TokenEmpty = 2,
+
+    /// <summary><see cref="AttestationClient"/> could not initialize the native DLL.</summary>
+    NotInitialized = 3,
+
+    /// <summary>Any managed exception thrown while attempting the call.</summary>
+    Exception = 4
+}
+
+/// <summary>
+/// Unified result returned by <see cref="AttestationClient.Attest"/>.
+/// </summary>
+/// <param name="Status">High-level category.</param>
+/// <param name="Jwt">JWT when <see cref="AttestationStatus.Success"/>; otherwise null.</param>
+/// <param name="NativeCode">
+/// The raw integer code returned by <c>AttestKeyGuardImportKey</c>
+/// (cast to <see cref="AttestationResultErrorCode"/> for readability).
+/// Zero when <see cref="Status"/> is not <see cref="AttestationStatus.NativeError"/>.
+/// </param>
+/// <param name="Message">Optional descriptive text for non-success cases.</param>
+public record AttestationResult(
+    AttestationStatus Status,
+    string? Jwt,
+    int NativeCode,
+    string? Message);