feat($sce): new $sce service for Strict Contextual Escaping.

$sce is a service that provides Strict Contextual Escaping services to AngularJS. Strict Contextual Escaping -------------------------- Strict Contextual Escaping (SCE) is a mode in which AngularJS requires bindings in certain contexts to result in a value that is marked as safe to use for that context One example of such a context is binding arbitrary html controlled by the user via ng-bind-html-unsafe. We refer to these contexts as privileged or SCE contexts. As of version 1.2, Angular ships with SCE enabled by default. Note: When enabled (the default), IE8 in quirks mode is not supported. In this mode, IE8 allows one to execute arbitrary javascript by the use of the expression() syntax. Refer http://blogs.msdn.com/b/ie/archive/2008/10/16/ending-expressions.aspx to learn more about them. You can ensure your document is in standards mode and not quirks mode by adding <!doctype html> to the top of your HTML document. SCE assists in writing code in way that (a) is secure by default and (b) makes auditing for security vulnerabilities such as XSS, clickjacking, etc. a lot easier. Here's an example of a binding in a privileged context: <input ng-model="userHtml"> <div ng-bind-html-unsafe="{{userHtml}}"> Notice that ng-bind-html-unsafe is bound to {{userHtml}} controlled by the user. With SCE disabled, this application allows the user to render arbitrary HTML into the DIV. In a more realistic example, one may be rendering user comments, blog articles, etc. via bindings. (HTML is just one example of a context where rendering user controlled input creates security vulnerabilities.) For the case of HTML, you might use a library, either on the client side, or on the server side, to sanitize unsafe HTML before binding to the value and rendering it in the document. How would you ensure that every place that used these types of bindings was bound to a value that was sanitized by your library (or returned as safe for rendering by your server?) How can you ensure that you didn't accidentally delete the line that sanitized the value, or renamed some properties/fields and forgot to update the binding to the sanitized value? To be secure by default, you want to ensure that any such bindings are disallowed unless you can determine that something explicitly says it's safe to use a value for binding in that context. You can then audit your code (a simple grep would do) to ensure that this is only done for those values that you can easily tell are safe - because they were received from your server, sanitized by your library, etc. You can organize your codebase to help with this - perhaps allowing only the files in a specific directory to do this. Ensuring that the internal API exposed by that code doesn't markup arbitrary values as safe then becomes a more manageable task. In the case of AngularJS' SCE service, one uses $sce.trustAs (and shorthand methods such as $sce.trustAsHtml, etc.) to obtain values that will be accepted by SCE / privileged contexts. In privileged contexts, directives and code will bind to the result of $sce.getTrusted(context, value) rather than to the value directly. Directives use $sce.parseAs rather than $parse to watch attribute bindings, which performs the $sce.getTrusted behind the scenes on non-constant literals. As an example, ngBindHtmlUnsafe uses $sce.parseAsHtml(binding expression). Here's the actual code (slightly simplified): var ngBindHtmlUnsafeDirective = ['$sce', function($sce) { return function(scope, element, attr) { scope.$watch($sce.parseAsHtml(attr.ngBindHtmlUnsafe), function(value) { element.html(value || ''); }); }; }]; Impact on loading templates --------------------------- This applies both to the ng-include directive as well as templateUrl's specified by directives. By default, Angular only loads templates from the same domain and protocol as the application document. This is done by calling $sce.getTrustedResourceUrl on the template URL. To load templates from other domains and/or protocols, you may either either whitelist them or wrap it into a trusted value. *Please note*: The browser's Same Origin Policy and Cross-Origin Resource Sharing (CORS) policy apply in addition to this and may further restrict whether the template is successfully loaded. This means that without the right CORS policy, loading templates from a different domain won't work on all browsers. Also, loading templates from file:// URL does not work on some browsers. This feels like too much overhead for the developer? ---------------------------------------------------- It's important to remember that SCE only applies to interpolation expressions. If your expressions are constant literals, they're automatically trusted and you don't need to call $sce.trustAs on them. e.g. <div ng-html-bind-unsafe="'<b>implicitly trusted</b>'"></div> just works. Additionally, a[href] and img[src] automatically sanitize their URLs and do not pass them through $sce.getTrusted. SCE doesn't play a role here. The included $sceDelegate comes with sane defaults to allow you to load templates in ng-include from your application's domain without having to even know about SCE. It blocks loading templates from other domains or loading templates over http from an https served document. You can change these by setting your own custom whitelists and blacklists for matching such URLs. This significantly reduces the overhead. It is far easier to pay the small overhead and have an application that's secure and can be audited to verify that with much more ease than bolting security onto an application later.
author: Chirayu Krishnappa 2013-05-14 14:51:39 -0700
committer: Chirayu Krishnappa 2013-07-25 13:00:35 -0700
commit: bea9422ebfc8e80ee28ad81afc62d2e432c85cbb (patch)
tree: 718e35908d9a017e51041b080276826f6595c8d2 /test/ng/sceSpecs.js
parent: fb7d891dacdcb9f799061d5fbb96cdd2dd912196 (diff)
download: angular.js-bea9422ebfc8e80ee28ad81afc62d2e432c85cbb.tar.bz2
1 files changed, 347 insertions, 0 deletions
diff --git a/test/ng/sceSpecs.js b/test/ng/sceSpecs.js
new file mode 100644
index 00000000..16525b8d
--- /dev/null
+++ b/test/ng/sceSpecs.js
@@ -0,0 +1,347 @@
+'use strict';
+
+describe('SCE', function() {
+
+  describe('when disabled', function() {
+    beforeEach(function() {
+      module(function($sceProvider) {
+        $sceProvider.enabled(false);
+      });
+    });
+
+    it('should provide the getter for enabled', inject(function($sce) {
+      expect($sce.isEnabled()).toBe(false);
+    }));
+
+    it('should not wrap/unwrap any value or throw exception on non-string values', inject(function($sce) {
+      var originalValue = { foo: "bar" };
+      expect($sce.trustAs($sce.JS, originalValue)).toBe(originalValue);
+      expect($sce.getTrusted($sce.JS, originalValue)).toBe(originalValue);
+    }));
+  });
+
+  describe('IE8 quirks mode', function() {
+    function runTest(enabled, documentMode, expectException) {
+      module(function($provide) {
+        $provide.value('$document', [{
+          documentMode: documentMode,
+          createElement: function() {}
+        }]);
+        $provide.value('$sceDelegate', {trustAs: null, valueOf: null, getTrusted: null});
+      });
+
+      inject(function($window, $injector) {
+        function constructSce() {
+          var sceProvider = new $SceProvider();
+          sceProvider.enabled(enabled);
+          return $injector.invoke(sceProvider.$get, sceProvider);
+        }
+
+        var origMsie = $window.msie;
+        try {
+          $window.msie = true;
+          if (expectException) {
+            expect(constructSce).toThrow(
+                '[$sce:iequirks] Strict Contextual Escaping does not support Internet Explorer ' +
+                'version < 9 in quirks mode.  You can fix this by adding the text <!doctype html> to ' +
+                'the top of your HTML document.  See http://docs.angularjs.org/api/ng.$sce for more ' +
+                'information.');
+          } else {
+            // no exception.
+            constructSce();
+          }
+        }
+        finally {
+          $window.msie = origMsie;
+        }
+      });
+    }
+
+    it('should throw an exception when sce is enabled in quirks mode', function() {
+      runTest(true, 7, true);
+    });
+
+    it('should NOT throw an exception when sce is enabled and in standards mode', function() {
+      runTest(true, 8, false);
+    });
+
+    it('should NOT throw an exception when sce is enabled and documentMode is undefined', function() {
+      runTest(true, undefined, false);
+    });
+
+    it('should NOT throw an exception when sce is disabled even when in quirks mode', function() {
+      runTest(false, 7, false);
+    });
+
+    it('should NOT throw an exception when sce is disabled and in standards mode', function() {
+      runTest(false, 8, false);
+    });
+
+    it('should NOT throw an exception when sce is disabled and documentMode is undefined', function() {
+      runTest(false, undefined, false);
+    });
+  });
+
+  describe('when enabled', function() {
+    it('should wrap string values with TrustedValueHolder', inject(function($sce) {
+      var originalValue = 'original_value';
+      var wrappedValue = $sce.trustAs($sce.HTML, originalValue);
+      expect(typeof wrappedValue).toBe('object');
+      expect($sce.getTrusted($sce.HTML, wrappedValue)).toBe('original_value');
+      expect(function() { $sce.getTrusted($sce.CSS, wrappedValue); }).toThrow(
+          '[$sce:unsafe] Attempting to use an unsafe value in a safe context.');
+      wrappedValue = $sce.trustAs($sce.CSS, originalValue);
+      expect(typeof wrappedValue).toBe('object');
+      expect($sce.getTrusted($sce.CSS, wrappedValue)).toBe('original_value');
+      expect(function() { $sce.getTrusted($sce.HTML, wrappedValue); }).toThrow(
+          '[$sce:unsafe] Attempting to use an unsafe value in a safe context.');
+      wrappedValue = $sce.trustAs($sce.URL, originalValue);
+      expect(typeof wrappedValue).toBe('object');
+      expect($sce.getTrusted($sce.URL, wrappedValue)).toBe('original_value');
+      wrappedValue = $sce.trustAs($sce.JS, originalValue);
+      expect(typeof wrappedValue).toBe('object');
+      expect($sce.getTrusted($sce.JS, wrappedValue)).toBe('original_value');
+    }));
+
+    it('should NOT wrap non-string values', inject(function($sce) {
+      expect(function() { $sce.trustAsCss(123); }).toThrow(
+          '[$sce:itype] Attempted to trust a non-string value in a content requiring a string: ' +
+          'Context: css');
+    }));
+
+    it('should NOT wrap unknown contexts', inject(function($sce) {
+      expect(function() { $sce.trustAs('unknown1' , '123'); }).toThrow(
+          '[$sce:icontext] Attempted to trust a value in invalid context. Context: unknown1; Value: 123');
+    }));
+
+    it('should NOT wrap undefined context', inject(function($sce) {
+      expect(function() { $sce.trustAs(undefined, '123'); }).toThrow(
+          '[$sce:icontext] Attempted to trust a value in invalid context. Context: undefined; Value: 123');
+    }));
+
+    it('should wrap undefined into undefined', inject(function($sce) {
+      expect($sce.trustAsHtml(undefined)).toBe(undefined);
+    }));
+
+    it('should unwrap undefined into undefined', inject(function($sce) {
+      expect($sce.getTrusted($sce.HTML, undefined)).toBe(undefined);
+    }));
+
+    it('should wrap null into null', inject(function($sce) {
+      expect($sce.trustAsHtml(null)).toBe(null);
+    }));
+
+    it('should unwrap null into null', inject(function($sce) {
+      expect($sce.getTrusted($sce.HTML, null)).toBe(null);
+    }));
+
+    it('should wrap "" into ""', inject(function($sce) {
+      expect($sce.trustAsHtml("")).toBe("");
+    }));
+
+    it('should unwrap null into null', inject(function($sce) {
+      expect($sce.getTrusted($sce.HTML, null)).toBe(null);
+    }));
+
+    it('should unwrap "" into ""', inject(function($sce) {
+      expect($sce.getTrusted($sce.HTML, "")).toBe("");
+    }));
+
+    it('should unwrap values and return the original', inject(function($sce) {
+      var originalValue = "originalValue";
+      var wrappedValue = $sce.trustAs($sce.HTML, originalValue);
+      expect($sce.getTrusted($sce.HTML, wrappedValue)).toBe(originalValue);
+    }));
+
+    it('should NOT unwrap values when the type is different', inject(function($sce) {
+      var originalValue = "originalValue";
+      var wrappedValue = $sce.trustAs($sce.HTML, originalValue);
+      expect(function () { $sce.getTrusted($sce.CSS, wrappedValue); }).toThrow(
+          '[$sce:unsafe] Attempting to use an unsafe value in a safe context.');
+    }));
+
+    it('should NOT unwrap values that had not been wrapped', inject(function($sce) {
+      function TrustedValueHolder(trustedValue) {
+        this.$unwrapTrustedValue = function() {
+          return trustedValue;
+        };
+      }
+      var wrappedValue = new TrustedValueHolder("originalValue");
+      expect(function() { return $sce.getTrusted($sce.HTML, wrappedValue) }).toThrow(
+          '[$sce:unsafe] Attempting to use an unsafe value in a safe context.');
+    }));
+
+    it('should implement toString on trusted values', inject(function($sce) {
+      var originalValue = '123',
+          wrappedValue = $sce.trustAsHtml(originalValue);
+      expect($sce.getTrustedHtml(wrappedValue)).toBe(originalValue);
+      expect(wrappedValue.toString()).toBe(originalValue.toString());
+    }));
+  });
+
+
+  describe('replace $sceDelegate', function() {
+    it('should override the default $sce.trustAs/valueOf/etc.', function() {
+      module(function($provide) {
+        $provide.value('$sceDelegate', {
+            trustAs: function(type, value) { return "wrapped:"   + value; },
+            getTrusted: function(type, value) { return "unwrapped:" + value; },
+            valueOf: function(value) { return "valueOf:" + value; }
+        });
+      });
+
+      inject(function($sce) {
+        expect($sce.trustAsJs("value")).toBe("wrapped:value");
+        expect($sce.valueOf("value")).toBe("valueOf:value");
+        expect($sce.getTrustedJs("value")).toBe("unwrapped:value");
+        expect($sce.parseAsJs("name")({name: "chirayu"})).toBe("unwrapped:chirayu");
+      });
+    });
+  });
+
+
+  describe('$sce.parseAs', function($sce) {
+   it('should parse constant literals as trusted', inject(function($sce) {
+      expect($sce.parseAsJs('1')()).toBe(1);
+      expect($sce.parseAsJs('1', $sce.ANY)()).toBe(1);
+      expect($sce.parseAsJs('1', $sce.HTML)()).toBe(1);
+      expect($sce.parseAsJs('1', 'UNDEFINED')()).toBe(1);
+      expect($sce.parseAsJs('true')()).toBe(true);
+      expect($sce.parseAsJs('false')()).toBe(false);
+      expect($sce.parseAsJs('null')()).toBe(null);
+      expect($sce.parseAsJs('undefined')()).toBe(undefined);
+      expect($sce.parseAsJs('"string"')()).toBe("string");
+    }));
+
+    it('should NOT parse constant non-literals', inject(function($sce) {
+      // Until there's a real world use case for this, we're disallowing
+      // constant non-literals.  See $SceParseProvider.
+      var exprFn = $sce.parseAsJs('1+1');
+      expect(exprFn).toThrow();
+    }));
+
+    it('should NOT return untrusted values from expression function', inject(function($sce) {
+      var exprFn = $sce.parseAs($sce.HTML, 'foo');
+      expect(function() {
+        return exprFn({}, {'foo': true})
+      }).toThrow(
+          '[$sce:unsafe] Attempting to use an unsafe value in a safe context.');
+    }));
+
+    it('should NOT return trusted values of the wrong type from expression function', inject(function($sce) {
+      var exprFn = $sce.parseAs($sce.HTML, 'foo');
+      expect(function() {
+        return exprFn({}, {'foo': $sce.trustAs($sce.JS, '123')})
+      }).toThrow(
+          '[$sce:unsafe] Attempting to use an unsafe value in a safe context.');
+    }));
+
+    it('should return trusted values from expression function', inject(function($sce) {
+      var exprFn = $sce.parseAs($sce.HTML, 'foo');
+      expect(exprFn({}, {'foo': $sce.trustAs($sce.HTML, 'trustedValue')})).toBe('trustedValue');
+    }));
+
+    it('should support shorthand methods', inject(function($sce) {
+      // Test shorthand parse methods.
+      expect($sce.parseAsHtml('1')()).toBe(1);
+      // Test short trustAs methods.
+      expect($sce.trustAsAny).toBeUndefined();
+      expect(function() {
+        // mismatched types.
+        $sce.parseAsCss('foo')({}, {'foo': $sce.trustAsHtml('1')});
+      }).toThrow(
+          '[$sce:unsafe] Attempting to use an unsafe value in a safe context.');
+    }));
+
+  });
+
+  describe('$sceDelegate resource url policies', function() {
+    function runTest(cfg, testFn) {
+      return function() {
+        module(function($sceDelegateProvider) {
+          if (cfg.whiteList !== undefined) {
+            $sceDelegateProvider.resourceUrlWhitelist(cfg.whiteList);
+          }
+          if (cfg.blackList !== undefined) {
+            $sceDelegateProvider.resourceUrlBlacklist(cfg.blackList);
+          }
+        });
+        inject(testFn);
+      }
+    }
+
+    it('should default to "self" which allows relative urls', runTest({}, function($sce, $document) {
+        expect($sce.getTrustedResourceUrl('foo/bar')).toEqual('foo/bar');
+    }));
+
+    it('should reject everything when whitelist is empty', runTest(
+      {
+        whiteList: [],
+        blackList: []
+      }, function($sce) {
+        expect(function() { $sce.getTrustedResourceUrl('#'); }).toThrow(
+          '[$sce:isecrurl] Blocked loading resource from url not allowed by $sceDelegate policy.  URL: #');
+    }));
+
+    it('should match against normalized urls', runTest(
+      {
+        whiteList: [/^foo$/],
+        blackList: []
+      }, function($sce) {
+        expect(function() { $sce.getTrustedResourceUrl('foo'); }).toThrow(
+          '[$sce:isecrurl] Blocked loading resource from url not allowed by $sceDelegate policy.  URL: foo');
+    }));
+
+    it('should support custom regex', runTest(
+      {
+        whiteList: [/^http:\/\/example\.com.*/],
+        blackList: []
+      }, function($sce) {
+        expect($sce.getTrustedResourceUrl('http://example.com/foo')).toEqual('http://example.com/foo');
+        expect(function() { $sce.getTrustedResourceUrl('https://example.com/foo'); }).toThrow(
+          '[$sce:isecrurl] Blocked loading resource from url not allowed by $sceDelegate policy.  URL: https://example.com/foo');
+    }));
+
+    it('should support the special string "self" in whitelist', runTest(
+      {
+        whiteList: ['self'],
+        blackList: []
+      }, function($sce) {
+        expect($sce.getTrustedResourceUrl('foo')).toEqual('foo');
+    }));
+
+    it('should support the special string "self" in blacklist', runTest(
+      {
+        whiteList: [/.*/],
+        blackList: ['self']
+      }, function($sce) {
+        expect(function() { $sce.getTrustedResourceUrl('foo'); }).toThrow(
+          '[$sce:isecrurl] Blocked loading resource from url not allowed by $sceDelegate policy.  URL: foo');
+    }));
+
+    it('should have blacklist override the whitelist', runTest(
+      {
+        whiteList: ['self'],
+        blackList: ['self']
+      }, function($sce) {
+        expect(function() { $sce.getTrustedResourceUrl('foo'); }).toThrow(
+          '[$sce:isecrurl] Blocked loading resource from url not allowed by $sceDelegate policy.  URL: foo');
+    }));
+
+    it('should support multiple items in both lists', runTest(
+      {
+        whiteList: [/^http:\/\/example.com\/1$/, /^http:\/\/example.com\/2$/, /^http:\/\/example.com\/3$/, 'self'],
+        blackList: [/^http:\/\/example.com\/3$/, /open_redirect/],
+      }, function($sce) {
+        expect($sce.getTrustedResourceUrl('same_domain')).toEqual('same_domain');
+        expect($sce.getTrustedResourceUrl('http://example.com/1')).toEqual('http://example.com/1');
+        expect($sce.getTrustedResourceUrl('http://example.com/2')).toEqual('http://example.com/2');
+        expect(function() { $sce.getTrustedResourceUrl('http://example.com/3'); }).toThrow(
+          '[$sce:isecrurl] Blocked loading resource from url not allowed by $sceDelegate policy.  URL: http://example.com/3');
+        expect(function() { $sce.getTrustedResourceUrl('open_redirect'); }).toThrow(
+          '[$sce:isecrurl] Blocked loading resource from url not allowed by $sceDelegate policy.  URL: open_redirect');
+    }));
+
+  });
+});
+
author	Chirayu Krishnappa	2013-05-14 14:51:39 -0700
committer	Chirayu Krishnappa	2013-07-25 13:00:35 -0700
commit	bea9422ebfc8e80ee28ad81afc62d2e432c85cbb (patch)
tree	718e35908d9a017e51041b080276826f6595c8d2 /test/ng/sceSpecs.js
parent	fb7d891dacdcb9f799061d5fbb96cdd2dd912196 (diff)
download	angular.js-bea9422ebfc8e80ee28ad81afc62d2e432c85cbb.tar.bz2