8000 Add ssl API added between preview 7 and 8 by aik-jahoda · Pull Request #4860 · dotnet/dotnet-api-docs · GitHub
[go: up one dir, main page]
Skip to content

Add ssl API added between preview 7 and 8 #4860

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 3 commits into from
Sep 16, 2020
Merged

Add ssl API added between preview 7 and 8 #4860

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d8d1289
Add ssl API added between preview 7 and 8
Sep 16, 2020
ba345f8
Apply suggestions from code review
aik-jahoda Sep 16, 2020
4fb4f93
Update xml/System.Net.Security/SslStream.xml
gewarren Sep 16, 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
5 changes: 3 additions & 2 deletions xml/System.Net.Http/WinHttpHandler.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -416,8 +416,9 @@ When this property is set to `true`, all HTTP redirect responses from the server
<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 additional HTTP/2 connections can be established to the same server when the maximum number of concurrent streams is reached on all existing connections.</summary>
<value>
<see langword="true" /> if additional HTTP/2 connections are allowed to be created; otherwise, <see langword="false" />.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
20 changes: 13 additions & 7 deletions xml/System.Net.Security/ServerOptionsSelectionCallback.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,18 @@
<ReturnType>System.Threading.Tasks.ValueTask&lt;System.Net.Security.SslServerAuthenticationOptions&gt;</ReturnType>
</ReturnValue>
<Docs>
<param name="stream">To be added.</param>
<param name="clientHelloInfo">To be added.</param>
<param name="state">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="stream">The TLS stream on which the authentication happens.</param>
<param name="clientHelloInfo">Information from the Client Hello message.</param>
<param name="state">The information that was passed when registering the callback.</param>
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
<summary>The asynchronous callback to select session properties based on name requested by client.</summary>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<summary>The asynchronous callback to select session properties based on name requested by client.</summary>
<summary>Represents the asynchronous callback method that will select session properties based on name requested by client.</summary>
Suggested change
<summary>The asynchronous callback to select session properties based on name requested by client.</summary>
<summary>The asynchronous callback to select session properties based on the name requested by the client.</summary>

<returns>A server authentication property bag.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

This delegate provides authentication properties during the server authenticaton as an asynchronous operation.

]]></format>
</remarks>
</Docs>
</Type>
6 changes: 3 additions & 3 deletions xml/System.Net.Security/SslClientHelloInfo.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>The host server specified by the client.</summary>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would change that to "The host server specified by the client in Server Name extension (SNI). If the extension is not present this returns empty string.

<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand All @@ -61,8 +61,8 @@
<ReturnType>System.Security.Authentication.SslProtocols</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets or sets the TLS/SSL protocols offered by client.</summary>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There really should not be setter. Both properties are readonly.

<value>A bitwise combination of the enumeration values that specify the TLS or SSL protocols.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
4 changes: 2 additions & 2 deletions xml/System.Net.Security/SslServerAuthenticationOptions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -332,8 +332,8 @@
<ReturnType>System.Net.Security.SslStreamCertificateContext</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets or sets the server certificate context.</summary>
<value>The server certificate context.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
39 changes: 30 additions & 9 deletions xml/System.Net.Security/SslS 8000 tream.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1399,7 +1399,7 @@
]]></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 langword="SslStream" /> constructor.</exception>
Either <see cref="P:System.Net.Security.SslServerAuthenticationOptions.ServerCertificateSelectionCallback" /> or <see cref="P:System.Net.Security.SslServerAuthenticationOptions.ServerCertificate" /> or <see cref="P:System.Net.Security.SslServerAuthenticationOptions.ServerCertificateContext" /> is <see langword="null" /> and <see cref="T:System.Net.Security.LocalCertificateSelectionCallback" /> is not set in the <see langword="SslStream" /> 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>
Expand Down Expand Up @@ -1438,12 +1438,33 @@
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="2" FrameworkAlternate="net-5.0" />
</Parameters>
<Docs>
<param name="optionsCallback">To be added.</param>
<param name="state">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="optionsCallback">The callback delegate.</param>
<param name="state">The state object to pass to <paramref name="optionsCallback" /> when the callback is invoked.</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 returned by <paramref name="optionsCallback" />.</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 6D40 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" /> or <see cref="P:System.Net.Security.SslServerAuthenticationOptions.ServerCertificateContext" /> is <see langword="null" /> and <see cref="T:System.Net.Security.LocalCertificateSelectionCallback" /> is not set in the <see langword="SslStream" /> constructor.</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 @@ -4346,8 +4367,8 @@ This property gets the cipher suite that is going to be used in the communicatio
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets 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>The name of the server the client is trying to connect to.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
15 changes: 9 additions & 6 deletions xml/System.Net.Security/SslStreamCertificateContext.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
</Base>
<Interfaces />
<Docs>
<summary>To be added.</summary>
<summary>Represents a set of certificates used for building a certificate chain.</summary>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add note that the certificates are normalized and if something is missing in constructed X509Chain, SslStream will try to resolve them - either by searching certificates stores or by fetching them via network if allowed.

<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -38,12 +38,15 @@
<Parameter Name="offline" Type="System.Boolean" />
</Parameters>
<Docs>
<param name="target">To be added.</param>
<param name="additionalCertificates">To be added.</param>
<param name="offline">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="target">The server certificate.</param>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add bold comment that the certificate must include private key.

<param name="additionalCertificates">The certificates to chain.</param>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would change this to something like "Supplemental certificates to build the certificate chain."
It is not quarantined that all the certificates will be used and sent out.

<param name="offline">
<see langword="true" /> to indicate that the missing certificates can be downloaded; otherwise, <see langword="false" />.</param>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

otherwise only available X509Certificate stores will be searched for missing certificates.

<summary>Attempts to build the certificate chain from the provided certificates.</summary>
<returns>The certificate context with the newly created certificate chain.</returns>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add note that it can be used across many streams to save chain construction and improve performance.
Provided certificates should not be disposed. CertificateContext does not copy them but uses references.

<remarks>To be added.</remarks>
<exception cref="T:System.NotSupportedException">
<paramref name="target" /> doesn't have an associated private key.</exception>
</Docs>
</Member>
</Members>
Expand Down
0