Аутентификация HMAC

Фреймворк RESTful API Elgg предоставляет функции для поддержки схемы подписи HMAC для аутентификации API. Клиент должен отправить подпись HMAC вместе с набором специальных заголовков HTTP при выполнении вызова, требующего аутентификации API. Это гарантирует, что вызов API выполняется от заявленного клиента и что данные не были изменены.

HMAC должен быть построен на основе следующих данных:

  • Публичный ключ API, идентифицирующий вас для сервера API Elgg, предоставленный плагином APIAdmin

  • Приватный ключ API, предоставленный Elgg (который является парным к публичному ключу)

  • Текущее время Unix в секундах

  • Nonce для гарантии того, что два запроса в одну и ту же секунду имеют разные подписи

  • URL-кодированное строковое представление любых параметров переменных GET, например, method=test.test&foo=bar

  • Если вы отправляете POST-данные, хеш этих данных

Некоторая дополнительная информация должна быть добавлена в заголовок HTTP для того, чтобы эти данные были правильно обработаны:

  • X-Elgg-apikey — публичный ключ API

  • X-Elgg-time — время Unix, использованное в расчёте HMAC

  • X-Elgg-nonce — случайная строка

  • X-Elgg-hmac — HMAC в кодировке base64

  • X-Elgg-hmac-algo — алгоритм, использованный в расчёте HMAC

Если вы отправляете POST-данные, вы также должны отправить:

  • X-Elgg-posthash — хеш POST-данных

  • X-Elgg-posthash-algo — алгоритм, использованный для получения хеша POST-данных

  • Content-type — тип содержимого отправляемых вами данных (это может быть application/x-www-form-urlencoded или multipart/form-data)

  • Content-Length — длина ваших POST-данных в байтах

Elgg предоставляет образец клиента API, реализующего эту подпись HMAC: \Elgg\WebServices\ElggApiClient. Он служит хорошим справочником по её реализации.

Поддерживаемые алгоритмы хеширования

  • sha256: рекомендуется

  • sha1: быстро, однако менее безопасно

  • md5: слабый и будет удалён в будущем

Расчёт хеша POST

При отправке POST-данных как Content-Type: application/x-www-form-urlencoded; хеш post должен быть рассчитан по всем post-данным с использованием одного из поддерживаемых алгоритмов хеширования.

При отправке POST-данных как Content-Type: multipart/form-data; хеш post должен быть рассчитан по пустой строке.

Результат хеширования должен быть указан в заголовке X-Elgg-posthash, а использованный алгоритм хеширования должен быть указан в заголовке X-Elgg-posthash-algo.

Предупреждение

Поскольку хеш POST не рассчитывается при использовании Content-Type: multipart/form-data;, используйте это только при вызове API, требующих ввод файла.

Расчёт хеша HMAC

Общий HMAC должен быть рассчитан на основе следующих данных (по порядку) с использованием секрета API в качестве секрета HMAC и с одним из поддерживаемых алгоритмов хеширования:

  1. метка времени UNIX, укажите эту метку времени в заголовке X-Elgg-time

  2. случайная строка, укажите эту строку в заголовке X-Elgg-nonce

  3. публичный ключ API, укажите этот ключ API в заголовке X-Elgg-apikey

  4. строка запроса URL (например, method=test.test&foo=bar)

  5. когда запрос является POST, добавьте posthash, как указано в заголовке X-Elgg-posthash

Полученная строка должна быть закодирована в base64, затем закодирована в URL и указана в заголовке X-Elgg-hmac. Использованный алгоритм хеширования должен быть указан в X-Elgg-hmac-algo.

Кеш хеширования

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