SslServerAuthenticationOptions - update documentation (#4367)

* SslServerAuthenticationOptions - update documentation

* Fix see reference

* apply PR comments

* apply PR comments

* Extend sslApplicationProtocol remark

* add default value for ApplicationProtocols

* fix closing tag

* fix closing tag

* apply review commevts

* Apply PR comments

* remove an article

* remove an article

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

Author: Jan Jahoda

xml/System.Net.Security/SslApplicationProtocol.xml

@@ -32,15 +32,17 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>Represents a values of TLS Application protocol.</summary>    
+    <summary>Represents a value of TLS Application protocol.</summary>    
     <remarks>
       <format type="text/markdown"><![CDATA[
 
 ## Remarks
+   
+This type contains static fields with predefined <xref:System.Net.Security.SslApplicationProtocol> values for HTTP versions.
 
-For list of supported protocols, see [TLS Application-Layer Protocol Negotiation (ALPN) Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids).
-    
-This class contains static field with predefined <xref:System.Net.Security.SslApplicationProtocol> values for HTTP versions.
+During the handshake, the client sends a list of available ALPN protocols and the server chooses the best match from that list. 
+
+For a complete list of supported protocols, see [TLS Application-Layer Protocol Negotiation (ALPN) Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids).
     
  ]]></format>    
     </remarks>

xml/System.Net.Security/SslServerAuthenticationOptions.xml

@@ -23,8 +23,15 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+    <summary>This struct represents a server 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.AuthenticateAsServer%2A>, or <xref:System.Net.Security.SslStream.AuthenticateAsServerAsync%2A>.
+  
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -46,7 +53,7 @@
       </AssemblyInfo>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Initializes a new instance of the <see cref="T:System.Net.Security.SslServerAuthenticationOptions" /> class.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -72,8 +79,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" /> allow SSL renegotiation; otherwise, <see langword="false" />. The default value is <see langword="true" />.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -99,7 +106,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 +133,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 check can be performed either by checking online or by checking against a cached revocation list. Revocation checking can be turned off 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.ArgumentException">
+          The value contains an invalid enumeration value.</exception>
       </Docs>
     </Member>
     <Member MemberName="CipherSuitesPolicy">
@@ -179,7 +197,7 @@
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets or sets a value that specifies whether the client is asked for a certificate for authentication. Note that this is only a request -- if no certificate is provided, the server still accepts the connection request.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -206,8 +224,8 @@
         <ReturnType>System.Security.Authentication.SslProtocols</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets or sets the <see cref="T:System.Security.Authentication.SslProtocols" /> value that represents protocols used for 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>
     </Member>
@@ -233,9 +251,11 @@
         <ReturnType>System.Net.Security.EncryptionPolicy</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets or sets the <see cref="T:System.Net.Security.EncryptionPolicy" />.</summary>
+        <value>The default value is <see cref="F:System.Net.Security.EncryptionPolicy.RequireEncryption" /></value>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentException">
+          The value contains an invalid enumeration value.</exception>
       </Docs>
     </Member>
     <Member MemberName="RemoteCertificateValidationCallback">
@@ -260,7 +280,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 responsible for custom validating the certificate supplied by the remote party.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -287,7 +307,7 @@
         <ReturnType>System.Security.Cryptography.X509Certificates.X509Certificate</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets or sets the server certificate.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -314,9 +334,16 @@
         <ReturnType>System.Net.Security.ServerCertificateSelectionCallback</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets or sets the <see cref="T:System.Net.Security.ServerCertificateSelectionCallback" /> delegate responsible for the server certificate selection.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks         
+        During the server connection establishment, the server first uses <xref:System.Net.Security.SslServerAuthenticationOptions.ServerCertificateSelectionCallback> callback. If the delegate is not provided server uses  <xref:System.Net.Security.LocalCertificateSelectionCallback> provided as argument of <xref:System.Net.Security.SslStream.%23ctor%2a?displayProperty=nameWithType> (for the .NET Framework compatibility). If none/neither of those callback are provided, the server falls back to <xref:System.Net.Security.SslServerAuthenticationOptions.ServerCertificate>.
+ 
+ ]]></format>        
+        </remarks>
       </Docs>
     </Member>
   </Members>

xml/System.Net.Security/SslStream.xml

@@ -668,7 +668,7 @@
       <Docs>
         <param name="targetHost">The name of the server that will share this <see cref="T:System.Net.Security.SslStream" />.</param>
         <param name="clientCertificates">The <see cref="T:System.Security.Cryptography.X509Certificates.X509CertificateCollection" /> that contains client certificates.</param>
-        <param name="enabledSslProtocols">The <see cref="T:System.Security.Authentication.SslProtocols" /> value that represents the protocol used for authentication.</param>
+        <param name="enabledSslProtocols">The <see cref="T:System.Security.Authentication.SslProtocols" /> value that represents protocols used for authentication.</param>
         <param name="checkCertificateRevocation">A <see cref="T:System.Boolean" /> value that specifies whether the certificate revocation list is checked during authentication.</param>
         <summary>Called by clients to authenticate the server and optionally the client in a client-server connection. The authentication process uses the specified certificate collection and SSL protocol.</summary>
         <remarks>
@@ -925,7 +925,7 @@
       <Docs>
         <param name="targetHost">The name of the server that will share this <see cref="T:System.Net.Security.SslStream" />.</param>
         <param name="clientCertificates">The <see cref="T:System.Security.Cryptography.X509Certificates.X509CertificateCollection" /> that contains client certificates.</param>
-        <param name="enabledSslProtocols">The <see cref="T:System.Security.Authentication.SslProtocols" /> value that represents the protocol used for authentication.</param>
+        <param name="enabledSslProtocols">The <see cref="T:System.Security.Authentication.SslProtocols" /> value that represents protocols used for authentication.</param>
         <param name="checkCertificateRevocation">A <see cref="T:System.Boolean" /> value that specifies whether the certificate revocation list is checked during authentication.</param>
         <summary>Called by clients to authenticate the server and optionally the client in a client-server connection as an asynchronous operation. The authentication process uses the specified certificate collection and SSL protocol.</summary>
         <returns>The task object representing the asynchronous operation.</returns>
@@ -1137,7 +1137,7 @@
       <Docs>
         <param name="serverCertificate">The X509Certificate used to authenticate the server.</param>
         <param name="clientCertificateRequired">A <see cref="T:System.Boolean" /> value that specifies whether the client is asked for a certificate for authentication. Note that this is only a request -- if no certificate is provided, the server still accepts the connection request.</param>
-        <param name="enabledSslProtocols">The <see cref="T:System.Security.Authentication.SslProtocols" /> value that represents the protocol used for authentication.</param>
+        <param name="enabledSslProtocols">The <see cref="T:System.Security.Authentication.SslProtocols" /> value that represents protocols used for authentication.</param>
         <param name="checkCertificateRevocation">A <see cref="T:System.Boolean" /> value that specifies whether the certificate revocation list is checked during authentication.</param>
         <summary>Called by servers to authenticate the server and optionally the client in a client-server connection using the specified certificates, requirements and security protocol.</summary>
         <remarks>
@@ -1405,7 +1405,7 @@
       <Docs>
         <param name="serverCertificate">The X509Certificate used to authenticate the server.</param>
         <param name="clientCertificateRequired">A <see cref="T:System.Boolean" /> value that specifies whether the client is asked for a certificate for authentication. Note that this is only a request -- if no certificate is provided, the server still accepts the connection request.</param>
-        <param name="enabledSslProtocols">The <see cref="T:System.Security.Authentication.SslProtocols" /> value that represents the protocol used for authentication.</param>
+        <param name="enabledSslProtocols">The <see cref="T:System.Security.Authentication.SslProtocols" /> value that represents protocols used for authentication.</param>
         <param name="checkCertificateRevocation">A <see cref="T:System.Boolean" /> value that specifies whether the certificate revocation list is checked during authentication.</param>
         <summary>Called by servers to authenticate the server and optionally the client in a client-server connection using the specified certificates, requirements and security protocol as an asynchronous operation.</summary>
         <returns>The task object representing the asynchronous operation.</returns>
@@ -1642,7 +1642,7 @@
       <Docs>
         <param name="targetHost">The name of the server that shares this <see cref="T:System.Net.Security.SslStream" />.</param>
         <param name="clientCertificates">The <see cref="T:System.Security.Cryptography.X509Certificates.X509CertificateCollection" /> containing client certificates.</param>
-        <param name="enabledSslProtocols">The <see cref="T:System.Security.Authentication.SslProtocols" /> value that represents the protocol used for authentication.</param>
+        <param name="enabledSslProtocols">The <see cref="T:System.Security.Authentication.SslProtocols" /> value that represents protocols used for authentication.</param>
         <param name="checkCertificateRevocation">A <see cref="T:System.Boolean" /> value that specifies whether the certificate revocation list is checked during authentication.</param>
         <param name="asyncCallback">An <see cref="T:System.AsyncCallback" /> delegate that references the method to invoke when the authentication is complete.</param>
         <param name="asyncState">A user-defined object that contains information about the operation. This object is passed to the <paramref name="asyncCallback" /> delegate when the operation completes.</param>
@@ -1894,7 +1894,7 @@
       <Docs>
         <param name="serverCertificate">The X509Certificate used to authenticate the server.</param>
         <param name="clientCertificateRequired">A <see cref="T:System.Boolean" /> value that specifies whether the client is asked for a certificate for authentication. Note that this is only a request -- if no certificate is provided, the server still accepts the connection request.</param>
-        <param name="enabledSslProtocols">The <see cref="T:System.Security.Authentication.SslProtocols" /> value that represents the protocol used for authentication.</param>
+        <param name="enabledSslProtocols">The <see cref="T:System.Security.Authentication.SslProtocols" /> value that represents protocols used for authentication.</param>
         <param name="checkCertificateRevocation">A <see cref="T:System.Boolean" /> value that specifies whether the certificate revocation list is checked during authentication.</param>
         <param name="asyncCallback">An <see cref="T:System.AsyncCallback" /> delegate that references the method to invoke when the authentication is complete.</param>
         <param name="asyncState">A user-defined object that contains information about the operation. This object is passed to the <paramref name="asyncCallback" /> delegate when the operation completes.</param>
@@ -4142,7 +4142,7 @@ This property gets the cipher suite that is going to be used in the communicatio
       </ReturnValue>
       <Docs>
         <summary>Gets a value that indicates the security protocol used to authenticate this connection.</summary>
-        <value>The <see cref="T:System.Security.Authentication.SslProtocols" /> value that represents the protocol used for authentication.</value>
+        <value>The <see cref="T:System.Security.Authentication.SslProtocols" /> value that represents protocols used for authentication.</value>
         <remarks>
           <format type="text/markdown"><![CDATA[  
   

xml/System.Security.Authentication/SslProtocols.xml

@@ -39,6 +39,11 @@
     <summary>Defines the possible versions of <see cref="T:System.Security.Authentication.SslProtocols" />.</summary>
     <remarks>
       <format type="text/markdown"><![CDATA[  
+      
+## Remarks
+
+  During the handshake, the client sends a list of SSL versions and the server chooses the best matching version from that list.
+   
  ]]></format>
     </remarks>
   </Docs>