Skip to content

SslStream - update documentation #4372

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Jun 18, 2020
Merged

SslStream - update documentation #4372

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3c2bb28
SslStream - update documentation
Jun 12, 2020
4f06c1c
Add AuthenticateAsServerAsync
Jun 12, 2020
d50958e
Add NegotiatedApplicationProtocol
Jun 12, 2020
00586cb
Add FlushAsync
Jun 12, 2020
7029de2
Apply suggestions from code review
aik-jahoda Jun 15, 2020
b6351c9
Apply PR comments
Jun 15, 2020
5fec3bd
Merge branch 'jajahoda/SslStream' of github.com:aik-jahoda/dotnet-api…
Jun 15, 2020
93dd4b7
Apply suggestions from code review
aik-jahoda Jun 17, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 117 additions & 16 deletions xml/System.Net.Security/SslStream.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -792,11 +792,34 @@
<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" />
</Parameters>
<Docs>
<param name="sslClientAuthenticationOptions">To be added.</param>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="sslClientAuthenticationOptions">The property bag for the SSL connection.</param>
<param name="cancellationToken">The token to monitor for cancellation requests.</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 information specified in the <see param="System.Net.Security.SslClientAuthenticationOptions" /> property bag.</summary>
<returns>The task object representing the asynchronous operation.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

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.

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.

]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="sslClientAuthenticationOptions" /> is <see langword="null" />.</exception>
<exception cref="T:System.Security.Authentication.AuthenticationException">The authentication failed and left this object in an unusable state.</exception>
<exception cref="T:System.InvalidOperationException">Authentication has already occurred.

-or-

Server authentication using this <see cref="T:System.Net.Security.SslStream" /> was tried previously.

-or-

Authentication is already in progress.</exception>
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
</Docs>
</Member>
<Member MemberName="AuthenticateAsClientAsync">
Expand Down Expand Up @@ -851,6 +874,17 @@

]]></format>
</remarks>
<exception cref="T:System.Security.Authentication.AuthenticationException">The authentication failed and left this object in an unusable state.</exception>
<exception cref="T:System.InvalidOperationException">Authentication has already occurred.

-or-

Server authentication using this <see cref="T:System.Net.Security.SslStream" /> was tried previously.

-or-

Authentication is already in progress.</exception>
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
</Docs>
</Member>
<Member MemberName="AuthenticateAsClientAsync">
Expand Down Expand Up @@ -910,6 +944,17 @@

]]></format>
</remarks>
<exception cref="T:System.Security.Authentication.AuthenticationException">The authentication failed and left this object in an unusable state.</exception>
<exception cref="T:System.InvalidOperationException">Authentication has already occurred.

-or-

Server authentication using this <see cref="T:System.Net.Security.SslStream" /> was tried previously.

-or-

Authentication is already in progress.</exception>
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
</Docs>
</Member>
<MemberGroup MemberName="AuthenticateAsServer">
Expand Down Expand Up @@ -1230,11 +1275,34 @@
<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" />
</Parameters>
<Docs>
<param name="sslServerAuthenticationOptions">To be added.</param>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="sslServerAuthenticationOptions">The property bag for the SSL connection.</param>
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
<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>
<returns>The task object representing the asynchronous operation.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

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.

]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">
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>
<exception cref="T:System.ArgumentNullException">
<paramref name="sslServerAuthenticationOptions" /> is <see langword="null" />.</exception>
<exception cref="T:System.Security.Authentication.AuthenticationException">The authentication failed and left this object in an unusable state.</exception>
<exception cref="T:System.InvalidOperationException">Authentication has already occurred.

-or-

Client authentication using this <see cref="T:System.Net.Security.SslStream" /> was tried previously.

-or-

Authentication is already in progress.</exception>
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
</Docs>
</Member>
<Member MemberName="AuthenticateAsServerAsync">
Expand Down Expand Up @@ -1284,6 +1352,19 @@

]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="serverCertificate" /> is <see langword="null" />.</exception>
<exception cref="T:System.Security.Authentication.AuthenticationException">The authentication failed and left this object in an unusable state.</exception>
<exception cref="T:System.InvalidOperationException">Authentication has already occurred.

-or-

Client authentication using this <see cref="T:System.Net.Security.SslStream" /> was tried previously.

-or-

Authentication is already in progress.</exception>
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
</Docs>
</Member>
<Member MemberName="AuthenticateAsServerAsync">
Expand Down Expand Up @@ -1338,6 +1419,19 @@

]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="serverCertificate" /> is <see langword="null" />.</exception>
<exception cref="T:System.Security.Authentication.AuthenticationException">The authentication failed and left this object in an unusable state.</exception>
<exception cref="T:System.InvalidOperationException">Authentication has already occurred.

-or-

Client authentication using this <see cref="T:System.Net.Security.SslStream" /> was tried previously.

-or-

Authentication is already in progress.</exception>
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
</Docs>
</Member>
<MemberGroup MemberName="BeginAuthenticateAsClient">
Expand Down Expand Up @@ -2828,10 +2922,17 @@ Authentication has not occurred.</exception>
<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" />
</Parameters>
<Docs>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
<summary>Asynchronously writes any buffered data to the underlying device.</summary>
<returns>A task that represents the asynchronous flush operation.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This method invokes <xref:System.IO.Stream.FlushAsync%2A> on the underlying stream.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="HashAlgorithm">
Expand Down Expand Up @@ -3441,9 +3542,9 @@ Authentication has not occurred.</exception>
<ReturnType>System.Net.Security.SslApplicationProtocol</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>The negotiated application protocol in TLS handshake.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<remarks>Available once authentication via one of of the <c>AuthenticateAs...</c> methods has been successfully processed.</remarks>
</Docs>
</Member>
<Member MemberName="NegotiatedCipherSuite">
Expand Down