Add RFC5649 KeyWrap

[blowdart]

Background

There are two different RFCs producing algorithms known as "AES Key Wrap", RFC 3394 ("Advanced Encryption Standard (AES) Key Wrap Algorithm"), and RFC 5649 ("Advanced Encryption Standard (AES) Key Wrap with Padding Algorithm").

These two RFCs produce mutually unintelligible values, and have different domains of input:

• 3394 requires an input to be a multiple of 64 bits (8 bytes), greater than zero.
• 5649 requires only that the input be non-empty.

OpenSSL offers both of these algorithms, calling them

• 3394: CRYPTO_128_wrap / CRYPTO_128_unwrap
• 5649: CRYPTO_128_wrap_pad / CRYPTO_128_wrap_unpad

Note that OpenSSL does not include "AES" in the name at all, just requiring that it be a padding algorithm based on 128-bit-block encryption (of which AES happens to be the only popular algorithm).

API Proposal

namespace System.Security.Cryptography
{
    public partial class Aes
    {
        // Alternate names:
        //   ExtendedKeyUnwrap
        //   PaddedKeyUnwrap
        //   UnwrapKeyPadded
        //   UnwrapPaddedKey
        //   (etc)
        public byte[] DecryptKeyWrapPadded(byte[] ciphertext);
        public byte[] DecryptKeyWrapPadded(System.ReadOnlySpan<byte> ciphertext);
        public int DecryptKeyWrapPadded(System.ReadOnlySpan<byte> ciphertext, System.Span<byte> destination);
        protected virtual int DecryptKeyWrapPaddedCore(System.ReadOnlySpan<byte> source, System.Span<byte> destination);
        public bool TryDecryptKeyWrapPadded(System.ReadOnlySpan<byte> ciphertext, System.Span<byte> destination, out int bytesWritten);

        public static int GetKeyWrapPaddedLength(int plaintextLengthInBytes);

        public byte[] EncryptKeyWrapPadded(byte[] plaintext);
        public byte[] EncryptKeyWrapPadded(System.ReadOnlySpan<byte> plaintext);
        public void EncryptKeyWrapPadded(System.ReadOnlySpan<byte> plaintext, System.Span<byte> destination);
        protected virtual void EncryptKeyWrapPaddedCore(System.ReadOnlySpan<byte> source, System.Span<byte> destination);
    }
}

Naming

RFC 5649's title uses the name "Key Wrap with Padding", which suggests KeyWrapPadded/KeyUnwrapPadded. But, in the body of the RFC, it uses a different name:

4. Specification of the AES Key Wrap with Padding Algorithm
   ...
   4.1. Extended Key Wrapping Process
   ...
   4.2. Extended Key Unwrapping Process

These names lead to a more flowing "ExtendedKeyWrap" and "ExtendedKeyUnwrap", which are the names proposed.

Other alternatives are KeyWrapRfc5649/KeyUnwrapRfc5649, or similar "include the RFC number".

Usage

byte[] wrapped = wrappingKey.EncryptKeyWrapPadded(toWrap);
Assert.Equal(wrapped.Length, Aes.GetKeyWrapPaddedLength(toWrap));
byte[] unwrapped = wrappingKey.DecryptKeyWrapPadded(wrapped);
Assert.SequenceEqual(wrapped, unwrapped);

Downlevel Concerns

If there's a need to expose this to NET8 (or even NetFramework), it can be done via a polyfill extension method in Microsoft.Bcl.Cryptography. The extension method would forward to the instance method (NET10+), or a non-extensible copy of the algorithm within M.B.C.

Such "backport" is not planned at this time.

[jackrichins]

We need the CKM_AES_KEY_WRAP_PAD mechanism, RFC5649, with support for key sizes 128, 192, and 256 key encryption keys and wrapped keys. For completeness, you may want to support 384 and 512 bit keys CKM_AES_KEY_WRAP.

Our end-to-end scenario is a three key hierarchy:
Key encryption key - in an HSM
Resource level key - wrapped by the key encryption key, in memory on a service machine. Gets persisted in service metadata wrapped by the KEK.
Data encryption key - wrapped by the resource level key, in memory while encrypting/decrypting data on the service machine.

Just for context of roadmap (not a requirement today), eventually we'd like the plaintext version of the resource level key and perhaps even the data encryption key to only exist in Keyguard. But that is a future requirement. For now, we simply want the wrap operations.

This is for teams implementing encryption at rest in Azure with key encryption keys in Key Vault or Managed HSM, though this is a standard pattern referred to as Envelope Encryption used by other cloud vendors as well. As NIST and NSA are recommending AES keys to be post-quantum safe rather than RSA keys as has been used in the past, we expect more teams to need this. Our team is building a library that would use this wrapping mechanism to help teams adopt AES key wrapping for encryption at rest with Azure Key Vault and Managed HSM.

[jackrichins]

Regarding which version beyond the next version of .Net,

I have no data to justify backporting to prior versions yet, but because of CNSA 2.0 timelines most services/applications should switch to AES-KW instead of RSA key wrap algorithms by 2030. So any version of .Net likely to still be in significant usage by 2030 will likely request backporting.

[vcsjones]

The API that I had in mind is basically this.

In an ideal, no-backport required scenario:

public abstract partial class Aes {
    public static int GetCiphertextLengthKeyWrapPadded(int plaintextLength);

    public byte[] EncryptKeyWrapPadded(byte[] plaintext);
    public byte[] EncryptKeyWrapPadded(System.ReadOnlySpan<byte> plaintext);
    public int EncryptKeyWrapPadded(ReadOnlySpan<byte> plaintext, Span<byte> destination);
    public bool TryEncryptKeyWrapPadded(ReadOnlySpan<byte> plaintext, Span<byte> destination, out int bytesWritten);
    protected virtual bool TryEncryptKeyWrapPaddedCore(ReadOnlySpan<byte> plaintext, Span<byte> destination, out int bytesWritten);
}

However, if we need to outbox this, we can't have instance members on Aes any more since that would not work with a type forward.

That would also mean we have no implementation point for user-derived types to override. Instead, we would implement it in terms of ICryptoTransform.TransformBlock calls in down level platforms. "In box" will still be able to do a better implementation since it can use the lite ciphers.

public static class AesKeyWrapExtensions {
    // We can't do extensions on types, so making this an extension is the next best option.
    public static int GetCiphertextLengthKeyWrapPadded(this Aes aes, int plaintextLength);

    public static byte[] EncryptKeyWrapPadded(this Aes aes, byte[] plaintext);
    public static byte[] EncryptKeyWrapPadded(this Aes aes, System.ReadOnlySpan<byte> plaintext);
    public static int EncryptKeyWrapPadded(this Aes aes, ReadOnlySpan<byte> plaintext, Span<byte> destination);
    public static bool TryEncryptKeyWrapPadded(this Aes aes, ReadOnlySpan<byte> plaintext, Span<byte> destination, out int bytesWritten);
}

Making this somewhat complicated is the fact that the algorithm instance of Aes has mode and padding associated with it. To implement AES-KW in terms of TransformBlock, we would need Aes at a minimum to have its mode in ECB. This makes the API shape a little rough but doable.

However I would also suggest that if down level is a real possibility, making the "right" decision early on is better than having two different AES-KW APIs later.

[blowdart]

I would suggest we do want down level in order to support 8 as it's still in LTS support and we know how slow folks are to update runtimes.

[bartonjs]

I've updated the proposal, and am marking it as ready-for-review (for tomorrow's session).

I'm open to early feedback that I've picked the wrong name (ExtendedKeyWrap vs KeyWrapPadded or PaddedKeyWrap or KeyWrap5649 or whatever) 😄.

To address some otherwise open (or implied) concerns:

What if we need this on NET8?

Find somewhere in M.B.C to shove in a polyfill extension method.

But the extension method approach isn't platform-extensible.

Indeed. Like with the polyfills we ended up with for the PQC project, the .NET 10 version will forward to the instance. There's no way for someone to override the implementation on .NET 8 or 9.

But if we needed to go all the way back to NETFX we couldn't!

Sure we could. If the instance is already in ECB+None, call CreateEncryptor/CreateDecryptor. If it isn't, then just make a new instance by reading aes.Key.

If it's not in ECB+None and the key isn't exportable... sure, then it'll fail. But it's NETFX, it's hard to have a non-exportable key. (Possible with AesCng, but "hard").

So are we doing the polyfill/backport?

No. Or, rather, "current evidence suggests it's not needed at this time". But it's not blocked by the instance method approach.

Motivation suggests a 2030 deadline, but .NET 8 and 9 will be out of support by then, and .NET 10 will be on its way out.

[vcsjones]

I'm open to early feedback that I've picked the wrong name (ExtendedKeyWrap vs KeyWrapPadded or PaddedKeyWrap or KeyWrap5649 or whatever) 😄.

I'm not a huge fan of the "Extended" part. I don't really ever see it referred to that in any other ecosystem, and all of the identifiers (The ASN.1 module) call it wrap-pad.

[bartonjs]

I changed the proposal to be based on DecryptKeyWrapPadded, which I don't particularly like. Hopefully the room has suggestions.

[bartonjs]

Video

Looks good as proposed.

namespace System.Security.Cryptography
{
    public partial class Aes
    {
        public byte[] DecryptKeyWrapPadded(byte[] ciphertext);
        public byte[] DecryptKeyWrapPadded(System.ReadOnlySpan<byte> ciphertext);
        public int DecryptKeyWrapPadded(System.ReadOnlySpan<byte> ciphertext, System.Span<byte> destination);
        protected virtual int DecryptKeyWrapPaddedCore(System.ReadOnlySpan<byte> source, System.Span<byte> destination);
        public bool TryDecryptKeyWrapPadded(System.ReadOnlySpan<byte> ciphertext, System.Span<byte> destination, out int bytesWritten);

        public static int GetKeyWrapPaddedLength(int plaintextLengthInBytes);

        public byte[] EncryptKeyWrapPadded(byte[] plaintext);
        public byte[] EncryptKeyWrapPadded(System.ReadOnlySpan<byte> plaintext);
        public void EncryptKeyWrapPadded(System.ReadOnlySpan<byte> plaintext, System.Span<byte> destination);
        protected virtual void EncryptKeyWrapPaddedCore(System.ReadOnlySpan<byte> source, System.Span<byte> destination);
    }
}