Document security risks of fixed multi-byte encodings in HTTP header encoding selectors

xml/System.Net.Http/SocketsHttpHandler.xml

@@ -1124,7 +1124,20 @@ For example, if the value is 64, then 65,536 bytes are allowed for the maximum r
       <Docs>
         <summary>Gets or sets a callback that selects the <see cref="System.Text.Encoding" /> to encode request header values.</summary>
         <value>The header encoding selector callback that selects the <see cref="System.Text.Encoding" /> to encode the value for the specified request header name, or <see langword="null" /> to indicate the default behavior.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+When specifying an encoding, you're generally expected to use one of the following encoding schemes: <xref:System.Text.Encoding.ASCII>, <xref:System.Text.Encoding.Latin1>, or <xref:System.Text.Encoding.UTF8>. Other encoding schemes might be susceptible to request smuggling attacks.
+
+> [!CAUTION]
+> Fixed multi-byte encoding schemes in particular (for example, <xref:System.Text.Encoding.Unicode> or <xref:System.Text.Encoding.UTF32>) must never be used, as their binary representation is likely to be misinterpreted and break the protocol. For instance, part of `✊` might be interpreted as a new line (`\n`) that terminates the header value.
+
+When you specify an encoding, it's your responsibility to ensure that the values are representable via the encoding, and that the server agrees on the encoding used. Otherwise, values will become corrupted. For example, since any set of bytes is considered a valid Latin1 sequence, a server replying with UTF-8 encoded header values might see its responses silently corrupted.
+
+ ]]></format>
+        </remarks>
         <exception cref="T:System.InvalidOperationException">An operation has already been started on the current instance.</exception>
         <exception cref="T:System.ObjectDisposedException">The current instance has been disposed.</exception>
       </Docs>
@@ -1199,7 +1212,20 @@ The timeout specified is greater than <see cref="F:System.Int32.MaxValue" /> mil
       <Docs>
         <summary>Gets or sets a callback that selects the <see cref="System.Text.Encoding" /> to decode response header values.</summary>
         <value>The header encoding selector callback that selects the <see cref="System.Text.Encoding" /> to decode the value for the specified response header name, or <see langword="null" /> to indicate the default behavior.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+When specifying an encoding, you're generally expected to use one of the following encoding schemes: <xref:System.Text.Encoding.ASCII>, <xref:System.Text.Encoding.Latin1>, or <xref:System.Text.Encoding.UTF8>. Other encoding schemes might be susceptible to request smuggling attacks.
+
+> [!CAUTION]
+> Fixed multi-byte encoding schemes in particular (for example, <xref:System.Text.Encoding.Unicode> or <xref:System.Text.Encoding.UTF32>) must never be used, as their binary representation is likely to be misinterpreted and break the protocol. For instance, part of `✊` might be interpreted as a new line (`\n`) that terminates the header value.
+
+When you specify an encoding, it's your responsibility to ensure that the values are representable via the encoding, and that the server agrees on the encoding used. Otherwise, values will become corrupted. For example, since any set of bytes is considered a valid Latin1 sequence, a server replying with UTF-8 encoded header values might see its responses silently corrupted.
+
+ ]]></format>
+        </remarks>
         <exception cref="T:System.InvalidOperationException">An operation has already been started on the current instance.</exception>
         <exception cref="T:System.ObjectDisposedException">The current instance has been disposed.</exception>
       </Docs>