Spec-Zone.ru › Angular.js 1.2

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

  1. $sceProvider
  2. служба в модуле ng

$sce — это служба, предоставляющая функции Strict Contextual Escaping для AngularJS.

Строгая контекстная экранизация

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

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

Примечание: При включенном режиме (по умолчанию) не поддерживается IE8 в режиме quirks. В этом режиме IE8 позволяет исполнять произвольный JavaScript с помощью синтаксиса expression(). Дополнительную информацию см. в http://blogs.msdn.com/b/ie/archive/2008/10/16/ending-expressions.aspx. Вы можете убедиться, что ваш документ находится в режиме стандартов, а не в режиме quirks, добавив <!doctype html> в начало вашего HTML-документа.

SCE помогает писать код, который (а) по умолчанию безопасен и (б) упрощает аудит на предмет таких уязвимостей, как 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-адресов для сопоставления с такими 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/Blacklist

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

  • '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.2.32/docs/api/ng/service/$sce

Spec-Zone.ru

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