Spec-Zone.ru › Angular.js 1.3

Улучшить эту документацию Просмотреть исходный код $sce

  1. $sceProvider
  2. сервис в модуле ng

$sce — это сервис, предоставляющий службы строгого контекстного экранирования для AngularJS.

Строгое контекстное экранирование

Строгое контекстное экранирование (SCE) — это режим, в котором AngularJS требует, чтобы привязки в определенных контекстах возвращали значение, отмеченное как безопасное для использования в данном контексте. Одним из примеров такого контекста является привязка произвольного HTML, управляемого пользователем через ng-bind-html. Мы называем эти контексты привилегированными или контекстами SCE.

Начиная с версии 1.2, Angular по умолчанию включил SCE.

Примечание: При включенном режиме (по умолчанию) IE<11 в режиме совместимости не поддерживается. В этом режиме IE<11 позволяет выполнять произвольный JavaScript с помощью синтаксиса expression(). Обратитесь к для получения дополнительной информации. Вы можете убедиться, что ваш документ находится в стандартном режиме, а не в режиме совместимости, добавив <!doctype html> в начало вашего HTML-документа.

SCE помогает создавать код, который (a) по умолчанию безопасен и (b) упрощает аудит на предмет таких уязвимостей, как XSS, clickjacking и т. д.

Вот пример привязки в привилегированном контексте:

<input ng-model="userHtml">
<div ng-bind-html="userHtml"></div>

Обратите внимание, что ng-bind-html привязан к userHtml, управляемому пользователем. Без SCE это приложение позволяет пользователю отображать произвольный HTML в DIV. В более реалистичном примере могут отображаться пользовательские комментарии, статьи блога и т. д. через привязки. (HTML — это всего лишь один пример контекста, где отображение пользовательского ввода приводит к уязвимостям безопасности.)

В случае с HTML можно использовать библиотеку, либо на стороне клиента, либо на стороне сервера, для очистки небезопасного HTML перед привязкой к значению и отображением его в документе.

Как убедиться, что все места с такими привязками привязаны к значению, очищенному вашей библиотекой (или возвращённому как безопасное для отображения вашим сервером)? Как убедиться, что вы случайно не удалили строку, очищающую значение, или не переименовали некоторые свойства/поля и не забыли обновить привязку к очищенному значению?

Чтобы обеспечить безопасность по умолчанию, необходимо убедиться, что все такие привязки запрещены, если вы не можете определить, что что-то явно указывает на безопасность использования значения для привязки в этом контексте. Затем вы можете проанализировать свой код (простой grep подойдет) для проверки того, что это делается только для тех значений, которые вы легко можете определить как безопасные — поскольку они были получены от вашего сервера, обработаны вашей библиотекой и т. д. Вы можете организовать свою кодовую базу, чтобы помочь с этим — возможно, позволяя выполнять это только файлам в определенной папке. Обеспечение того, что внутренний API, предоставляемый этим кодом, не помечает произвольные значения как безопасные, тогда станет более управляемой задачей.

В случае сервиса SCE AngularJS используется $sce.trustAs (и сокращённые методы, такие как $sce.trustAsHtml и т. д.) для получения значений, которые будут приняты контекстами SCE/привилегированными контекстами.

Как это работает?

В привилегированных контекстах директивы и код будут привязаны к результату $sce.getTrusted(context, value), а не непосредственно к значению. Директивы используют $sce.parseAs, а не $parse для отслеживания привязок атрибутов, что выполняет $sce.getTrusted за кулисами для неконстантных литералов.

Например, ngBindHtml использует $sce.parseAsHtml(выражение привязки). Вот фактический код (несколько упрощённый):

var ngBindHtmlDirective = ['$sce', function($sce) {
  return function(scope, element, attr) {
    scope.$watch($sce.parseAsHtml(attr.ngBindHtml), function(value) {
      element.html(value || '');
    });
  };
}];

Воздействие на загрузку шаблонов

Это относится как к директиве ng-include, так и к templateUrl, определённым директивами директивами.

По умолчанию Angular загружает шаблоны только с того же домена и протокола, что и документ приложения. Это выполняется путём вызова $sce.getTrustedResourceUrl для URL шаблона. Для загрузки шаблонов с других доменов и/или протоколов вы можете либо включить их в белый список, либо упаковать их в надёжное значение.

Обратите внимание: политика браузера Same Origin Policy и политика совместного использования ресурсов между источниками (CORS) применяются дополнительно и могут дополнительно ограничить, загрузится ли шаблон успешно. Это означает, что без соответствующей политики CORS загрузка шаблонов с другого домена не будет работать во всех браузерах. Кроме того, загрузка шаблонов с file:// URL не работает в некоторых браузерах.

Это кажется излишней нагрузкой

Важно помнить, что SCE применяется только к выражениям интерполяции.

Если ваши выражения являются константными литералами, они автоматически считаются надёжными, и вам не нужно вызывать $sce.trustAs для них (не забудьте включить модуль ngSanitize). (Например, <div ng-bind-html="'<b>implicitly trusted</b>'"></div>) просто работает.

Кроме того, a[href] и img[src] автоматически очищают свои URL-адреса и не передают их через $sce.getTrusted. SCE здесь не играет роли.

Включённый $sceDelegate поставляется с разумными значениями по умолчанию, которые позволяют загружать шаблоны в ng-include из домена вашего приложения, без необходимости даже знать о SCE. Он блокирует загрузку шаблонов с других доменов или загрузку шаблонов по протоколу http из документа, серверного по https. Вы можете изменить их, задав свои собственные пользовательские белые списки и чёрные списки для сопоставления таких URL.

Это значительно снижает нагрузку. Гораздо проще заплатить небольшую плату за накладные расходы и получить приложение, которое безопасно и может быть проверено на соответствие безопасности намного легче, чем добавлять безопасность в приложение позже.

Какие типы надёжных контекстов поддерживаются?

Контекст Примечания
$sce.HTML Для HTML, который безопасно импортировать в приложение. Директива ngBindHtml использует этот контекст для привязок. Если встречается небезопасное значение и присутствует модуль $sanitize, это значение будет очищено вместо выдачи ошибки.
$sce.CSS Для CSS, который безопасно импортировать в приложение. В настоящее время не используется. Вы можете использовать его в собственных директивах.
$sce.URL Для URL-адресов, которые безопасно использовать в качестве ссылок. В настоящее время не используется (<a href= и <img src= очищают свои URL-адреса и не являются контекстами SCE).
$sce.RESOURCE_URL Для URL-адресов, которые не только безопасны для использования в качестве ссылок, но и чьё содержимое безопасно включать в ваше приложение. Примеры включают ng-include, src / ngSrc привязки для тегов, отличных от IMG (например, IFRAME, OBJECT, и т. д.).

Обратите внимание, что $sce.RESOURCE_URL делает более сильное заявление о URL-адресе, чем $sce.URL, и поэтому контексты, требующие значений, надёжных для $sce.RESOURCE_URL, могут быть использованы в любом месте, где требуются значения, надёжные для $sce.URL.
$sce.JS Для JavaScript, который безопасно выполнить в контексте вашего приложения. В настоящее время не используется. Вы можете использовать его в собственных директивах.

Формат элементов в resourceUrlWhitelist/чёрном списке

Каждый элемент в этих массивах должен быть одним из следующих:

  • 'self'
    • Специальная строка, 'self', может использоваться для сопоставления со всеми URL-адресами одного домена приложения, использующего тот же протокол.
  • Строка (кроме специального значения 'self')
    • Строка сопоставляется с полным нормализованным/абсолютным URL-адресом проверяемого ресурса (совпадение по подстрокам недостаточно).
    • Существует ровно две последовательности подстановок - * и **. Все остальные символы соответствуют самим себе.
    • *: соответствует нулю или более вхождениям любого символа, кроме одного из следующих 6 символов: ':', '/', '.', '?', '&' и ';'. Это полезная подстановка для использования в белом списке.
    • **: соответствует нулю или более вхождениям любого символа. Поэтому она не подходит для использования в схеме, домене и т. д., так как может соответствовать слишком многому. (например, http://**.example.com/ будет соответствовать http://evil.com/?ignore=.example.com/, и это, возможно, не было целью.) Ее использование в самом конце пути допустимо. (например, http://foo.example.com/templates/**).
  • RegExp (см. замечание ниже)
    • Замечание: Хотя регулярные выражения мощные и предлагают большую гибкость, их синтаксис (и все неизбежные экранирования) делает их сложнее поддерживать. Легко случайно ввести ошибку при обновлении сложного выражения (на мой взгляд, все регулярные выражения должны иметь хорошее покрытие тестами). Например, использование . в регулярном выражении верно только в небольшом количестве случаев. Символ . в регулярном выражении, используемом при сопоставлении схемы или поддомена, может соответствовать : или буквенному ., что, вероятно, не предполагалось. Настоятельно рекомендуется использовать шаблоны строк и переходить к регулярным выражениям только в крайнем случае.
    • Регулярное выражение должно быть экземпляром RegExp (то есть не строкой). Оно сопоставляется со всем нормализованным/абсолютным URL-адресом проверяемого ресурса (даже когда в регулярном выражении отсутствуют коды ^ и $). Кроме того, любые флаги, присутствующие в регулярном выражении (например, многострочный, глобальный, игнорирование регистра), игнорируются.
    • Если вы генерируете свой JavaScript из другого шаблонизатора (не рекомендуется, например, в проблеме #4006), не забудьте экранировать свое регулярное выражение (и имейте в виду, что вам может потребоваться больше одного уровня экранирования в зависимости от вашего шаблонизатора и способа интерполяции значения). Используйте механизм экранирования вашей платформы, так как он может быть достаточным до кодирования собственного. Например, в Ruby есть Regexp.escape(str), а в Python есть re.escape. Javascript не имеет аналогичной встроенной функции для экранирования. Обратите внимание на библиотеку Google Closure goog.string.regExpEscape(s).

См. пример в $sceDelegateProvider.

Показать пример использования SCE.

Можно ли полностью отключить SCE?

Да, можно. Однако это крайне не рекомендуется. SCE предоставляет множество преимуществ в области безопасности с небольшими затратами на программирование. Будет гораздо сложнее взять приложение, в котором отключен SCE, и либо защитить его самостоятельно, либо включить SCE на более позднем этапе. Возможно, отключение SCE будет уместно в тех случаях, когда у вас много существующего кода, написанного до введения SCE, и вы мигрируете их по модулям.

Тем не менее, вот как можно полностью отключить SCE:

angular.module('myAppWithSceDisabledmyApp', []).config(function($sceProvider) {
  // Completely disable SCE.  For demonstration purposes only!
  // Do not use in new projects.
  $sceProvider.enabled(false);
});

Использование

$sce();

Методы

  • isEnabled();

    Возвращает булево значение, указывающее, включен ли SCE.

    Возвращает

    Boolean

    true, если SCE включен, false в противном случае. Если вы хотите установить значение, вы должны сделать это во время настройки модуля в $sceProvider.

  • parseAs(type, expression);

    Преобразует выражение Angular expression в функцию. Это похоже на $parse и идентично, когда выражение является константой. В противном случае оно оборачивает выражение в вызов $sce.getTrusted(type, result)

    Параметры

    Param Type Details
    type string

    Тип контекста SCE, в котором будет использоваться этот результат.
    expression string

    Строковое выражение для компиляции.

    Возвращает

    function(context, locals)

    функцию, которая представляет скомпилированное выражение:

    • context – {object} – объект, относительно которого вычисляются любые выражения, встроенные в строки (обычно объект области видимости).
    • locals – {object=} – контекстный объект локальных переменных, полезный для переопределения значений в context.

  • trustAs(type, value);

    Делегирует $sceDelegate.trustAs. Таким образом, возвращает объект, которому доверяет Angular для использования в указанных строгих контекстных контекстах экранирования (таких как ng-bind-html, ng-include, любое интерполяция атрибута src, любая интерполяция атрибута привязки события DOM, например, для onclick и т. д.), использующих предоставленное значение. См. * $sce для включения строгого контекстного экранирования.

    Параметры

    Param Type Details
    type string

    Тип контекста, в котором это значение безопасно для использования. например, url, resource_url, html, js и css.
    value *

    Значение, которое следует считать доверенным/безопасным.

    Возвращает

    *

    Значение, которое может быть использовано вместо предоставленного value в местах, где Angular ожидает возвращаемого значения $sce.trustAs().

  • trustAsHtml(value);

    Сокращенный метод. $sce.trustAsHtml(value) → $sceDelegate.trustAs($sce.HTML, value)

    Параметры

    Param Type Details
    value *

    Значение для trustAs.

    Возвращает

    *

    Объект, который может быть передан в $sce.getTrustedHtml(value) для получения исходного значения. (привилегированные директивы принимают только выражения, которые являются либо литеральными константами, либо возвращаемым значением $sce.trustAs.)

  • trustAsUrl(value);

    Сокращенный метод. $sce.trustAsUrl(value) → $sceDelegate.trustAs($sce.URL, value)

    Параметры

    Param Type Details
    value *

    Значение для trustAs.

    Возвращает

    *

    Объект, который может быть передан в $sce.getTrustedUrl(value) для получения исходного значения. (привилегированные директивы принимают только выражения, которые являются либо литеральными константами, либо возвращаемым значением $sce.trustAs.)

  • trustAsResourceUrl(value);

    Сокращенный метод. $sce.trustAsResourceUrl(value) → $sceDelegate.trustAs($sce.RESOURCE_URL, value)

    Параметры

    Param Type Details
    value *

    Значение для trustAs.

    Возвращает

    *

    Объект, который может быть передан в $sce.getTrustedResourceUrl(value) для получения исходного значения. (привилегированные директивы принимают только выражения, которые являются либо литеральными константами, либо возвращаемым значением $sce.trustAs.)

  • trustAsJs(value);

    Сокращенный метод. $sce.trustAsJs(value) → $sceDelegate.trustAs($sce.JS, value)

    Параметры

    Param Type Details
    value *

    Значение для trustAs.

    Возвращает

    *

    Объект, который может быть передан в $sce.getTrustedJs(value) для получения исходного значения. (привилегированные директивы принимают только выражения, которые являются либо литеральными константами, либо возвращаемым значением $sce.trustAs.)

  • getTrusted(type, maybeTrusted);

    Делегирует $sceDelegate.getTrusted. Таким образом, принимает результат вызова $sce.trustAs() и возвращает исходно предоставленное значение, если запрашиваемый тип контекста является супертипом созданного типа. Если это условие не выполняется, выдает исключение.

    Параметры

    Param Type Details
    type string

    Тип контекста, в котором будет использоваться это значение.
    maybeTrusted *

    Результат предыдущего вызова $sce.trustAs.

    Возвращает

    *

    Значение, которое было первоначально предоставлено $sce.trustAs, если оно допустимо в этом контексте. В противном случае, выдает исключение.

  • getTrustedHtml(value);

    Сокращенный метод. $sce.getTrustedHtml(value) → $sceDelegate.getTrusted($sce.HTML, value)

    Параметры

    Param Type Details
    value *

    Значение для передачи в $sce.getTrusted.

    Возвращает

    *

    Возвращаемое значение $sce.getTrusted($sce.HTML, value)

  • getTrustedCss(value);

    Сокращенный метод. $sce.getTrustedCss(value) → $sceDelegate.getTrusted($sce.CSS, value)

    Параметры

    Param Type Details
    value *

    Значение для передачи в $sce.getTrusted.

    Возвращает

    *

    Возвращаемое значение $sce.getTrusted($sce.CSS, value)

  • getTrustedUrl(value);

    Сокращенный метод. $sce.getTrustedUrl(value) → $sceDelegate.getTrusted($sce.URL, value)

    Параметры

    Param Type Details
    value *

    Значение для передачи в $sce.getTrusted.

    Возвращает

    *

    Возвращаемое значение $sce.getTrusted($sce.URL, value)

  • getTrustedResourceUrl(value);

    Сокращенный метод. $sce.getTrustedResourceUrl(value) → $sceDelegate.getTrusted($sce.RESOURCE_URL, value)

    Параметры

    Param Type Details
    value *

    Значение для передачи в $sceDelegate.getTrusted.

    Возвращает

    *

    Возвращаемое значение $sce.getTrusted($sce.RESOURCE_URL, value)

  • getTrustedJs(value);

    Сокращенный метод. $sce.getTrustedJs(value) → $sceDelegate.getTrusted($sce.JS, value)

    Параметры

    Param Type Details
    value *

    Значение для передачи в $sce.getTrusted.

    Возвращает

    *

    Возвращаемое значение $sce.getTrusted($sce.JS, value)

  • parseAsHtml(expression);

    Укороченный метод. $sce.parseAsHtml(expression string) → $sce.parseAs($sce.HTML, value)

    Параметры

    Параметр Тип Подробности
    expression string

    Строковое выражение для компиляции.

    Возвращаемое значение

    function(context, locals)

    функция, представляющая скомпилированное выражение:

    • context – {object} – объект, относительно которого оцениваются любые выражения, встроенные в строки (обычно объект области видимости).
    • locals – {object=} – объект контекста локальных переменных, полезный для переопределения значений в context.

  • parseAsCss(expression);

    Укороченный метод. $sce.parseAsCss(value) → $sce.parseAs($sce.CSS, value)

    Параметры

    Параметр Тип Подробности
    expression string

    Строковое выражение для компиляции.

    Возвращаемое значение

    function(context, locals)

    функция, представляющая скомпилированное выражение:

    • context – {object} – объект, относительно которого оцениваются любые выражения, встроенные в строки (обычно объект области видимости).
    • locals – {object=} – объект контекста локальных переменных, полезный для переопределения значений в context.

  • parseAsUrl(expression);

    Укороченный метод. $sce.parseAsUrl(value) → $sce.parseAs($sce.URL, value)

    Параметры

    Параметр Тип Подробности
    expression string

    Строковое выражение для компиляции.

    Возвращаемое значение

    function(context, locals)

    функция, представляющая скомпилированное выражение:

    • context – {object} – объект, относительно которого оцениваются любые выражения, встроенные в строки (обычно объект области видимости).
    • locals – {object=} – объект контекста локальных переменных, полезный для переопределения значений в context.

  • parseAsResourceUrl(expression);

    Укороченный метод. $sce.parseAsResourceUrl(value) → $sce.parseAs($sce.RESOURCE_URL, value)

    Параметры

    Параметр Тип Подробности
    expression string

    Строковое выражение для компиляции.

    Возвращаемое значение

    function(context, locals)

    функция, представляющая скомпилированное выражение:

    • context – {object} – объект, относительно которого оцениваются любые выражения, встроенные в строки (обычно объект области видимости).
    • locals – {object=} – объект контекста локальных переменных, полезный для переопределения значений в context.

  • parseAsJs(expression);

    Укороченный метод. $sce.parseAsJs(value) → $sce.parseAs($sce.JS, value)

    Параметры

    Параметр Тип Подробности
    expression string

    Строковое выражение для компиляции.

    Возвращаемое значение

    function(context, locals)

    функция, представляющая скомпилированное выражение:

    • context – {object} – объект, относительно которого оцениваются любые выражения, встроенные в строки (обычно объект области видимости).
    • locals – {object=} – объект контекста локальных переменных, полезный для переопределения значений в context.

© 2010–2017 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://code.angularjs.org/1.3.20/docs/api/ng/service/$sce

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API