[API Proposal]: Windows CNG virtualization-based security

[krwq]

Background and motivation

One of the Windows 11 builds has added framework to help secure Windows keys with virtualization-based security (VBS). With this new capability, keys can be protected from admin-level key theft attacks with negligible effect on performance, reliability, or scale.

Blog post: https://techcommunity.microsoft.com/t5/windows-it-pro-blog/advancing-key-protection-in-windows-using-vbs/ba-p/4050988

Win API: https://learn.microsoft.com/en-us/windows/win32/api/ncrypt/nf-ncrypt-ncryptcreatepersistedkey

The proposal is to extend existing CngKeyCreationOptions API to include the new flags.

API Proposal

namespace System.Security.Cryptography;

[Flags]
public enum CngKeyCreationOptions : int
{
    // existing:
    // None = 0x00000000,
    // MachineKey = 0x00000020,            // NCRYPT_MACHINE_KEY_FLAG
    // OverwriteExistingKey = 0x00000080,  // NCRYPT_OVERWRITE_KEY_FLAG

    // new APIs:
    PreferVbs = 0x00010000,             // NCRYPT_PREFER_VBS_FLAG
    RequireVbs = 0x00020000,            // NCRYPT_REQUIRE_VBS_FLAG
    UsePerBootKey = 0x00040000,         // NCRYPT_USE_PER_BOOT_KEY_FLAG
}

API Usage

// Note: this API is Windows only

using System.Security.Cryptography;

CngKeyCreationParameters cngCreationParams = new()
{
    Provider = CngProvider.MicrosoftSoftwareKeyStorageProvider,
    KeyCreationOptions = CngKeyCreationOptions.RequireVbs | CngKeyCreationOptions.OverwriteExistingKey,
};

using (CngKey key = CngKey.Create(CngAlgorithm.ECDsaP256, "mySoftwareKey", cngCreationParams))
using (ECDsaCng ecdsa = new ECDsaCng(key))
{
    // do stuff with the key
}

Alternative Designs

No response

Risks

Very low - new flags to existing API

[dotnet-policy-service[bot]]

Tagging subscribers to this area: @dotnet/area-system-security, @bartonjs, @vcsjones See info in area-owners.md if you want to be subscribed.

[bartonjs]

I'm not sure I like the names of any of these new enum members. NCRYPT_USE_PER_BOOT_KEY_FLAG doesn't seem to be on MSDN, so I can't say if the description offers a better description of what this means, and the Vbs isn't (I don't think) a common enough concept yet that it's worthy of abbreviation... but the expanded form isn't really better.

So, they might all be "right", but I'm not sure I like them :)

[krwq]

I mainly matched the WinAPI names but will leave for API review to make a call which name they prefer - I think it's easier to mostly match existing WinAPI names but I'm personally not a fan of "VBS" in the name

[terrajobst]

Video

• Looks good as proposed

namespace System.Security.Cryptography;

[Flags]
public enum CngKeyCreationOptions : int
{
    // existing:
    // None = 0x00000000,
    // MachineKey = 0x00000020,            // NCRYPT_MACHINE_KEY_FLAG
    // OverwriteExistingKey = 0x00000080,  // NCRYPT_OVERWRITE_KEY_FLAG

    // new APIs:
    PreferVbs = 0x00010000,             // NCRYPT_PREFER_VBS_FLAG
    RequireVbs = 0x00020000,            // NCRYPT_REQUIRE_VBS_FLAG
    UsePerBootKey = 0x00040000,         // NCRYPT_USE_PER_BOOT_KEY_FLAG
}