New ToString() options.

benmccallum · benmccallum · commit a862405f7ac8 · 2018-10-02T11:35:43.000+02:00
* Splitting the new HTML escaping functionality into ToHtmlEscapedString().
* A new ToString() overload that accepts a JsonSerializerSettings instance.
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-﻿![Schema.NET Banner](https://raw.githubusercontent.com/RehanSaeed/Schema.NET/master/Images/Banner.png)
+![Schema.NET Banner](https://raw.githubusercontent.com/RehanSaeed/Schema.NET/master/Images/Banner.png)
 
 Schema.org objects turned into strongly typed C# POCO classes for use in .NET. All classes can be serialized into JSON/JSON-LD and XML, typically used to represent structured data in the `head` section of `html` page.
 
@@ -16,7 +16,7 @@ var jsonLd = website.ToString();
 
 The code above outputs the following JSON-LD:
 
-```JSONLD
+```JSON
 {
     "@context":"http://schema.org",
     "@type":"WebSite",
@@ -26,6 +26,8 @@ The code above outputs the following JSON-LD:
 }
 ```
 
+If writing the result into a `<script>` element, be sure to use the `.ToHtmlEscapedString()` method instead to avoid exposing your website to a Cross-Site Scripting attack. See the [example below](#important-security-notice).
+
 ## What is Schema.org?
 
 [schema.org](https://schema.org) defines a set of standard classes and their properties for objects and services in the real world. This machine readable format is a common standard used across the web for describing things.
@@ -56,6 +58,17 @@ Using structured data in `html` requires the use of a `script` tag with a MIME t
 </script>
 ```
 
+##### Important Security Notice
+When serializing the result for a website's `<script>` tag, you should use the alternate `.ToHtmlEscapedString()` to avoid exposing yourself to a Cross-Site Scripting (XSS) vulnerability if some of the properties in your schema have been set from untrusted sources.
+Usage in an ASP.NET MVC project might look like this:
+
+```HTML
+<script type="application/ld+json">
+    @Html.Raw(Model.Schema.ToHtmlEscapedString())
+</script>
+```
+ 
+
 #### Windows UWP Sharing
 
 Windows UWP apps let you share data using schema.org classes. [Here](https://docs.microsoft.com/en-us/uwp/schemas/appxpackage/appxmanifestschema/element-sharetarget) is an example showing how to share metadata about a book.
diff --git a/Source/Schema.NET/Thing.Partial.cs b/Source/Schema.NET/Thing.Partial.cs
@@ -10,10 +10,22 @@ public partial class Thing : JsonLdObject
         private const string ContextPropertyJson = "\"@context\":\"http://schema.org\",";
 
         /// <summary>
-        /// Serializer settings used.
-        /// Note: Escapes HTML to avoid XSS vulnerabilities where user-supplied data is used.
+        /// Default serializer settings used.
         /// </summary>
         private static readonly JsonSerializerSettings SerializerSettings = new JsonSerializerSettings()
+        {
+            Converters = new List<JsonConverter>()
+            {
+                new StringEnumConverter()
+            },
+            NullValueHandling = NullValueHandling.Ignore
+        };
+
+        /// <summary>
+        /// Serializer settings used when trying to avoid XSS vulnerabilities where user-supplied data is used
+        /// and the output of the serialization is embedded into a web page raw.
+        /// </summary>
+        private static readonly JsonSerializerSettings HtmlEscapedSerializerSettings = new JsonSerializerSettings()
         {
             Converters = new List<JsonConverter>()
             {
@@ -29,8 +41,34 @@ public partial class Thing : JsonLdObject
         /// <returns>
         /// A <see cref="string" /> that represents the JSON-LD representation of this instance.
         /// </returns>
-        public override string ToString() =>
-            RemoveAllButFirstContext(JsonConvert.SerializeObject(this, SerializerSettings));
+        public override string ToString() => this.ToString(SerializerSettings);
+
+        /// <summary>
+        /// Returns the JSON-LD representation of this instance.
+        ///
+        /// This method should be used when you want to embed the output raw (as-is) into a web
+        /// page. It uses serializer settings with HTML escaping to avoid Cross-Site Scripting (XSS)
+        /// vulnerabilities if the object was constructed from an untrusted source.
+        /// </summary>
+        /// <returns>
+        /// A <see cref="string" /> that represents the JSON-LD representation of this instance.
+        /// </returns>
+        public string ToHtmlEscapedString() => this.ToString(HtmlEscapedSerializerSettings);
+
+        /// <summary>
+        /// Returns the JSON-LD representation of this instance using the <see cref="JsonSerializerSettings"/> provided.
+        ///
+        /// Caution: You should ensure your <paramref name="serializerSettings"/> has
+        /// <see cref="JsonSerializerSettings.StringEscapeHandling"/> set to <see cref="StringEscapeHandling.EscapeHtml"/>
+        /// if you plan to embed the output using @Html.Raw anywhere in a web page, else you open yourself up a possible
+        /// Cross-Site Scripting (XSS) attack if untrusted data is set on any of this object's properties.
+        /// </summary>
+        /// <param name="serializerSettings">Serialization settings.</param>
+        /// <returns>
+        /// A <see cref="string" /> that represents the JSON-LD representation of this instance.
+        /// </returns>
+        public string ToString(JsonSerializerSettings serializerSettings) =>
+            RemoveAllButFirstContext(JsonConvert.SerializeObject(this, serializerSettings));
 
         private static string RemoveAllButFirstContext(string json)
         {
diff --git a/Tests/Schema.NET.Test/ProductTest.cs b/Tests/Schema.NET.Test/ProductTest.cs
@@ -44,7 +44,7 @@ public class ProductTest
             "\"@context\":\"http://schema.org\"," +
             "\"@type\":\"Product\"," +
             "\"name\":\"Executive Anvil\"," +
-            "\"description\":\"Sleeker than ACME\\u0027s Classic Anvil, the Executive Anvil is perfect for the business traveller looking for something to drop from a height.\"," +
+            "\"description\":\"Sleeker than ACME's Classic Anvil, the Executive Anvil is perfect for the business traveller looking for something to drop from a height.\"," +
             "\"image\":\"http://www.example.com/anvil_executive.jpg\"," +
             "\"aggregateRating\":{" +
                 "\"@type\":\"AggregateRating\"," +
diff --git a/Tests/Schema.NET.Test/RecipeTest.cs b/Tests/Schema.NET.Test/RecipeTest.cs
@@ -45,8 +45,8 @@ public class RecipeTest
             "{" +
             "\"@context\":\"http://schema.org\"," +
             "\"@type\":\"Recipe\"," +
-            "\"name\":\"Grandma\\u0027s Holiday Apple Pie\"," +
-            "\"description\":\"This is my grandmother\\u0027s apple pie recipe. I like to add a dash of nutmeg.\"," +
+            "\"name\":\"Grandma's Holiday Apple Pie\"," +
+            "\"description\":\"This is my grandmother's apple pie recipe. I like to add a dash of nutmeg.\"," +
             "\"image\":\"https://example.com/image.jpg\"," +
             "\"aggregateRating\":{" +
                 "\"@type\":\"AggregateRating\"," +
diff --git a/Tests/Schema.NET.Test/RestaurantTest.cs b/Tests/Schema.NET.Test/RestaurantTest.cs
@@ -66,7 +66,7 @@ public class RestaurantTest
             "\"@context\":\"http://schema.org\"," +
             "\"@type\":\"Restaurant\"," +
             "\"@id\":\"http://davessteakhouse.example.com\"," +
-            "\"name\":\"Dave\\u0027s Steak House\"," +
+            "\"name\":\"Dave's Steak House\"," +
             "\"image\":\"http://davessteakhouse.example.com/logo.jpg\"," +
             "\"sameAs\":\"http://davessteakhouse.example.com\"," +
             "\"address\":{" +
diff --git a/Tests/Schema.NET.Test/SerializationTest.cs b/Tests/Schema.NET.Test/SerializationTest.cs
@@ -1,22 +1,40 @@
 namespace Schema.NET.Test
 {
     using System;
+    using System.Collections.Generic;
+    using Newtonsoft.Json;
+    using Newtonsoft.Json.Converters;
     using Xunit;
 
     // https://developers.google.com/search/docs/data-types/books
     public class SerializationTest
     {
+        private static readonly Person Person = new Person()
+        {
+            Name = "J.D. Salinger</script><script>alert('gotcha');</script>",
+            Description = null
+        };
+
         private readonly Book book = new Book()
         {
             Id = new Uri("http://example.com/book/1"),
             Name = "The Catcher in the Rye</script><script>alert('gotcha');</script>",
-            Author = new Person()
-            {
-                Name = "J.D. Salinger</script><script>alert('gotcha');</script>"
-            }
+            Author = Person
         };
 
         private readonly string json =
+        "{" +
+            "\"@context\":\"http://schema.org\"," +
+            "\"@type\":\"Book\"," +
+            "\"@id\":\"http://example.com/book/1\"," +
+            "\"name\":\"The Catcher in the Rye</script><script>alert('gotcha');</script>\"," +
+            "\"author\":{" +
+                "\"@type\":\"Person\"," +
+                "\"name\":\"J.D. Salinger</script><script>alert('gotcha');</script>\"" +
+            "}" +
+        "}";
+
+        private readonly string jsonHtmlEscaped =
         "{" +
             "\"@context\":\"http://schema.org\"," +
             "\"@type\":\"Book\"," +
@@ -28,8 +46,43 @@ public class SerializationTest
             "}" +
         "}";
 
+        private readonly JsonSerializerSettings customSerializerSettings = new JsonSerializerSettings()
+        {
+            Converters = new List<JsonConverter>()
+            {
+                new StringEnumConverter()
+            },
+            NullValueHandling = NullValueHandling.Include, // changed
+            StringEscapeHandling = StringEscapeHandling.EscapeHtml,
+        };
+
+        private readonly string jsonCustom =
+        "{" +
+            "\"@context\":\"http://schema.org\"," +
+            "\"@type\":\"Person\"," +
+            "\"@id\":null," +
+            "\"name\":\"J.D. Salinger\\u003c/script\\u003e\\u003cscript\\u003ealert(\\u0027gotcha\\u0027);\\u003c/script\\u003e\"," +
+            "\"description\":null,\"additionalType\":null,\"alternateName\":null,\"disambiguatingDescription\":null,\"identifier\":null," +
+            "\"image\":null,\"mainEntityOfPage\":null,\"potentialAction\":null,\"sameAs\":null,\"url\":null,\"additionalName\":null," +
+            "\"address\":null,\"affiliation\":null,\"alumniOf\":null,\"award\":null,\"birthDate\":null,\"birthPlace\":null,\"brand\":null," +
+            "\"children\":null,\"colleague\":null,\"contactPoint\":null,\"deathDate\":null,\"deathPlace\":null,\"duns\":null,\"email\":null," +
+            "\"familyName\":null,\"faxNumber\":null,\"follows\":null,\"funder\":null,\"gender\":null,\"givenName\":null," +
+            "\"globalLocationNumber\":null,\"hasOfferCatalog\":null,\"hasPOS\":null,\"height\":null,\"homeLocation\":null," +
+            "\"honorificPrefix\":null,\"honorificSuffix\":null,\"isicV4\":null,\"jobTitle\":null,\"knows\":null,\"makesOffer\":null," +
+            "\"memberOf\":null,\"naics\":null,\"nationality\":null,\"netWorth\":null,\"owns\":null,\"parent\":null,\"performerIn\":null," +
+            "\"publishingPrinciples\":null,\"relatedTo\":null,\"seeks\":null,\"sibling\":null,\"sponsor\":null,\"spouse\":null,\"taxID\":null," +
+            "\"telephone\":null,\"vatID\":null,\"weight\":null,\"workLocation\":null,\"worksFor\":null}";
+
         [Fact]
         public void ToString_UnsafeBookData_ReturnsExpectedJsonLd() =>
             Assert.Equal(this.json, this.book.ToString());
+
+        [Fact]
+        public void ToHtmlEscapedString_UnsafeBookData_ReturnsExpectedJsonLd() =>
+            Assert.Equal(this.jsonHtmlEscaped, this.book.ToHtmlEscapedString());
+
+        [Fact]
+        public void ToStringWithCustomSerializerSettings_UnsafeAuthorData_ReturnsExpectedJsonLd() =>
+            Assert.Equal(this.jsonCustom, Person.ToString(this.customSerializerSettings));
     }
 }
diff --git a/Tests/Schema.NET.Test/WebsiteTest.cs b/Tests/Schema.NET.Test/WebsiteTest.cs
@@ -25,7 +25,7 @@ public void ToString_SiteLinksSearchBoxGoogleStructuredData_ReturnsExpectedJsonL
                     "\"@type\":\"WebSite\"," +
                     "\"potentialAction\":{" +
                         "\"@type\":\"SearchAction\"," +
-                        "\"target\":\"http://example.com/search?\\u0026q={query}\"," +
+                        "\"target\":\"http://example.com/search?&q={query}\"," +
                         "\"query-input\":\"required\"" +
                     "}," +
                     "\"url\":\"https://example.com\"" +
