This site is the archived OWASP Foundation Wiki and is no longer accepting Account Requests.
To view the new OWASP Foundation website, please visit https://owasp.org

Difference between revisions of "ASP.NET Output Encoding"

From OWASP
Jump to: navigation, search
(Creating this page for Brice.)
 
(Initial page content)
Line 2: Line 2:
  
 
==Description==
 
==Description==
 +
Cross-site scripting attacks exploit vulnerabilities in web page validation by injecting client-side script code. The script code embeds itself in response data, which is sent back to an unsuspecting user. In addition to validating input, any data retrieved from untrusted or shared sources should be encoded on output. For example: data retrieved from a database that may have had malicious input persisted to it.
  
 +
==Validating Input==
 +
See the [[ASP.NET Request Validation]] article for details on how request validation can be used to protect against malicious input.
  
==Risk Factors==
+
==Encoding Output Values in Code==
 +
Use <code>Server.HtmlEncode</code> to encode untrusted data for use in HTML output:
 +
<pre>var encodedHtml = Server.HtmlEncode(untrustedData);</pre>
  
 +
Use <code>Server.UrlEncode</code> to encode untrusted data for use in constructing URLs
 +
<pre>var encodedUrl = Server.UrlEncode(untrustedData);</pre>
  
==Related [[Attacks]]==
+
Use <code>Server.UrlTokenEncode</code> to encode untrusted data in byte array form for use as a URL parameter
 +
<pre>var encodedUrlToken = Server.UrlTokenEncode(untrustedData);</pre>
  
 +
==Encoding Output Values in HTML markup==
 +
You can HTML encode the value in markup with the <code><%: %></code> syntax, as shown below.
 +
<pre><span><%: untrustedData%></span></pre>
  
==Related [[Vulnerabilities]]==
+
Or, in Razor syntax, you can HTML encode with <code>@</code>, as shown below.
 +
<pre><span>@untrustedData</span></pre>
  
 +
==Preventing Double Encoding==
 +
You may run into a scenario where encoding values results in them becoming double encoded on output. ASP.NET provides the <code>HtmlString</code> and <code>MvcHtmlString</code> classes starting with .NET 4.0 which are designed to help. These both implement the <code>IHtmlString</code> interface which will instruct ASP.NET to not apply encoding within HTML markup when using <code><%: userInput %></code> or <code>@userInput</code>. Converting a property on your view model from <code>String</code> to <code>MvcHtmlString</code> will instruct ASP.NET that HTML encoding has already been accounted for.
  
==Related [[Controls]]==
+
<pre>public class User
 +
{
 +
    public int Id { get; set; }
 +
    public string Name { get; set; }
 +
    public MvcHtmlString Description { get; set; } // Output encoding is handled manually
 +
}</pre>
  
 +
==Enhanced Encoding==
 +
By default the ASP.NET encoding methods use a black-listing technique that evaluates the string for a set of character combinations that may indicate presence of malicious script. A superior approach is to use a [[Input Validation Cheat Sheet#White_List_Input_Validation|white-listing technique]] for validation, which can be achieved using the Anti-Cross Site Scripting Library from Microsoft. Starting with ASP.NET 4.5 you can specify that the <code>AntiXssEncoder</code> from this library be used as the default encoder for you entire application using the <code>encoderType</code> setting in web.config as shown below.
 +
<pre><httpRuntime encoderType="System.Web.Security.AntiXss.AntiXssEncoder" /></pre>
  
==Related [[Technical Impacts]]==
+
If you are using a version of .NET earlier than 4.5, you will need to download and include the library as a reference to your project, and then use the earlier library name for the encodeType setting as shown below.
 +
<pre><httpRuntime encoderType="Microsoft.Security.Application.AntiXssEncoder, AntiXssLibrary" /></pre>
  
 +
In addition to the common <code>HtmlEncode</code> and <code>UrlEncode</code> methods, the Anti-Cross Site Scripting Library provides the following <code>AntiXssEncoder</code> methods for more specialized output encoding needs:
 +
 +
{| class="wikitable"
 +
|CssEncode
 +
|Encodes the specified string for use in cascading style sheets (CSS).
 +
|-
 +
|HeaderNameValueEncode
 +
|Encodes a header name and value into a string that can be used as an HTTP header.
 +
|-
 +
|HtmlAttributeEncode
 +
|Encodes and outputs the specified string for use in an HTML attribute.
 +
|-
 +
|HtmlFormUrlEncode
 +
|Encodes the specified string for use in form submissions whose MIME type is "application/x-www-form-urlencoded".
 +
|-
 +
|JavaScriptStringEncode
 +
|Encodes a string for use in JavaScript.
 +
|-
 +
|UrlPathEncode
 +
|Encodes path strings for use in a URL.
 +
|-
 +
|XmlAttributeEncode
 +
|Encodes the specified string for use in XML attributes.
 +
|-
 +
|XmlEncode
 +
|Encodes the specified string for use in XML.
 +
|}
  
 
==References==
 
==References==
 
+
*[http://blogs.msdn.com/b/cisg/archive/2008/08/28/output-encoding.aspx Output Encoding]
 +
*[http://weblogs.asp.net/scottgu/new-lt-gt-syntax-for-html-encoding-output-in-asp-net-4-and-asp-net-mvc-2 New <%: %> Syntax for HTML Encoding Output in ASP.NET 4 (and ASP.NET MVC 2)]
 +
*[http://msdn.microsoft.com/en-us/library/system.web.ihtmlstring(v=vs.110).aspx IHtmlString Interface]
 +
*[http://stackoverflow.com/questions/2293357/what-is-an-mvchtmlstring-and-when-should-i-use-it What is an MvcHtmlString and when should I use it?]
 +
*[http://www.microsoft.com/en-sg/download/details.aspx?id=43126 Microsoft Anti-Cross Site Scripting Library V4.3]
 +
*[http://msdn.microsoft.com/en-us/library/system.web.security.antixss.antixssencoder_methods(v=vs.110).aspx AntiXssEncoder Methods]
  
 
[[Category:OWASP .NET Project]][[Category:Stub]]
 
[[Category:OWASP .NET Project]][[Category:Stub]]

Revision as of 19:19, 30 October 2014

DRAFT DOCUMENT - WORK IN PROGRESS

Description

Cross-site scripting attacks exploit vulnerabilities in web page validation by injecting client-side script code. The script code embeds itself in response data, which is sent back to an unsuspecting user. In addition to validating input, any data retrieved from untrusted or shared sources should be encoded on output. For example: data retrieved from a database that may have had malicious input persisted to it.

Validating Input

See the ASP.NET Request Validation article for details on how request validation can be used to protect against malicious input.

Encoding Output Values in Code

Use Server.HtmlEncode to encode untrusted data for use in HTML output:

var encodedHtml = Server.HtmlEncode(untrustedData);

Use Server.UrlEncode to encode untrusted data for use in constructing URLs

var encodedUrl = Server.UrlEncode(untrustedData);

Use Server.UrlTokenEncode to encode untrusted data in byte array form for use as a URL parameter

var encodedUrlToken = Server.UrlTokenEncode(untrustedData);

Encoding Output Values in HTML markup

You can HTML encode the value in markup with the <%: %> syntax, as shown below.

<span><%: untrustedData%></span>

Or, in Razor syntax, you can HTML encode with @, as shown below.

<span>@untrustedData</span>

Preventing Double Encoding

You may run into a scenario where encoding values results in them becoming double encoded on output. ASP.NET provides the HtmlString and MvcHtmlString classes starting with .NET 4.0 which are designed to help. These both implement the IHtmlString interface which will instruct ASP.NET to not apply encoding within HTML markup when using <%: userInput %> or @userInput. Converting a property on your view model from String to MvcHtmlString will instruct ASP.NET that HTML encoding has already been accounted for.

public class User 
{
    public int Id { get; set; }
    public string Name { get; set; }
    public MvcHtmlString Description { get; set; } // Output encoding is handled manually
}

Enhanced Encoding

By default the ASP.NET encoding methods use a black-listing technique that evaluates the string for a set of character combinations that may indicate presence of malicious script. A superior approach is to use a white-listing technique for validation, which can be achieved using the Anti-Cross Site Scripting Library from Microsoft. Starting with ASP.NET 4.5 you can specify that the AntiXssEncoder from this library be used as the default encoder for you entire application using the encoderType setting in web.config as shown below.

<httpRuntime encoderType="System.Web.Security.AntiXss.AntiXssEncoder" />

If you are using a version of .NET earlier than 4.5, you will need to download and include the library as a reference to your project, and then use the earlier library name for the encodeType setting as shown below.

<httpRuntime encoderType="Microsoft.Security.Application.AntiXssEncoder, AntiXssLibrary" />

In addition to the common HtmlEncode and UrlEncode methods, the Anti-Cross Site Scripting Library provides the following AntiXssEncoder methods for more specialized output encoding needs:

CssEncode Encodes the specified string for use in cascading style sheets (CSS).
HeaderNameValueEncode Encodes a header name and value into a string that can be used as an HTTP header.
HtmlAttributeEncode Encodes and outputs the specified string for use in an HTML attribute.
HtmlFormUrlEncode Encodes the specified string for use in form submissions whose MIME type is "application/x-www-form-urlencoded".
JavaScriptStringEncode Encodes a string for use in JavaScript.
UrlPathEncode Encodes path strings for use in a URL.
XmlAttributeEncode Encodes the specified string for use in XML attributes.
XmlEncode Encodes the specified string for use in XML.

References