Простой веб-маркер (SWT)

  • Статья

Настоящий документ, выпущенный в 2009 г., разработан в качестве рекомендованного стандарта по Simple Web Token (SWT) для группы IETF. Хотя он не завершен и не является разделом справки, в нем приведены интересные сведения о формате и использовании маркеров SWT.

Аннотация

Версия 0.9.5.1, 4 ноября 2009 г.

Simple Web Token (SWT) предоставляет формат для передачи утверждения между двумя сторонами. Утверждения — это набор пар «имя-значение», закодированных в HTML-форме. Результирующая строка подтверждается SHA 256 HMAC с помощью общего ключа сторон.

Авторы

  • Дик Хартт (dick.hardt@microsoft.com), Редактор

  • Ярон Голанд (yarong@microsoft.com)

Лицензия

Эта спецификация доступна в рамках соглашения Open Web Foundation версии 0.9, которая доступна по адресу [http://groups.google.com/group/open-web-board/web/owf-agreement-for-final-specs---pt-9-draft][Примечание. Обновленный URL-адрес ожидается.] Вы можете просмотреть подписанные копии соглашения Open Web Foundation версии 0.9 для этой спецификации по адресу [URI хранилища соглашений insert group], который также может включать дополнительные стороны перечисленных выше. Ваше использование данной спецификации может подпадать под права прочих третьих лиц. ЭТА СПЕЦИФИКАЦИЯ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ». Участники (соавторы) явно отказываются от любых гарантий (явных, подразумеваемых или иных), включая подразумеваемые гарантии товарного состояния, патентной чистоты, соответствия конкретным целям или прав собственности, связанных со спецификацией. Всю ответственность за внедрение или иное использование спецификации несет исполнитель и пользователь спецификации. НИКАКАЯ СТОРОНА НИ ПРИ КАКИХ ОБСТОЯТЕЛЬСТВАХ НЕ НЕСЕТ ОТВЕТСТВЕННОСТИ ЗА ЛЮБЫЕ УБЫТКИ ИЛИ ЛЮБЫЕ КОСВЕННЫЕ, ОСОБЫЕ, СЛУЧАЙНЫЕ ИЛИ ОПОСРЕДОВАННЫЕ УБЫТКИ ВСЛЕДСТВИЕ ЛЮБЫХ ПРИЧИН В ОТНОШЕНИИ НАСТОЯЩЕЙ СПЕЦИФИКАЦИИ ИЛИ ЕГО УПРАВЛЯЮЩЕГО СОГЛАШЕНИЯ, ВСЛЕДСТВИЕ НАРУШЕНИЯ УСЛОВИЙ КОНТРАКТА, НАРУШЕНИЕ ЗАКОННЫХ ПРАВ (В ТОМ ЧИСЛЕ, ПО НЕБРЕЖНОСТИ) ИЛИ ПО ИНЫМ ПРИЧИНАМ, И НЕЗАВИСИМО ОТ ТОГО, ЗНАЛА ЛИ ДРУГАЯ СТОРОНА О ВОЗМОЖНОСТИ ТАКИХ УБЫТКОВ.

Обзор

Простой веб-маркер (Simple Web Token, SWT) определяет компактный формат для передачи простых утверждений, которые в отформатированном виде могут быть включены в заголовок для протоколов, например HTTP. Простое утверждение может быть представлено как набор пар «имя-значение». Значения, закодированные в форме HTML, соответствуют поставленной целям, которые заключаются в предоставлении хорошо понятного и безопасного формата заголовков HTTP.

Так как маркеры SWT будут передавать важные сведения об идентификации и доступе, требуется предотвратить возможность несанкционированного доступа к ним. Поэтому мы представляем в SWT единственную обязательную пару «имя-значение» — HMACSHA256. Эта пара всегда является последней парой в SWT, а значением является SHA 256 HMAC других пар «имя-значение» в SWT.

Выбор других пар «имя-значение», используемых в SWT, выходит за рамки этой спецификации. Тем не более того, есть ряд условий и атрибутов, которые доказали свою полезность в различных платформах утверждений, в частности: Issuer, Audience и ExpiresOn. Хотя использование этих пар «имя значение» не является обязательным, мы определяем их в данном документе для упрощения взаимодействия.

И, наконец, ожидается, что целый ряд атрибутов будет создан сторонами, осуществляющими обмен SWT. Использование обратных DNS-имен позволяет упростить процесс создания имен атрибутов и исключить возникновение конфликтов имен. Кроме того, поддерживается использование URI в качестве имен. Имена, которые не являются ни обратными DNS-именами, ни URI, представляют собой закрытые имена, определенные соглашением между производителем и потребителем SWT, поэтому они могут быть причиной конфликтов. Имена, определенные в данной спецификации, являются зарезервированными.

Нотация и условные обозначения

Ключевые слова "MUST", "MUST", "MUST", "REQUIRED", "SHALL", "SHOULD", "SHOULD", "SHOULD", "RECOMMENDED", "MAY" и "OPTIONAL" в этом документе должны быть интерпретированы, как описано в [RFC2119] (Bradner, B., "Ключевые слова для использования в RFCs для указания уровней требований","). В примерах доменных имен используется [RFC2606] (Eastlake, D. и A. Panitz, "Зарезервированные DNS-имена верхнего уровня,").

Создание SWT

Сторона, создающая SWT, является производителем SWT. Сторона, проверяющая SWT, является потребителем SWT. Перед созданием SWT производитель и потребителем согласились с использованием атрибутов, содержащихся в SWT, и обменялись внешним произвольно сгенерированным 256-разрядным ключом. Чтобы создать SWT, производитель выполняет следующие действия.

  1. Собирает пары «имя-значение» для передачи в SWT и кодирует их как application/x-www-form-urlencoded согласно 17.13.4 для HTML 4.01

  2. Вводит закодированный SWT и согласованный ключ в процесс SHA 256 HMAC.

  3. Получает результирующее значение HMAC и кодирует его с помощью Base64 согласно разделу 4 в RFC 4648.

  4. Следует правилам кодирования форм, добавляет имя «HMACSHA256» и значение HMAC в кодировке base-64 в конец закодированного SWT.

Проверка SWT

Потребитель SWT выполняет следующие действия, чтобы проверить, что маркер SWT был создан производителем, а не подделан.

  1. Возьмите отправленный SWT-файл и разделите строку на часть до "&HMACSHA256=" и оставшуюся часть, которая является URL-адресом, закодированным HMAC. Первая часть — noHMACSWT.

  2. Декодирует URL-адрес остальной части строки SWT. Это submittedHMAC.

  3. Создайте HMAC для noHMACSWT, используя согласованный ключ, а затем закодируйте его с помощью кодировки Base64 на Base64 на раздел 4 RFC 4648. Результирующая строка будет локальной.

  4. Выполняет посимвольное сравнение submittedHMAC и localHMAC. Если строки равны, HMAC в SWT является допустимым.

Пример SWT

Производитель SWT хочет выдавать SWT со следующими сведениями:

Issuer = issuer.example.com
ExpiresOn = 1/1/2010, Midnight
com.example.group = gold
over18 = true

со значением ключа HMAC (представленным в base 64), равным:

N4QeKa3c062VBjnVK6fb+rnwURkcwGXh7EoNK34n0uM=

В этом примере Issuer и ExpiresOn являются зарезервированными именами из данной спецификации. Атрибут com.example.group является некоторым согласованным определением синтаксиса и семантики группы, созданной владельцем домена example.com. over18 — это частный атрибут, определенный между производителем и потребителем SWT.

Прежде чем закодировать SWT, нужно преобразовать ExpiresOn в значение, равное количеству секунд с 01.01.1970, полночь (UTC) до времени истечения срока действия — 01.01.2010, полночь. Результат — 1 262 304 000.

Кодирование

  1. Закодируйте пары «имя-значение» в HTML-форму. Результат (разрывы строк вставлены для удобства чтения):

    Issuer=issuer.example.com&
ExpiresOn=1262304000&
com.example.group=gold&
over18=true

  2. Далее следует рассчитать HMAC предыдущего значения с помощью ключа.

  3. Выполните кодирование HMAC в формате Base64. Результат:

    AT55+2jLQeuigpg0xm/vn7tjpSGXBUfFe0UXb0/9opE=

  4. Выполните URL-кодирование итогового HMAC в кодировке base64 и прикрепите его к концу утверждения. Результирующий SWT (разрывы строк вставлены для удобства чтения):

    Issuer=issuer.example.com&
ExpiresOn=1262304000&
com.example.group=gold&
over18=true&
HMACSHA256=
AT55%2B2jLQeuigpg0xm%2Fvn7tjpSGXBUfFe0UXb0%2F9opE%3D

Декодирование

  1. Разделите SWT с помощью: &HMACSHA256= мы получаем строку noHMACSWT (строки, добавленные для удобочитаемости):

    Issuer=issuer.example.com&
ExpiresOn=1262304000&
com.example.group=gold&
over18=true&

    и строка submittedHMAC:

    AT55%2B2jLQeuigpg0xm%2Fvn7tjpSGXBUfFe0UXb0%2F9opE%3D

  2. Далее выполните URL-декодирование submittedHMAC. Будет получен следующий результат:

    AT55+2jLQeuigpg0xm/vn7tjpSGXBUfFe0UXb0/9opE=

  3. Затем следует вычислить localHMAC с помощью noHMACSWT и значения ключа HMAC, закодировать результат в формате base64. Будет получено следующее значение localHMAC:

    AT55+2jLQeuigpg0xm/vn7tjpSGXBUfFe0UXb0/9opE=

  4. Итогом сравнения submittedHMAC и localHMAC будет одна и та же строка. Затем для получения доступа к значениям SWT выполняется URL-декодирование noHMACSWT.

Имена атрибутов SWT

Зарезервированные имена

Следующие пары «имя-значение» являются необязательными. Они определены для упрощения взаимодействия в рамках некоторых распространенных сценариев.

Имя Синтаксис значения Семантика значения

Издатель

Строка в кодировке UTF-8

Определяет сторону, которая выдает SWT.

ExpiresOn

Строка ASCII, представляющая целое число (с основанием 10) без знака.

Определяет момент, когда SWT не следует принимать для дальнейшей обработки.

Дата и время окончания действия записываются в виде количества секунд, которое пройдет с 01.01.1970T0:0:0Z до момента истечения срока действия в формате UTC.

Аудитория

Строка в кодировке UTF-8

Определяет аудиторию SWT, для которой предназначен SWT. Цель заключается в том, что если потребитель SWT получает SWT со значением аудитории, которое не определяет аудиторию SWT, то SWT отклоняется.

Общедоступные имена

Для определения дополнительных атрибутов производитель SWT может использовать обратное DNS-имя или URI.

Закрытые имена

Производитель и потребитель SWT могут согласовать и принять любое имя атрибута, которое не является зарезервированным или общедоступным. Эти имена не должны входить в список зарезервированных имен, определенных в предыдущем разделе «Зарезервированные имена». В отличие от общедоступных имен, закрытые имена могут стать причиной возникновения конфликтов, поэтому их следует использовать с осторожностью.

См. также:

Основные понятия

Форматы токенов, поддерживаемые в ACS