Skip to content

Document TryAddWithoutValidation security implications and validation behavior #12226

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

Open
Copilot wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Document TryAddWithoutValidation security implications and validation behavior #12226

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
cfeb2cb
Initial plan
Copilot Jan 13, 2026
0f9a026
Add comprehensive documentation for TryAddWithoutValidation methods
Copilot Jan 13, 2026
5eaf345
Fix documentation formatting and code example issues
Copilot Jan 13, 2026
61410ff
Apply suggestions from code review
MihaZupan Jan 13, 2026
ce37714
Apply suggestions from code review
MihaZupan Jan 13, 2026
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
44 changes: 41 additions & 3 deletions xml/System.Net.Http.Headers/HttpHeaders.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -583,7 +583,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">
Expand Down Expand Up @@ -635,7 +635,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">
Expand Down Expand Up @@ -687,7 +706,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">
Expand Down