Merge pull request #12326 from dotnet/main

Merge main into live

Author: dotnet-policy-service[bot]

xml/System.Net.Http.Headers/HttpHeaders.xml

@@ -596,7 +596,7 @@ This member is an explicit interface member implementation. It can be used only
         <AssemblyVersion>4.2.0.0</AssemblyVersion>
       </AssemblyInfo>
       <Docs>
-        <summary>Returns a value that indicates whether a new header and its values were added to  the <see cref="T:System.Net.Http.Headers.HttpHeaders" /> collection without validating the provided information.</summary>
+        <summary>Returns a value that indicates whether a new header and its values were added to the <see cref="T:System.Net.Http.Headers.HttpHeaders" /> collection without validating the header values.</summary>
       </Docs>
     </MemberGroup>
     <Member MemberName="TryAddWithoutValidation">
@@ -649,7 +649,26 @@ This member is an explicit interface member implementation. It can be used only
         <summary>Returns a value that indicates whether the specified header and its values were added to the <see cref="T:System.Net.Http.Headers.HttpHeaders" /> collection without validating the provided information.</summary>
         <returns>
           <see langword="true" /> if the specified header <paramref name="name" /> and <paramref name="values" /> could be added to the collection; otherwise <see langword="false" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This method performs header name validation, returning `false` for invalid names. Header names are enforced to be valid HTTP tokens, where a token is defined as any set of ASCII letters, digits, or symbols from the ``"!#$%&'*+-.^_`|~"`` set, matching [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-collected-abnf)'s definition. Non-ASCII characters aren't allowed in a header name.
+
+This method doesn't perform any header value validation. Values added via this method are assumed to be trusted, and other application logic, such as <xref:System.Net.Http.HttpClient>, might misbehave if they're not well formed.
+
+Values added without validation might be observed when enumerating the collection or querying for the specific header name, even when the caller isn't using the <xref:System.Net.Http.Headers.HttpHeaders.NonValidated> view of the collection.
+
+> [!CAUTION]
+> This method must never be used with untrusted values, unless they were otherwise sufficiently validated.
+> 
+> What constitutes "sufficient" validation can vary by use case. At a minimum, prohibit newline characters for protocol correctness, for example, `if (value.ContainsAny('\r', '\n', '\0')) throw ...`. This validation should ensure that the server application sees values in the same way as the client application, with the server now being responsible for properly sanitizing its own inputs.
+> 
+> To guard against attacks such as request smuggling, callers are highly encouraged to validate that these values don't contain newline characters.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="TryAddWithoutValidation">
@@ -702,7 +721,26 @@ This member is an explicit interface member implementation. It can be used only
         <summary>Returns a value that indicates whether the specified header and its value were added to the <see cref="T:System.Net.Http.Headers.HttpHeaders" /> collection without validating the provided information.</summary>
         <returns>
           <see langword="true" /> if the specified header <paramref name="name" /> and <paramref name="value" /> could be added to the collection; otherwise <see langword="false" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This method performs header name validation, returning `false` for invalid names. Header names are enforced to be valid HTTP tokens, where a token is defined as any set of ASCII letters, digits, or symbols from the ``"!#$%&'*+-.^_`|~"`` set, matching [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-collected-abnf)'s definition. Non-ASCII characters aren't allowed in a header name.
+
+This method doesn't perform any header value validation. Values added via this method are assumed to be trusted, and other application logic, such as <xref:System.Net.Http.HttpClient>, might misbehave if they're not well formed.
+
+Values added without validation might be observed when enumerating the collection or querying for the specific header name, even when the caller isn't using the <xref:System.Net.Http.Headers.HttpHeaders.NonValidated> view of the collection.
+
+> [!CAUTION]
+> This method must never be used with untrusted values, unless they were otherwise sufficiently validated.
+> 
+> What constitutes "sufficient" validation can vary by use case. At a minimum, prohibit newline characters for protocol correctness, for example, `if (value.ContainsAny('\r', '\n', '\0')) throw ...`. This validation should ensure that the server application sees values in the same way as the client application, with the server now being responsible for properly sanitizing its own inputs.
+> 
+> To guard against attacks such as request smuggling, callers are highly encouraged to validate that these values don't contain newline characters.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="TryGetValues">

xml/System.Net.Mail/MailAddress.xml

@@ -265,6 +265,8 @@ If `displayName` contains non-ASCII characters, the iso-8859-1 character set is
 
 If `address` contains a display name, and `displayName` is not `null` and is not equal to <xref:System.String.Empty?displayProperty=nameWithType>, `displayName` overrides the value specified in `address`.
 
+The <xref:System.Net.Mail.MailAddress.%23ctor(System.String,System.String)> constructor does not check if the `displayName` parameter is valid. This method removes surrounding quotes not displayed by the <xref:System.Net.Mail.MailAddress.DisplayName> property. Quotes will be added before transmission. <xref:System.Text.Encoding.UTF8> encoding will be applied to the <xref:System.Net.Mail.MailAddress.DisplayName> property before transmission.
+
 ## Examples
 
 The following code example uses this constructor to create <xref:System.Net.Mail.MailAddress> instances for the sender and recipient of an email message.

xml/System/TimeZoneInfo.xml

@@ -1892,7 +1892,12 @@
 
 The `id` parameter must correspond exactly to the time zone's identifier in length, but not in case, for a successful match to occur; that is, the comparison of `id` with time zone identifiers is case-insensitive. If you want to retrieve time zone objects based on partial matches, you can write custom procedures that work with the read-only collection of <xref:System.TimeZoneInfo> objects returned by the <xref:System.TimeZoneInfo.GetSystemTimeZones%2A> method.
 
-On Windows systems, `FindSystemTimeZoneById` tries to match `id` to the subkey names of the HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Time Zones branch of the registry. On Linux and macOS, it uses time zone information available in the [ICU Library](https://unicode-org.github.io/icu/userguide/datetime/timezone/). If the registry or the library does not have the information for the time zone you desire, you can create a particular time zone either by calling one of the overloads of the <xref:System.TimeZoneInfo.CreateCustomTimeZone%2A> method or by calling <xref:System.TimeZoneInfo.FromSerializedString%2A> to deserialize a <xref:System.TimeZoneInfo> object that represents the required time zone. However, time zones created by these method calls are not system-defined time and cannot be retrieved using the <xref:System.TimeZoneInfo.FindSystemTimeZoneById%2A> method. These custom time zones can be accessed only through the object reference returned by the <xref:System.TimeZoneInfo.CreateCustomTimeZone%2A> or <xref:System.TimeZoneInfo.FromSerializedString%2A> method call.
+On Windows systems, `FindSystemTimeZoneById` tries to match `id` to the subkey names of the HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Time Zones branch of the registry.
+Starting with .NET 6, Windows systems also support IANA time zone identifiers (such as "America/Los_Angeles" or "Pacific/Auckland"), providing cross-platform time zone resolution. IANA IDs are supported on Windows only if NLS isn't enabled and globalization invariant mode isn't enabled.
+On Linux and macOS, it uses time zone information available in the [ICU Library](https://unicode-org.github.io/icu/userguide/datetime/timezone/).
+If the registry or the library does not have the information for the time zone you desire, you can create a particular time zone either by calling one of the overloads of the <xref:System.TimeZoneInfo.CreateCustomTimeZone%2A> method or by calling <xref:System.TimeZoneInfo.FromSerializedString%2A> to deserialize a <xref:System.TimeZoneInfo> object that represents the required time zone.
+However, time zones created by these method calls are not system-defined time and cannot be retrieved using the <xref:System.TimeZoneInfo.FindSystemTimeZoneById%2A> method.
+These custom time zones can be accessed only through the object reference returned by the <xref:System.TimeZoneInfo.CreateCustomTimeZone%2A> or <xref:System.TimeZoneInfo.FromSerializedString%2A> method call.
 
 In .NET 7 and earlier versions, this method returns a new <xref:System.TimeZoneInfo> instance for each method call. This might impact performance in applications that call the `FindSystemTimeZoneById` method repeatedly with the same identifier. (In .NET 8 and later versions, this method always returns a cached <xref:System.TimeZoneInfo> instance.)