ClientCertificate breaking change

docs/core/compatibility/6.0.md

@@ -19,6 +19,7 @@ If you're migrating an app to .NET 6, the breaking changes listed here might aff
 - [Blazor: WebEventDescriptor.EventArgsType property replaced](aspnet-core/6.0/blazor-eventargstype-property-replaced.md)
 - [Blazor: Byte array interop](aspnet-core/6.0/byte-array-interop.md)
 - [Changed MessagePack library in @microsoft/signalr-protocol-msgpack](aspnet-core/6.0/messagepack-library-change.md)
+- [ClientCertificate property doesn't trigger renegotiation for HttpSys](aspnet-core/6.0/clientcertificate-doesnt-trigger-renegotiation.md)
 - [Kestrel: Log message attributes changed](aspnet-core/6.0/kestrel-log-message-attributes-changed.md)
 - [Microsoft.AspNetCore.Http.Features split](aspnet-core/6.0/microsoft-aspnetcore-http-features-package-split.md)
 - [Middleware: HTTPS Redirection Middleware throws exception on ambiguous HTTPS ports](aspnet-core/6.0/middleware-ambiguous-https-ports-exception.md)

docs/core/compatibility/aspnet-core/6.0/byte-array-interop.md

@@ -57,3 +57,15 @@ For example, if you have the following code, then you _should_ provide a `Uint8A
 ```csharp
 var bytes = await _jsRuntime.InvokeAsync<byte[]>("someJSMethodReturningAByteArray");
 ```
+
+<!--
+
+## Category
+
+ASP.NET Core
+
+## Affected APIs
+
+Not detectable via API analysis
+
+-->

docs/core/compatibility/aspnet-core/6.0/clientcertificate-doesnt-trigger-renegotiation.md

@@ -0,0 +1,59 @@
+---
+title: "Breaking change: ClientCertificate property no longer triggers renegotiation for HttpSys"
+description: "Learn about the breaking change in ASP.NET Core 6.0 where the ClientCertificate property no longer triggers renegotiation for HttpSys."
+ms.date: 07/20/2021
+no-loc: [ Kestrel ]
+---
+# ClientCertificate property no longer triggers renegotiation for HttpSys
+
+The [`HttpContext.Connection.ClientCertificate`](xref:Microsoft.AspNetCore.Http.ConnectionInfo.ClientCertificate?displayProperty=nameWithType) property no longer triggers TLS renegotiations for HttpSys.
+
+## Version introduced
+
+ASP.NET Core 6.0
+
+### Old behavior
+
+Setting `HttpSysOptions.ClientCertificateMethod = ClientCertificateMethod.AllowRenegotiation` allowed renegotiation to be triggered by both `HttpContext.Connection.ClientCertificate` and `HttpContext.Connection.GetClientCertifiateAsync`.
+
+### New behavior
+
+Setting `HttpSysOptions.ClientCertificateMethod = ClientCertificateMethod.AllowRenegotiation` allows renegotiation to be triggered only by `HttpContext.Connection.GetClientCertifiateAsync`. `HttpContext.Connection.ClientCertificate` returns the current certificate if available, but does not renegotiate with the client to request the certificate.
+
+## Reason for change
+
+When implementing the same features for Kestrel, it became clear that applications need to be able to check the state of the client certificate before triggering a renegotiation. For issues like the request body conflicting with the renegotiation, checking the state enables the following usage pattern to deal with the issue:
+
+```csharp
+if (connection.ClientCertificate == null)
+{
+  await BufferRequestBodyAsync();
+  await connection.GetClientCertificateAsync();
+}
+```
+
+## Recommended action
+
+Apps that use delayed client-certificate negotiation should call <xref:Microsoft.AspNetCore.Http.ConnectionInfo.GetClientCertificateAsync(System.Threading.CancellationToken)> to trigger renegotiation.
+
+## Affected APIs
+
+- <xref:Microsoft.AspNetCore.Server.HttpSys.HttpSysOptions.ClientCertificateMethod?displayProperty=fullName>
+- <xref:Microsoft.AspNetCore.Http.ConnectionInfo.ClientCertificate?displayProperty=fullName>
+- <xref:Microsoft.AspNetCore.Http.ConnectionInfo.GetClientCertificateAsync(System.Threading.CancellationToken)?displayProperty=fullName>
+
+## See also
+
+- [dotnet/aspnetcore issue number 34124](https://github.com/dotnet/aspnetcore/issues/34124)
+
+<!--
+
+## Category
+
+ASP.NET Core
+
+## Affected APIs
+
+Not detectable via API analysis
+
+-->

docs/core/compatibility/toc.yml

@@ -33,6 +33,8 @@ items:
           href: aspnet-core/6.0/blazor-eventargstype-property-replaced.md
         - name: "Blazor: Byte-array interop"
           href: aspnet-core/6.0/byte-array-interop.md
+        - name: ClientCertificate doesn't trigger renegotiation
+          href: aspnet-core/6.0/clientcertificate-doesnt-trigger-renegotiation.md
         - name: "Kestrel: Log message attributes changed"
           href: aspnet-core/6.0/kestrel-log-message-attributes-changed.md
         - name: "MessagePack: Library changed in @microsoft/signalr-protocol-msgpack"
@@ -401,6 +403,8 @@ items:
           href: aspnet-core/6.0/blazor-eventargstype-property-replaced.md
         - name: "Blazor: Byte-array interop"
           href: aspnet-core/6.0/byte-array-interop.md
+        - name: ClientCertificate doesn't trigger renegotiation
+          href: aspnet-core/6.0/clientcertificate-doesnt-trigger-renegotiation.md
         - name: "Kestrel: Log message attributes changed"
           href: aspnet-core/6.0/kestrel-log-message-attributes-changed.md
         - name: "MessagePack: Library changed in @microsoft/signalr-protocol-msgpack"