SslClientAuthenticationOptions - update documentation (#4366)

* NegotiateStream - update documentation

* Fix revocation mode

* Fix see reference

* minor changes

* Fix reference in class description

* Apply PR comments

* fix closing tag

* apply review comments

* Update xml/System.Net.Security/SslClientAuthenticationOptions.xml

Co-authored-by: Genevieve Warren <[email protected]>

* Remove wrong ApplicationProtocols description

* RP comments

* RP comments

* Apply suggestions from code review

Co-authored-by: Genevieve Warren <[email protected]>

* Fix remark is not visible

Co-authored-by: Jan Jahoda <[email protected]>
Co-authored-by: Genevieve Warren <[email protected]>

Author: 3 people

xml/System.Net.Security/SslClientAuthenticationOptions.xml

@@ -23,8 +23,17 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+    <summary>Represents a client authentication property bag for the <see cref="T:System.Net.Security.SslStream" />.</summary>    
+    <remarks>
+     <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+ This property bag is used as argument for <xref:System.Net.Security.SslStream.AuthenticateAsClientAsync%2A> and, in .NET 5.0 and later versions, for <xref:System.Net.Security.SslStream.AuthenticateAsClient%2A>.
+ 
+ The <xref:System.Net.Http.SocketsHttpHandler> uses this property bag in the <xref: System.Net.Http.SocketsHttpHandler.SslOptions%2A> property.
+  
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -46,7 +55,7 @@
       </AssemblyInfo>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Initializes a new instance of the <see cref="T:System.Net.Security.SslClientAuthenticationOptions" /> class.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -72,8 +81,8 @@
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets or sets a value that indicates whether the <see cref="T:System.Net.Security.SslStream" /> should allow SSL renegotiation.</summary>
+        <value><see langword="true" /> to indicate that the <see cref="T:System.Net.Security.SslStream" /> allows SSL renegotiation; otherwise, <see langword="false" />. The default value is <see langword="true" />.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -99,7 +108,7 @@
         <ReturnType>System.Collections.Generic.List&lt;System.Net.Security.SslApplicationProtocol&gt;</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets or sets a list of ALPN protocols.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -126,9 +135,20 @@
         <ReturnType>System.Security.Cryptography.X509Certificates.X509RevocationMode</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary>Gets or sets the certificate revocation mode for certificate validation.</summary>
+        <value>One of the values in <see cref="T:System.Security.Cryptography.X509Certificates.X509RevocationMode" />: <see langword="NoCheck" />, <see langword="Online" />, or <see langword="Offline" />. The default is <see langword="Online" />.</value>       
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+ When using certificates, the system validates that the client certificate is not revoked by checking that the client certificate is not in the revoked certificate list. This validation can be performed by checking online or against a cached revocation list. You can trun off revocation checking by setting this property to <xref:System.Security.Cryptography.X509Certificates.X509RevocationMode.NoCheck>.  
+  
+ For more information, see [Working with Certificates](/dotnet/framework/wcf/feature-details/working-with-certificates).  
+    
+ ]]></format>
+        </remarks>
+        <exception cref="T:System.ArgumentNullException">
+          The value contains an invalid enumeration value.</exception>
       </Docs>
     </Member>
     <Member MemberName="CipherSuitesPolicy">
@@ -179,9 +199,17 @@
         <ReturnType>System.Security.Cryptography.X509Certificates.X509CertificateCollection</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>A collection of certificates to be considered for the client's authentication to the server.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>        
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+ 
+ <xref:System.Net.Security.LocalCertificateSelectionCallback> can be used to select a specific certificate to offer to the server. 
+ 
+ ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="EnabledSslProtocols">
@@ -206,8 +234,8 @@
         <ReturnType>System.Security.Authentication.SslProtocols</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets or sets the value that represents the protocol versions offered by the client to the server during authentication.</summary>
+        <value>The default value is <see cref="F:System.Security.Authentication.SslProtocols.None" />, which is the recommended value. For more information, see <see cref="T:System.Security.Authentication.SslProtocols" />.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -233,8 +261,8 @@
         <ReturnType>System.Net.Security.EncryptionPolicy</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets or sets the encryption policy.</summary>
+        <value>The default value is <see cref="F:System.Net.Security.EncryptionPolicy.RequireEncryption" />.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -260,7 +288,7 @@
         <ReturnType>System.Net.Security.LocalCertificateSelectionCallback</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets or sets a <see cref="T:System.Net.Security.LocalCertificateSelectionCallback" /> delegate that's responsible for selecting the client authentication certificate used for authentication.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -287,7 +315,7 @@
         <ReturnType>System.Net.Security.RemoteCertificateValidationCallback</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets or sets a <see cref="T:System.Net.Security.RemoteCertificateValidationCallback" /> delegate that's responsible for validating the certificate supplied by the remote party.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -314,7 +342,7 @@
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets or sets the name of the server the client is trying to connect to. That name is used for server certificate validation. It can be a DNS name or an IP address.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>

xml/System.Net.Security/SslServerAuthenticationOptions.xml

@@ -225,7 +225,7 @@
         <ReturnType>System.Security.Authentication.SslProtocols</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets or sets the <see cref="T:System.Security.Authentication.SslProtocols" /> value that represents protocols used for authentication.</summary>
+        <summary>Gets or sets a value that represents protocol versions used by the server to match the client protocol version during authentication.</summary>
         <value>The default value is <see cref="F:System.Security.Authentication.SslProtocols.None" />, which is the recommended value. See <see cref="T:System.Security.Authentication.SslProtocols" /> for more details.</value>
         <remarks>To be added.</remarks>
       </Docs>