From af47b27f0d1ae41e11965ddd7a76b67dc78091ec Mon Sep 17 00:00:00 2001
From: Ryan Nowak <nowakra@gmail.com>
Date: Thu, 4 Oct 2018 13:17:05 -0700
Subject: [PATCH] Add blurb about Host header

---
 .../LinkGenerationTemplate.cs                 | 22 ++++++++++++++++++-
 .../LinkGenerator.cs                          | 22 ++++++++++++++++++-
 ...kGeneratorEndpointNameAddressExtensions.cs | 22 ++++++++++++++++++-
 ...nkGeneratorRouteValuesAddressExtensions.cs | 22 ++++++++++++++++++-
 4 files changed, 84 insertions(+), 4 deletions(-)

diff --git a/src/Microsoft.AspNetCore.Routing.Abstractions/LinkGenerationTemplate.cs b/src/Microsoft.AspNetCore.Routing.Abstractions/LinkGenerationTemplate.cs
index 5f99df178d..b54692bd15 100644
--- a/src/Microsoft.AspNetCore.Routing.Abstractions/LinkGenerationTemplate.cs
+++ b/src/Microsoft.AspNetCore.Routing.Abstractions/LinkGenerationTemplate.cs
@@ -63,6 +63,7 @@ namespace Microsoft.AspNetCore.Routing
         /// </param>
         /// <param name="host">
         /// The URI host/authority, applied to the resulting URI. Optional. If not provided, the value <see cref="HttpRequest.Host"/> will be used.
+        /// See the remarks section for details about the security implications of the <paramref name="host"/>.
         /// </param>
         /// <param name="pathBase">
         /// An optional URI path base. Prepended to the path in the resulting URI. If not provided, the value of <see cref="HttpRequest.PathBase"/> will be used.
@@ -73,6 +74,14 @@ namespace Microsoft.AspNetCore.Routing
         /// names from <c>RouteOptions</c>.
         /// </param>
         /// <returns>A URI with an absolute path, or <c>null</c>.</returns>
+        /// <remarks>
+        /// <para>
+        /// The value of <paramref name="host" /> should be a trusted value. Relying on the value of the current request
+        /// can allow untrusted input to influence the resulting URI unless the <c>Host</c> header has been validated.
+        /// See the deployment documentation for instructions on how to properly validate the <c>Host</c> header in
+        /// your deployment environment.
+        /// </para>
+        /// </remarks>
         public abstract string GetUri(
             HttpContext httpContext,
             object values,
@@ -87,7 +96,10 @@ namespace Microsoft.AspNetCore.Routing
         /// </summary>
         /// <param name="values">The route values. Used to expand parameters in the route template. Optional.</param>
         /// <param name="scheme">The URI scheme, applied to the resulting URI.</param>
-        /// <param name="host">The URI host/authority, applied to the resulting URI.</param>
+        /// <param name="host">
+        /// The URI host/authority, applied to the resulting URI.
+        /// See the remarks section for details about the security implications of the <paramref name="host"/>.
+        /// </param>
         /// <param name="pathBase">An optional URI path base. Prepended to the path in the resulting URI.</param>
         /// <param name="fragment">An optional URI fragment. Appended to the resulting URI.</param>
         /// <param name="options">
@@ -95,6 +107,14 @@ namespace Microsoft.AspNetCore.Routing
         /// names from <c>RouteOptions</c>.
         /// </param>
         /// <returns>An absolute URI, or <c>null</c>.</returns>
+        /// <remarks>
+        /// <para>
+        /// The value of <paramref name="host" /> should be a trusted value. Relying on the value of the current request
+        /// can allow untrusted input to influence the resulting URI unless the <c>Host</c> header has been validated.
+        /// See the deployment documentation for instructions on how to properly validate the <c>Host</c> header in
+        /// your deployment environment.
+        /// </para>
+        /// </remarks>
         public abstract string GetUri(
             object values,
             string scheme,
diff --git a/src/Microsoft.AspNetCore.Routing.Abstractions/LinkGenerator.cs b/src/Microsoft.AspNetCore.Routing.Abstractions/LinkGenerator.cs
index 9f6bb0640f..1f91a4446d 100644
--- a/src/Microsoft.AspNetCore.Routing.Abstractions/LinkGenerator.cs
+++ b/src/Microsoft.AspNetCore.Routing.Abstractions/LinkGenerator.cs
@@ -83,6 +83,7 @@ namespace Microsoft.AspNetCore.Routing
         /// </param>
         /// <param name="host">
         /// The URI host/authority, applied to the resulting URI. Optional. If not provided, the value <see cref="HttpRequest.Host"/> will be used.
+        /// See the remarks section for details about the security implications of the <paramref name="host"/>.
         /// </param>
         /// <param name="pathBase">
         /// An optional URI path base. Prepended to the path in the resulting URI. If not provided, the value of <see cref="HttpRequest.PathBase"/> will be used.
@@ -93,6 +94,14 @@ namespace Microsoft.AspNetCore.Routing
         /// names from <c>RouteOptions</c>.
         /// </param>
         /// <returns>A URI with an absolute path, or <c>null</c>.</returns>
+        /// <remarks>
+        /// <para>
+        /// The value of <paramref name="host" /> should be a trusted value. Relying on the value of the current request
+        /// can allow untrusted input to influence the resulting URI unless the <c>Host</c> header has been validated.
+        /// See the deployment documentation for instructions on how to properly validate the <c>Host</c> header in
+        /// your deployment environment.
+        /// </para>
+        /// </remarks>
         public abstract string GetUriByAddress<TAddress>(
             HttpContext httpContext,
             TAddress address,
@@ -111,7 +120,10 @@ namespace Microsoft.AspNetCore.Routing
         /// <param name="address">The address value. Used to resolve endpoints.</param>
         /// <param name="values">The route values. Used to expand parameters in the route template. Optional.</param>
         /// <param name="scheme">The URI scheme, applied to the resulting URI.</param>
-        /// <param name="host">The URI host/authority, applied to the resulting URI.</param>
+        /// <param name="host">
+        /// The URI host/authority, applied to the resulting URI.
+        /// See the remarks section for details about the security implications of the <paramref name="host"/>.
+        /// </param>
         /// <param name="pathBase">An optional URI path base. Prepended to the path in the resulting URI.</param>
         /// <param name="fragment">An optional URI fragment. Appended to the resulting URI.</param>
         /// <param name="options">
@@ -119,6 +131,14 @@ namespace Microsoft.AspNetCore.Routing
         /// names from <c>RouteOptions</c>.
         /// </param>
         /// <returns>An absolute URI, or <c>null</c>.</returns>
+        /// <remarks>
+        /// <para>
+        /// The value of <paramref name="host" /> should be a trusted value. Relying on the value of the current request
+        /// can allow untrusted input to influence the resulting URI unless the <c>Host</c> header has been validated.
+        /// See the deployment documentation for instructions on how to properly validate the <c>Host</c> header in
+        /// your deployment environment.
+        /// </para>
+        /// </remarks>
         public abstract string GetUriByAddress<TAddress>(
             TAddress address,
             RouteValueDictionary values,
diff --git a/src/Microsoft.AspNetCore.Routing/LinkGeneratorEndpointNameAddressExtensions.cs b/src/Microsoft.AspNetCore.Routing/LinkGeneratorEndpointNameAddressExtensions.cs
index a5904d1071..d3e50328cf 100644
--- a/src/Microsoft.AspNetCore.Routing/LinkGeneratorEndpointNameAddressExtensions.cs
+++ b/src/Microsoft.AspNetCore.Routing/LinkGeneratorEndpointNameAddressExtensions.cs
@@ -112,6 +112,7 @@ namespace Microsoft.AspNetCore.Routing
         /// </param>
         /// <param name="host">
         /// The URI host/authority, applied to the resulting URI. Optional. If not provided, the value <see cref="HttpRequest.Host"/> will be used.
+        /// See the remarks section for details about the security implications of the <paramref name="host"/>.
         /// </param>
         /// <param name="pathBase">
         /// An optional URI path base. Prepended to the path in the resulting URI. If not provided, the value of <see cref="HttpRequest.PathBase"/> will be used.
@@ -122,6 +123,14 @@ namespace Microsoft.AspNetCore.Routing
         /// names from <c>RouteOptions</c>.
         /// </param>
         /// <returns>A URI with an absolute path, or <c>null</c>.</returns>
+        /// <remarks>
+        /// <para>
+        /// The value of <paramref name="host" /> should be a trusted value. Relying on the value of the current request
+        /// can allow untrusted input to influence the resulting URI unless the <c>Host</c> header has been validated.
+        /// See the deployment documentation for instructions on how to properly validate the <c>Host</c> header in
+        /// your deployment environment.
+        /// </para>
+        /// </remarks>
         public static string GetUriByName(
             this LinkGenerator generator,
             HttpContext httpContext,
@@ -167,7 +176,10 @@ namespace Microsoft.AspNetCore.Routing
         /// <param name="endpointName">The endpoint name. Used to resolve endpoints.</param>
         /// <param name="values">The route values. Used to expand parameters in the route template. Optional.</param>
         /// <param name="scheme">The URI scheme, applied to the resulting URI.</param>
-        /// <param name="host">The URI host/authority, applied to the resulting URI.</param>
+        /// <param name="host">
+        /// The URI host/authority, applied to the resulting URI.
+        /// See the remarks section for details about the security implications of the <paramref name="host"/>.
+        /// </param>
         /// <param name="pathBase">An optional URI path base. Prepended to the path in the resulting URI.</param>
         /// <param name="fragment">An optional URI fragment. Appended to the resulting URI.</param>
         /// <param name="options">
@@ -175,6 +187,14 @@ namespace Microsoft.AspNetCore.Routing
         /// names from <c>RouteOptions</c>.
         /// </param>
         /// <returns>An absolute URI, or <c>null</c>.</returns>
+        /// <remarks>
+        /// <para>
+        /// The value of <paramref name="host" /> should be a trusted value. Relying on the value of the current request
+        /// can allow untrusted input to influence the resulting URI unless the <c>Host</c> header has been validated.
+        /// See the deployment documentation for instructions on how to properly validate the <c>Host</c> header in
+        /// your deployment environment.
+        /// </para>
+        /// </remarks>
         public static string GetUriByName(
             this LinkGenerator generator,
             string endpointName,
diff --git a/src/Microsoft.AspNetCore.Routing/LinkGeneratorRouteValuesAddressExtensions.cs b/src/Microsoft.AspNetCore.Routing/LinkGeneratorRouteValuesAddressExtensions.cs
index d025679e41..d41f43d644 100644
--- a/src/Microsoft.AspNetCore.Routing/LinkGeneratorRouteValuesAddressExtensions.cs
+++ b/src/Microsoft.AspNetCore.Routing/LinkGeneratorRouteValuesAddressExtensions.cs
@@ -104,6 +104,7 @@ namespace Microsoft.AspNetCore.Routing
         /// </param>
         /// <param name="host">
         /// The URI host/authority, applied to the resulting URI. Optional. If not provided, the value <see cref="HttpRequest.Host"/> will be used.
+        /// See the remarks section for details about the security implications of the <paramref name="host"/>.
         /// </param>
         /// <param name="pathBase">
         /// An optional URI path base. Prepended to the path in the resulting URI. If not provided, the value of <see cref="HttpRequest.PathBase"/> will be used.
@@ -114,6 +115,14 @@ namespace Microsoft.AspNetCore.Routing
         /// names from <c>RouteOptions</c>.
         /// </param>
         /// <returns>A URI with an absolute path, or <c>null</c>.</returns>
+        /// <remarks>
+        /// <para>
+        /// The value of <paramref name="host" /> should be a trusted value. Relying on the value of the current request
+        /// can allow untrusted input to influence the resulting URI unless the <c>Host</c> header has been validated.
+        /// See the deployment documentation for instructions on how to properly validate the <c>Host</c> header in
+        /// your deployment environment.
+        /// </para>
+        /// </remarks>
         public static string GetUriByRouteValues(
             this LinkGenerator generator,
             HttpContext httpContext,
@@ -155,7 +164,10 @@ namespace Microsoft.AspNetCore.Routing
         /// <param name="routeName">The route name. Used to resolve endpoints. Optional.</param>
         /// <param name="values">The route values. Used to resolve endpoints and expand parameters in the route template. Optional.</param>
         /// <param name="scheme">The URI scheme, applied to the resulting URI.</param>
-        /// <param name="host">The URI host/authority, applied to the resulting URI.</param>
+        /// <param name="host">
+        /// The URI host/authority, applied to the resulting URI.
+        /// See the remarks section for details about the security implications of the <paramref name="host"/>.
+        /// </param>
         /// <param name="pathBase">An optional URI path base. Prepended to the path in the resulting URI.</param>
         /// <param name="fragment">An optional URI fragment. Appended to the resulting URI.</param>
         /// <param name="options">
@@ -163,6 +175,14 @@ namespace Microsoft.AspNetCore.Routing
         /// names from <c>RouteOptions</c>.
         /// </param>
         /// <returns>An absolute URI, or <c>null</c>.</returns>
+        /// <remarks>
+        /// <para>
+        /// The value of <paramref name="host" /> should be a trusted value. Relying on the value of the current request
+        /// can allow untrusted input to influence the resulting URI unless the <c>Host</c> header has been validated.
+        /// See the deployment documentation for instructions on how to properly validate the <c>Host</c> header in
+        /// your deployment environment.
+        /// </para>
+        /// </remarks>
         public static string GetUriByRouteValues(
             this LinkGenerator generator,
             string routeName,