Skip to content

Commit d89c3c4

Browse files
Jan JahodaJan JahodaManickaPgewarren
authored
SslStream - update documentation (#4372)
* SslStream - update documentation * Add AuthenticateAsServerAsync * Add NegotiatedApplicationProtocol * Add FlushAsync * Apply suggestions from code review Co-authored-by: Marie Píchová <[email protected]> * Apply PR comments * Apply suggestions from code review Co-authored-by: Genevieve Warren <[email protected]> Co-authored-by: Jan Jahoda <[email protected]> Co-authored-by: Marie Píchová <[email protected]> Co-authored-by: Genevieve Warren <[email protected]>
1 parent 7566b64 commit d89c3c4

File tree

1 file changed

+117
-16
lines changed

1 file changed

+117
-16
lines changed

‎xml/System.Net.Security/SslStream.xml

Lines changed: 117 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -792,11 +792,34 @@
792792
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="net-5.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netstandard-2.1" />
793793
</Parameters>
794794
<Docs>
795-
<param name="sslClientAuthenticationOptions">To be added.</param>
796-
<param name="cancellationToken">To be added.</param>
797-
<summary>To be added.</summary>
798-
<returns>To be added.</returns>
799-
<remarks>To be added.</remarks>
795+
<param name="sslClientAuthenticationOptions">The property bag for the SSL connection.</param>
796+
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
797+
<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 information specified in the <see param="System.Net.Security.SslClientAuthenticationOptions" /> property bag.</summary>
798+
<returns>The task object representing the asynchronous operation.</returns>
799+
<remarks>
800+
<format type="text/markdown"><![CDATA[
801+
802+
## Remarks
803+
804+
When authentication succeeds, you must check the <xref:System.Net.Security.SslStream.IsEncrypted%2A> and <xref:System.Net.Security.SslStream.IsSigned%2A> properties to determine what security services are used by the <xref:System.Net.Security.SslStream>. Check the <xref:System.Net.Security.SslStream.IsMutuallyAuthenticated%2A> property to determine whether mutual authentication occurred.
805+
806+
If the authentication fails, you receive a <xref:System.Security.Authentication.AuthenticationException>, and this <xref:System.Net.Security.SslStream> is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector.
807+
808+
]]></format>
809+
</remarks>
810+
<exception cref="T:System.ArgumentNullException">
811+
<paramref name="sslClientAuthenticationOptions" /> is <see langword="null" />.</exception>
812+
<exception cref="T:System.Security.Authentication.AuthenticationException">The authentication failed and left this object in an unusable state.</exception>
813+
<exception cref="T:System.InvalidOperationException">Authentication has already occurred.
814+
815+
-or-
816+
817+
Server authentication using this <see cref="T:System.Net.Security.SslStream" /> was tried previously.
818+
819+
-or-
820+
821+
Authentication is already in progress.</exception>
822+
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
800823
</Docs>
801824
</Member>
802825
<Member MemberName="AuthenticateAsClientAsync">
@@ -851,6 +874,17 @@
851874
852875
]]></format>
853876
</remarks>
877+
<exception cref="T:System.Security.Authentication.AuthenticationException">The authentication failed and left this object in an unusable state.</exception>
878+
<exception cref="T:System.InvalidOperationException">Authentication has already occurred.
879+
880+
-or-
881+
882+
Server authentication using this <see cref="T:System.Net.Security.SslStream" /> was tried previously.
883+
884+
-or-
885+
886+
Authentication is already in progress.</exception>
887+
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
854888
</Docs>
855889
</Member>
856890
<Member MemberName="AuthenticateAsClientAsync">
@@ -910,6 +944,17 @@
910944
911945
]]></format>
912946
</remarks>
947+
<exception cref="T:System.Security.Authentication.AuthenticationException">The authentication failed and left this object in an unusable state.</exception>
948+
<exception cref="T:System.InvalidOperationException">Authentication has already occurred.
949+
950+
-or-
951+
952+
Server authentication using this <see cref="T:System.Net.Security.SslStream" /> was tried previously.
953+
954+
-or-
955+
956+
Authentication is already in progress.</exception>
957+
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
913958
</Docs>
914959
</Member>
915960
<MemberGroup MemberName="AuthenticateAsServer">
@@ -1230,11 +1275,34 @@
12301275
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="net-5.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netstandard-2.1" />
12311276
</Parameters>
12321277
<Docs>
1233-
<param name="sslServerAuthenticationOptions">To be added.</param>
1234-
<param name="cancellationToken">To be added.</param>
1235-
<summary>To be added.</summary>
1236-
<returns>To be added.</returns>
1237-
<remarks>To be added.</remarks>
1278+
<param name="sslServerAuthenticationOptions">The property bag for the SSL connection.</param>
1279+
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
1280+
<summary>Called by servers to authenticate the server and optionally the client in a client-server connection as an asynchronous operation. The authentication process uses information specified in the <see param="System.Net.Security.SslServerAuthenticationOptions" /> property bag.</summary>
1281+
<returns>The task object representing the asynchronous operation.</returns>
1282+
<remarks>
1283+
<format type="text/markdown"><![CDATA[
1284+
1285+
## Remarks
1286+
1287+
If the authentication fails, you receive a <xref:System.Security.Authentication.AuthenticationException>, and this <xref:System.Net.Security.SslStream> is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector.
1288+
1289+
]]></format>
1290+
</remarks>
1291+
<exception cref="T:System.ArgumentNullException">
1292+
Either <see cref="P:System.Net.Security.SslServerAuthenticationOptions.ServerCertificateSelectionCallback" /> or <see cref="P:System.Net.Security.SslServerAuthenticationOptions.ServerCertificate" /> is <see langword="null" /> and <see cref="T:System.Net.Security.LocalCertificateSelectionCallback" /> is not set in the <see cref="M:System.Net.Security.SslStream.#ctor" /> constructor.</exception>
1293+
<exception cref="T:System.ArgumentNullException">
1294+
<paramref name="sslServerAuthenticationOptions" /> is <see langword="null" />.</exception>
1295+
<exception cref="T:System.Security.Authentication.AuthenticationException">The authentication failed and left this object in an unusable state.</exception>
1296+
<exception cref="T:System.InvalidOperationException">Authentication has already occurred.
1297+
1298+
-or-
1299+
1300+
Client authentication using this <see cref="T:System.Net.Security.SslStream" /> was tried previously.
1301+
1302+
-or-
1303+
1304+
Authentication is already in progress.</exception>
1305+
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
12381306
</Docs>
12391307
</Member>
12401308
<Member MemberName="AuthenticateAsServerAsync">
@@ -1284,6 +1352,19 @@
12841352
12851353
]]></format>
12861354
</remarks>
1355+
<exception cref="T:System.ArgumentNullException">
1356+
<paramref name="serverCertificate" /> is <see langword="null" />.</exception>
1357+
<exception cref="T:System.Security.Authentication.AuthenticationException">The authentication failed and left this object in an unusable state.</exception>
1358+
<exception cref="T:System.InvalidOperationException">Authentication has already occurred.
1359+
1360+
-or-
1361+
1362+
Client authentication using this <see cref="T:System.Net.Security.SslStream" /> was tried previously.
1363+
1364+
-or-
1365+
1366+
Authentication is already in progress.</exception>
1367+
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
12871368
</Docs>
12881369
</Member>
12891370
<Member MemberName="AuthenticateAsServerAsync">
@@ -1338,6 +1419,19 @@
13381419
13391420
]]></format>
13401421
</remarks>
1422+
<exception cref="T:System.ArgumentNullException">
1423+
<paramref name="serverCertificate" /> is <see langword="null" />.</exception>
1424+
<exception cref="T:System.Security.Authentication.AuthenticationException">The authentication failed and left this object in an unusable state.</exception>
1425+
<exception cref="T:System.InvalidOperationException">Authentication has already occurred.
1426+
1427+
-or-
1428+
1429+
Client authentication using this <see cref="T:System.Net.Security.SslStream" /> was tried previously.
1430+
1431+
-or-
1432+
1433+
Authentication is already in progress.</exception>
1434+
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
13411435
</Docs>
13421436
</Member>
13431437
<MemberGroup MemberName="BeginAuthenticateAsClient">
@@ -2828,10 +2922,17 @@ Authentication has not occurred.</exception>
28282922
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="0" FrameworkAlternate="net-5.0;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netstandard-2.1" />
28292923
</Parameters>
28302924
<Docs>
2831-
<param name="cancellationToken">To be added.</param>
2832-
<summary>To be added.</summary>
2833-
<returns>To be added.</returns>
2834-
<remarks>To be added.</remarks>
2925+
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
2926+
<summary>Asynchronously writes any buffered data to the underlying device.</summary>
2927+
<returns>A task that represents the asynchronous flush operation.</returns>
2928+
<remarks>
2929+
<format type="text/markdown"><![CDATA[
2930+
2931+
## Remarks
2932+
This method invokes <xref:System.IO.Stream.FlushAsync%2A> on the underlying stream.
2933+
2934+
]]></format>
2935+
</remarks>
28352936
</Docs>
28362937
</Member>
28372938
<Member MemberName="HashAlgorithm">
@@ -3441,9 +3542,9 @@ Authentication has not occurred.</exception>
34413542
<ReturnType>System.Net.Security.SslApplicationProtocol</ReturnType>
34423543
</ReturnValue>
34433544
<Docs>
3444-
<summary>To be added.</summary>
3545+
<summary>The negotiated application protocol in TLS handshake.</summary>
34453546
<value>To be added.</value>
3446-
<remarks>To be added.</remarks>
3547+
<remarks>Available once authentication via one of of the <c>AuthenticateAs...</c> methods has been successfully processed.</remarks>
34473548
</Docs>
34483549
</Member>
34493550
<Member MemberName="NegotiatedCipherSuite">

0 commit comments

Comments
 (0)