From c80dbff6f25b483c329dbbb90a2008c937803c95 Mon Sep 17 00:00:00 2001
From: Chris Ross <chrross@microsoft.com>
Date: Wed, 8 Sep 2021 16:45:14 -0700
Subject: [PATCH] Doc "SslProtocols" and "ClientCertificateMode" settable via
 config (#23241)

---
 .../fundamentals/servers/kestrel/endpoints.md | 52 +++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/aspnetcore/fundamentals/servers/kestrel/endpoints.md b/aspnetcore/fundamentals/servers/kestrel/endpoints.md
index ac473d828c..fc13a6146b 100644
--- a/aspnetcore/fundamentals/servers/kestrel/endpoints.md
+++ b/aspnetcore/fundamentals/servers/kestrel/endpoints.md
@@ -402,8 +402,60 @@ webBuilder.ConfigureKestrel(serverOptions =>
 });
 ```
 
+```json
+{
+  "Kestrel": {
+    "Endpoints": {
+      "MyHttpsEndpoint": {
+        "Url": "https://localhost:5001",
+        "SslProtocols": ["Tls12", "Tls13"],
+        "Certificate": {
+          "Path": "<path to .pfx file>",
+          "Password": "<certificate password>"
+        }
+      }
+    }
+  }
+}
+```
+
 The default value, `SslProtocols.None`, causes Kestrel to use the operating system defaults to choose the best protocol. Unless you have a specific reason to select a protocol, use the default.
 
+## Client Certificates
+
+`ClientCertificateMode` configures the [client certificate requirements](xref:Microsoft.AspNetCore.Server.Kestrel.Https.ClientCertificateMode).
+
+```csharp
+webBuilder.ConfigureKestrel(serverOptions =>
+{
+    serverOptions.ConfigureHttpsDefaults(listenOptions =>
+    {
+        listenOptions.ClientCertificateMode = ClientCertificateMode.AllowCertificate;
+    });
+});
+```
+
+```json
+{
+  "Kestrel": {
+    "Endpoints": {
+      "MyHttpsEndpoint": {
+        "Url": "https://localhost:5001",
+        "ClientCertificateMode": "AllowCertificate",
+        "Certificate": {
+          "Path": "<path to .pfx file>",
+          "Password": "<certificate password>"
+        }
+      }
+    }
+  }
+}
+```
+
+The default value is `ClientCertificateMode.NoCertificate` where Kestrel will not request or require a certificate from the client.
+
+See [Certificate Authenticaiton](/aspnet/core/security/authentication/certauth) for more details.
+
 ## Connection logging
 
 Call <xref:Microsoft.AspNetCore.Hosting.ListenOptionsConnectionLoggingExtensions.UseConnectionLogging%2A> to emit Debug level logs for byte-level communication on a connection. Connection logging is helpful for troubleshooting problems in low-level communication, such as during TLS encryption and behind proxies. If `UseConnectionLogging` is placed before `UseHttps`, encrypted traffic is logged. If `UseConnectionLogging` is placed after `UseHttps`, decrypted traffic is logged. This is built-in [Connection Middleware](#connection-middleware).