[API Proposal]: Export Keying Material for TLS sessions

[alanssitis]

Background and motivation

Add an API that exposes the functionality outlined in RFC 5705: Keying Material Exporters.

This is useful as it will allow my company to drop an external library to use this functionality.

API Proposal

updated by @rzikm

namespace System.Net.Security;

public partial class SslStream {
    public void ExportKeyingMaterial(string label, Span<byte>output);

    public void ExportKeyingMaterial(string label, ReadOnlySpan<byte> context, Span<byte> output);
}

API Usage

await using var sslStream = new SslStream(someStream, true);

// Initialize and finish SSL handshake
await sslStream.AuthenticateAsServerAsync(...);
// or as client
// await sslStream.AuthenticateAsClientAsync(...);

// Use the export keying material API
byte[] keyingMaterial = new byte[128];
sslStream.ExportKeyingMaterial("showcase key", keyingMaterial);
Console.WriteLine(Convert.ToHexString(keyingMaterial));

Alternative proposal

Unless I am mistaken, the label string is supposed to be an ASCII string, so we can accept it as ROS

namespace System.Net.Security;

public partial class SslStream {
    public void ExportKeyingMaterial(ReadOnlySpan<byte> label, Span<byte>output);

    public void ExportKeyingMaterial(ReadOnlySpan<byte> label, ReadOnlySpan<byte> context, Span<byte> output);
}

API Usage

since labels are usually literal constants in code, UTF-8 string literals can be used

byte[] keyingMaterial = new byte[128];
sslStream.ExportKeyingMaterial("showcase key"u8, keyingMaterial);
Console.WriteLine(Convert.ToHexString(keyingMaterial));

Risks

Platform support:

• Windows - needs verification (should be implementable as per
  https://learn.microsoft.com/en-us/windows/win32/api/schannel/ns-schannel-secpkgcontext_keyingmaterialinfo, https://learn.microsoft.com/en-us/windows/win32/secauthn/querycontextattributes--schannel, see SECPKG_ATTR_KEYING_MATERIAL)
• Linux - implementable (https://docs.openssl.org/master/man3/SSL_export_keying_material/)
• OSX - Not implemented for Secure Transport (package used to back SslStream implementaion)

[dotnet-policy-service]

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

[wfurt]

AFAIK this is not feasible on Windows at this moment.

[teo-tsirpanis]

We should also add these APIs:

namespace System.Net.Security;

public partial class SslStream {
    public void ExportKeyingMaterial(string label, Span<byte> output);

    public void ExportKeyingMaterial(string label, ReadOnlySpan<byte> context, Span<byte> output);
}

[rzikm]

It seems this might be viable on Windows as well, see

https://learn.microsoft.com/en-us/windows/win32/api/schannel/ns-schannel-secpkgcontext_keyingmaterialinfo

We should test it out before proceeding, but the docs mention the specific RFC so I am hopeful.

OpenSSL is more straightforward:

OpenSSL: https://docs.openssl.org/master/man3/SSL_export_keying_material/

There seem to be similar functions on Apple crypto (but not in Secure Transport package we are currently using), not sure how feasible this is for Android

From API perspective, the RFC specifies

     The exporter takes three input values:
  
     o  a disambiguating label string,
  
     o  a per-association context value provided by the application using
        the exporter, and
  
     o  a length value.

In general, we tend to prefer Span-based APIs now as they are more flexible, so proposition from teo-tsirpanis seems like the better choice.

[skizzerz]

Having this feature would be useful for me as well. Right now I'm trying to work around it with P/Invoke but having an API baked in would be nicer, especially due to the libssl naming mess for linux support.

Android: https://developer.android.com/reference/android/net/ssl/SSLEngines#exportKeyingMaterial(javax.net.ssl.SSLEngine,%20java.lang.String,%20byte[],%20int) is available in API levels 31+ (seems coreclr targets 21 as the minimum SDK version, however, based on the documentation I found)

macOS: https://developer.apple.com/documentation/security/sec_protocol_metadata_create_secret_with_context(_:_:_:_:_:_:) although as noted above, this is using different APIs than the Secure Transport package. #1979 seems relevant here, since moving to the Network API would allow use of the sec_protocol_metadata_create_secret_with_context() function needed for this feature.

[Neustradamus]

Any progress on it?

[wfurt]

no, but it should be doable in 11.0 if we get API approved.