Introduce ListenOptions.GetServerCertificate

[amcasey]

Background and Motivation

The original fix for #45801 had to be rolled back because it broke an internal partner that depended on UseHttps failing fast in the absence of a certificate. Rather than having them continue to rely on the behavior (which we want to change), we should introduce an API that allows them to check for certificates explicitly (originally requested in #28120).

Proposed API

See #48054

namespace Microsoft.AspNetCore.Hosting;

public static class ListenOptionsHttpsExtensions
{
+    /// <summary>
+    /// Retrieve the server certificate, if any, for an endpoint; otherwise, throw.
+    /// Should not be called before the configuration is loaded, if there is one.
+    /// </summary>
+    /// <param name="listenOptions">The <see cref="ListenOptions"/> to configure.</param>
+    /// <returns>The server certificate for this endpoint.</returns>
+    /// <exception cref="InvalidOperationException">If there is no server certificate for this endpoint.</exception>
+    /// <exception cref="InvalidOperationException">If there is a configuration and it has not been loaded.</exception>
+    public static X509Certificate2 GetServerCertificate(this ListenOptions listenOptions)
}

Usage Examples

webHostBuilder
    .UseKestrel(options =>
    {
        options.Configure(/* ... */);
        options.ConfigurationLoader.Load();

        options.Listen(IPAddress.Loopback, 5000, listenOptions =>
        {
                // No HTTPS
        });

        try
        {
            options.Listen(IPAddress.Loopback, 5001, listenOptions =>
            {
                listenOptions.GetServerCertificate();
                listenOptions.UseHttps();
            });
        }
        catch
        {
            Console.WriteLine("No https");
        }
    })

Alternative Designs

We could have gone with TryGet but our partner expressed a preference for getting an explanatory exception message.
We could have made UseHttps fail eagerly, but that would have introduced a lot of complexity, chiefly around handling configuration changes between UseHttps and bind-time.

Risks

It's a little wonky that you have to explicitly load the configuration yourself, but this is a very niche scenario.

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[Tratcher]

We could have gone with TryGet but our partner expressed a preference for getting an explanatory exception message.

The implementation only throws NoCertSpecifiedNoDevelopmentCertificateFound, that doesn't seem like meaningful information, or are there other exceptions that could be thrown here?

Here's the usage I'd like to see:

webHostBuilder
    .UseKestrel(options =>
    {
        options.Configure(/* ... */);
        options.ConfigurationLoader.Load();

        options.Listen(IPAddress.Loopback, 5000, listenOptions =>
        {
                // No HTTPS
        });

        if (options.CheckForDefaultHttpsCert())
        {
            options.Listen(IPAddress.Loopback, 5001, listenOptions =>
            {
                listenOptions.UseHttps();
            });
        }
        else
        {
            Console.WriteLine("No https");
        }
    })

[amcasey]

@Tratcher I suggested something like that and they were very explicit about not wanting to have to get into the business of formulating a description of what had failed (i.e. they wanted us to produce a string). Of course, I don't think we realized at the time that only one error message would ever be produced (assuming that's the case, which it appears to be).

I also asked whether we could do a global (vs per-endpoint) check like that and understood them to say that they were sometimes deployed in production and needed to handle real cert configuration, which is per-endpoint.

I definitely agree that not calling Listen (or having something like TryListen) would be much clearer, but @halter73 and I didn't think the extra complexity was justified for this narrow use case.

Edit: Chris pointed out offline that the original PR doesn't actually look at per-endpoint certs. 🤦

[amcasey]

Background and Motivation

The original fix for #45801 had to be rolled back because it broke an internal partner that depended on UseHttps failing fast in the absence of a certificate. Rather than having them continue to rely on the behavior (which we want to change), we should introduce an API that allows them to check for certificates explicitly (originally requested in #28120).

Proposed API

See #48057

namespace Microsoft.AspNetCore.Server.Kestrel.Core;

public class KestrelServerOptions
{
+    /// <summary>
+    /// Return true if there is a default or development server certificate.
+    /// Should not be called before the configuration is loaded, if there is one.
+    /// </summary>
+    /// <returns>True if there is a default or development server certificate, false otherwise.</returns>
+    /// <exception cref="InvalidOperationException">If there is a configuration and it has not been loaded.</exception>
+    public bool CheckDefaultCertificate()
}

Usage Examples

webHostBuilder
    .UseKestrel(options =>
    {
        options.Configure(/* ... */);
        options.ConfigurationLoader.Load();

        options.Listen(IPAddress.Loopback, 5000, listenOptions =>
        {
                // No HTTPS
        });

        if (options.CheckDefaultCertificate())
        {
            options.Listen(IPAddress.Loopback, 5001, listenOptions =>
            {
                listenOptions.UseHttps();
            });
        }
        else 
        {
            Log("Skipping HTTPS endpoint Foo due to lack of cert");
        }
    })

Alternative Designs

The one in the description, obviously.

Risks

It's a little wonky that you have to explicitly load the configuration yourself, but this is a very niche scenario.

[amcasey]

We're going to try to fix things without a new API.