Skip to content

Commit e30f409

Browse files
Jan JahodaJan Jahodagewarren
authored
Add ssl API added between preview 7 and 8 #2 (#4869)
* Add ssl API added between preview 7 and 8 * Apply suggestions from code review Co-authored-by: Genevieve Warren <[email protected]> * Update xml/System.Net.Security/SslStream.xml * Apply @wfurt comments * Add missing remark headers * Apply suggestions from code review Co-authored-by: Genevieve Warren <[email protected]> Co-authored-by: Jan Jahoda <[email protected]> Co-authored-by: Genevieve Warren <[email protected]>
1 parent ad72063 commit e30f409

File tree

6 files changed

+92
-32
lines changed

6 files changed

+92
-32
lines changed

‎xml/System.Net.Http/WinHttpHandler.xml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -416,8 +416,9 @@ When this property is set to `true`, all HTTP redirect responses from the server
416416
<ReturnType>System.Boolean</ReturnType>
417417
</ReturnValue>
418418
<Docs>
419-
<summary>To be added.</summary>
420-
<value>To be added.</value>
419+
<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>
420+
<value>
421+
<see langword="true" /> if additional HTTP/2 connections are allowed to be created; otherwise, <see langword="false" />.</value>
421422
<remarks>To be added.</remarks>
422423
</Docs>
423424
</Member>

‎xml/System.Net.Security/ServerOptionsSelectionCallback.xml

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,19 @@
2222
<ReturnType>System.Threading.Tasks.ValueTask&lt;System.Net.Security.SslServerAuthenticationOptions&gt;</ReturnType>
2323
</ReturnValue>
2424
<Docs>
25-
<param name="stream">To be added.</param>
26-
<param name="clientHelloInfo">To be added.</param>
27-
<param name="state">To be added.</param>
28-
<param name="cancellationToken">To be added.</param>
29-
<summary>To be added.</summary>
30-
<returns>To be added.</returns>
31-
<remarks>To be added.</remarks>
25+
<param name="stream">The TLS stream on which the authentication happens.</param>
26+
<param name="clientHelloInfo">Information from the Client Hello message.</param>
27+
<param name="state">The information that was passed when registering the callback.</param>
28+
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
29+
<summary>Represents the asynchronous callback method that will select session properties based on the name requested by the client.</summary>
30+
<returns>A server authentication property bag.</returns>
31+
<remarks>
32+
<format type="text/markdown"><![CDATA[
33+
34+
## Remarks
35+
This delegate provides authentication properties during the server authenticaton as an asynchronous operation.
36+
37+
]]></format>
38+
</remarks>
3239
</Docs>
3340
</Type>

‎xml/System.Net.Security/SslClientHelloInfo.xml

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,9 +40,16 @@
4040
<ReturnType>System.String</ReturnType>
4141
</ReturnValue>
4242
<Docs>
43-
<summary>To be added.</summary>
43+
<summary>Gets the host server specified by the client.</summary>
4444
<value>To be added.</value>
45-
<remarks>To be added.</remarks>
45+
<remarks>
46+
<format type="text/markdown"><![CDATA[
47+
48+
## Remarks
49+
The host server name requires Server Name extension (SNI). If the SNI extension is not present, this property returns an empty string.
50+
51+
]]></format>
52+
</remarks>
4653
</Docs>
4754
</Member>
4855
<Member MemberName="SslProtocols">
@@ -61,8 +68,8 @@
6168
<ReturnType>System.Security.Authentication.SslProtocols</ReturnType>
6269
</ReturnValue>
6370
<Docs>
64-
<summary>To be added.</summary>
65-
<value>To be added.</value>
71+
<summary>Gets the TLS/SSL protocols offered by client.</summary>
72+
<value>A bitwise combination of the enumeration values that specify the TLS or SSL protocols.</value>
6673
<remarks>To be added.</remarks>
6774
</Docs>
6875
</Member>

‎xml/System.Net.Security/SslServerAuthenticationOptions.xml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -332,8 +332,8 @@
332332
<ReturnType>System.Net.Security.SslStreamCertificateContext</ReturnType>
333333
</ReturnValue>
334334
<Docs>
335-
<summary>To be added.</summary>
336-
<value>To be added.</value>
335+
<summary>Gets or sets the server certificate context.</summary>
336+
<value>The server certificate context.</value>
337337
<remarks>To be added.</remarks>
338338
</Docs>
339339
</Member>

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

Lines changed: 30 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1399,7 +1399,7 @@
13991399
]]></format>
14001400
</remarks>
14011401
<exception cref="T:System.ArgumentNullException">
1402-
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>
1402+
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>
14031403
<exception cref="T:System.ArgumentNullException">
14041404
<paramref name="sslServerAuthenticationOptions" /> is <see langword="null" />.</exception>
14051405
<exception cref="T:System.Security.Authentication.AuthenticationException">The authentication failed and left this object in an unusable state.</exception>
@@ -1438,12 +1438,33 @@
14381438
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="2" FrameworkAlternate="net-5.0" />
14391439
</Parameters>
14401440
<Docs>
1441-
<param name="optionsCallback">To be added.</param>
1442-
<param name="state">To be added.</param>
1443-
<param name="cancellationToken">To be added.</param>
1444-
<summary>To be added.</summary>
1445-
<returns>To be added.</returns>
1446-
<remarks>To be added.</remarks>
1441+
<param name="optionsCallback">The callback delegate.</param>
1442+
<param name="state">The state object to pass to <paramref name="optionsCallback" /> when the callback is invoked.</param>
1443+
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
1444+
<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>
1445+
<returns>The task object representing the asynchronous operation.</returns>
1446+
<remarks>
1447+
<format type="text/markdown"><![CDATA[
1448+
1449+
## Remarks
1450+
1451+
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.
1452+
1453+
]]></format>
1454+
</remarks>
1455+
<exception cref="T:System.ArgumentNullException">
1456+
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>
1457+
<exception cref="T:System.Security.Authentication.AuthenticationException">The authentication failed and left this object in an unusable state.</exception>
1458+
<exception cref="T:System.InvalidOperationException">Authentication has already occurred.
1459+
1460+
-or-
1461+
1462+
Client authentication using this <see cref="T:System.Net.Security.SslStream" /> was tried previously.
1463+
1464+
-or-
1465+
1466+
Authentication is already in progress.</exception>
1467+
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
14471468
</Docs>
14481469
</Member>
14491470
<Member MemberName="AuthenticateAsServerAsync">
@@ -4346,8 +4367,8 @@ This property gets the cipher suite that is going to be used in the communicatio
43464367
<ReturnType>System.String</ReturnType>
43474368
</ReturnValue>
43484369
<Docs>
4349-
<summary>To be added.</summary>
4350-
<value>To be added.</value>
4370+
<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>
4371+
<value>The name of the server the client is trying to connect to.</value>
43514372
<remarks>To be added.</remarks>
43524373
</Docs>
43534374
</Member>

‎xml/System.Net.Security/SslStreamCertificateContext.xml

Lines changed: 32 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,18 @@
1414
</Base>
1515
<Interfaces />
1616
<Docs>
17-
<summary>To be added.</summary>
18-
<remarks>To be added.</remarks>
17+
<summary>Represents a set of certificates used for building a certificate chain.</summary>
18+
<remarks>
19+
<format type="text/markdown"><![CDATA[
20+
21+
## Remarks
22+
23+
The certificates are normalized. If a certificate is missing in the constructed X509Chain, SslStream will try to resolve them either by searching for the certificate in the certificate stores or by fetching them over the network, if allowed.
24+
25+
The <see cref="T:System.Net.Security.SslStreamCertificateContext" /> can be used across multiple streams to save chain construction and improve performance.
26+
27+
]]></format>
28+
</remarks>
1929
</Docs>
2030
<Members>
2131
<Member MemberName="Create">
@@ -38,12 +48,26 @@
3848
<Parameter Name="offline" Type="System.Boolean" />
3949
</Parameters>
4050
<Docs>
41-
<param name="target">To be added.</param>
42-
<param name="additionalCertificates">To be added.</param>
43-
<param name="offline">To be added.</param>
44-
<summary>To be added.</summary>
45-
<returns>To be added.</returns>
46-
<remarks>To be added.</remarks>
51+
<param name="target">The server certificate.</param>
52+
<param name="additionalCertificates">Supplementary certificates used to build the certificate chain.</param>
53+
<param name="offline">
54+
<see langword="true" /> to indicate that the missing certificates can be downloaded from the network; <see langword="false" /> to indicate that only available X509Certificate stores should be searched for missing certificates.</param>
55+
<summary>Attempts to build the certificate chain from the provided certificates.</summary>
56+
<returns>The certificate context with the newly created certificate chain.</returns>
57+
<remarks>To be added.
58+
<format type="text/markdown"><![CDATA[
59+
60+
## Remarks
61+
The provided certificates should not be disposed during the lifetime of the <see cref="T:System.Net.Security.SslStreamCertificateContext" />.
62+
63+
> [!IMPORTANT]
64+
> The target certificate must include a private key.
65+
66+
]]></format>
67+
68+
</remarks>
69+
<exception cref="T:System.NotSupportedException">
70+
<paramref name="target" /> doesn't have an associated private key.</exception>
4771
</Docs>
4872
</Member>
4973
</Members>

0 commit comments

Comments
 (0)