Введение

Ошибка аутентификации при обращении к API пула ViaBTC сама по себе не является доказательством того, что API-ключ был отозван или скомпрометирован. Документация API ViaBTC разделяет несколько отдельных причин неудачного аутентифицированного запроса — недействительный API-ключ, ошибку подписи, недействительный параметр метки времени и IP-адрес, отсутствующий в белом списке аккаунта. Эти условия имеют отдельные задокументированные коды ошибок. Недействительный API-ключ и ошибка подписи требуют разных проверок, однако неверный или несовпадающий секретный ключ также может стать причиной ошибки подписи. Сброс или удаление учётных данных до выяснения того, какое именно условие применимо, может нарушить работающую интеграцию, не устранив при этом саму причину проблемы с настройками.

Начните с проверки возвращённого кода ошибки: проверьте API-ключ при коде 12001, подпись и соответствие секретного ключа при коде 12002, метку времени при коде 12003 и белый список IP-адресов при коде 12004. Если вы подозреваете, что учётные данные были скомпрометированы, незамедлительно замените или удалите затронутые учётные данные, не дожидаясь завершения рутинной диагностики.

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

Учётные данные API — это не учётные данные майнинг-воркера

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

API-ключ ViaBTC и парный ему секретный ключ используются внешним приложением — скриптом мониторинга, дашбордом или инструментом учёта — для запроса данных уровня аккаунта, таких как балансы или статистика хешрейта, через API пула. Они вводятся в настройки этого приложения, а не в майнинговое оборудование.

ASIC-устройства и майнинговое ПО вместо этого подключаются к пулу с помощью Stratum-адреса и имени воркера, следуя стандартному потоку майнинг-протокола, в рамках которого майнер отправляет пулу доли (shares) в качестве доказательства выполненной работы. Это подключение вообще не использует API-ключ или секретный ключ. Если майнер перестал отправлять доли или дашборд показывает устаревшие данные о хешрейте, первым делом нужно выяснить, какая именно из этих двух систем фактически даёт сбой, поскольку шаги диагностики для каждой из них никак не связаны между собой.

Как ViaBTC проверяет запрос к API

Согласно опубликованным ViaBTC требованиям к аутентификации API, запрос может быть отклонён по одной из четырёх отдельных причин, причём не каждая конечная точка проверяет их все одинаковым образом.

Для аккаунта должен быть настроен белый список IP-адресов, и исходный адрес запроса должен присутствовать в нём; эта проверка применяется независимо от того, требует ли конечная точка подписи. Заголовок X-API-KEY должен содержать значение, принадлежащее запрашиваемому аккаунту или субаккаунту. Для конечных точек, для которых документально предусмотрено требование подписи, запрос должен включать заголовок X-SIGNATURE, вычисленный с помощью HMAC-SHA256 с использованием секретного ключа, парного данному API-ключу — рассчитанный на основе строки запроса для запросов GET и DELETE либо на основе тела запроса в формате JSON для запросов POST и PUT. Подписанные запросы должны включать параметр tonce, определяемый как текущая метка времени в миллисекундах, формируемая непосредственно перед созданием подписи.

Каждый аккаунт и субаккаунт имеет собственный API-ключ и секретный ключ. В документации ViaBTC также отмечается, что субаккаунт использует белый список IP-адресов основного аккаунта только в том случае, если собственный белый список субаккаунта не настроен — не утверждается, что это наследование применяется безусловно, поэтому при управлении несколькими субаккаунтами необходимо подтвердить, какой именно белый список фактически действует для того субаккаунта, который выдаёт ошибку.

Чтение кода ошибки перед принятием мер

Ответы API ViaBTC возвращаются в формате JSON с полем code, указывающим на успех или неудачу, и полем message, описывающим результат. Значение 0 означает успех; любое другое значение соответствует задокументированной ошибке. В справочнике кодов ошибок API ViaBTC перечислены четыре кода, относящиеся к аутентификации:

Используйте код ошибки, чтобы выбрать следующую проверку, а не чтобы исключить все остальные возможные проблемы. Для 12001 проверьте отправляемый API-ключ и убедитесь, что интеграция использует учётные данные нужного аккаунта. Для 12002 проверьте и парный секретный ключ, и построение подписи. Замена учётных данных обычно не требуется при ошибках, связанных с меткой времени или белым списком, поскольку она не устраняет эти настройки.

Диагностический чек-лист перед сбросом учётных данных

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

1. Зафиксируйте точные значения code и message из ответа. Сохраните тело ответа в формате JSON (предварительно скрыв секретный ключ перед тем, как делиться им где-либо), а не полагайтесь на обобщённое сообщение «ошибка аутентификации» от уровня приложения, которое может объединять несколько возможных причин.

2. Убедитесь, требует ли эндпоинт подписи. В справочнике API ViaBTC для каждого эндпоинта указано, требуется ли подпись. Например, эндпоинт account-hashrate документирован как GET-запрос, которому нужны только параметр coin и X-API-KEY, без подписи. Если такой запрос выполняется успешно, а подписанный запрос с тем же API-ключом и тем же исходящим IP завершается ошибкой 12002 или 12003, в первую очередь проверьте соответствие секретного ключа, построение подписи и формирование временной метки. Успешный запрос подтверждает только условия аутентификации именно этого запроса. При других кодах ошибок руководствуйтесь конкретным сообщением об ошибке, а не предположением о проблеме с подписью или временной меткой.

3. Сравните исходный IP-адрес запроса со списком разрешённых адресов (whitelist). Скрипт, который продолжает корректно работать после миграции сервера, смены региона облака или установки нового NAT-шлюза, всё равно может завершиться ошибкой 12004, если его исходящий IP-адрес изменился, а белый список не был обновлён. Это распространённая и легко упускаемая причина, поскольку API-ключ и секретный ключ при такой инфраструктурной смене не затрагиваются.

4. Проверьте, что API-ключ и секретный ключ относятся к одному и тому же аккаунту или субаккаунту. Поскольку каждый аккаунт и субаккаунт имеет собственную пару ключей, интеграция, отслеживающая несколько субаккаунтов, может по ошибке сопоставить API-ключ одного аккаунта с секретным ключом другого, особенно после предыдущего сброса ключа. Это приводит к ошибке подписи, даже если оба значения по отдельности являются действительными учётными данными.

5. Пересоберите подпись из тех самых данных, которые фактически передаются. Подпись HMAC-SHA256 должна рассчитываться из той же строки запроса или тела JSON, которые отправляются по сети. Если промежуточное ПО запроса, библиотека сериализации или прокси-сервер изменяют порядок параметров, кодировку или добавляют поля после того, как подпись уже была сгенерирована, сервер вычислит подпись, отличную от клиентской, и вернёт 12002. Решение в данном случае — проверить конвейер формирования запроса, а не предполагать, что секретный ключ неверен.

6. Проверьте синхронизацию системных часов и единицы измерения временной метки. Параметр tonce должен быть текущей временной меткой, выраженной в миллисекундах. Десятизначное значение в секундах, временная метка, сформированная задолго до фактической отправки запроса, или рассинхронизация системных часов — всё это может привести к ошибке 12003. Ни одна из этих проблем не устраняется заменой пары ключей.

Если нет подозрений на компрометацию учётных данных, выполните проверки, относящиеся к конкретной сообщённой ошибке, прежде чем заменять учётные данные. Замена может быть уместна, если ошибка 12001 сохраняется после проверки передаваемого ключа, или если верный секретный ключ невозможно восстановить для подписанных запросов. Подозрение на компрометацию требует незамедлительной ротации или удаления ключа без ожидания прохождения этого контрольного списка.

Когда замена пары ключей является правильным решением

Руководство ViaBTC по настройке API описывает варианты сброса пары API-ключ/секретный ключ или её удаления; удаление требует подтверждения по электронной почте и кода Google Authenticator. Сброс или удаление учётных данных — разумная реакция в ряде конкретных ситуаций:

• Ошибка 12001 сохраняется после подтверждения того, что в запросе отправляется правильный ключ для правильного аккаунта или субаккаунта.
• Секретный ключ был утерян или никогда не был сохранён, из-за чего невозможно восстановить подписанную интеграцию.
• Интеграция или стороннее приложение выведены из эксплуатации и больше не нуждаются в доступе.
• Есть какие-либо основания подозревать, что ключ или секретный ключ были скомпрометированы — например, вставлены в публичный репозиторий, попали на скриншот, в журнал чата или в заявку в службу поддержки.

Именно в случае компрометации незамедлительная ротация или удаление ключа уместны без длительной диагностики, поскольку риск от продолжения использования перевешивает ценность выяснения причины исходной ошибки. ViaBTC рекомендует держать в тайне как API-ключ, так и секретный ключ, и это касается всего процесса диагностики — ни одно из этих значений не должно передаваться в запросе в службу поддержки, в сообщении на форуме или в файле журнала. В белый список для одного аккаунта можно внести до 20 IP-адресов, по одному на строку, чего, как правило, достаточно для покрытия небольшого числа серверов приложений без необходимости ослаблять белый список в качестве обходного решения.

Часто задаваемые вопросы

Нужно ли вводить API-ключ в настройках моего ASIC-устройства?

Нет. API-ключ и секретный ключ используются для аутентификации запросов к API пула ViaBTC со стороны внешнего приложения. ASIC-устройства и программное обеспечение для майнинга подключаются к пулу через Stratum-адрес (URL) и имя воркера — это отдельная система учётных данных.

Мой API-ключ верен, так почему же запрос завершается ошибкой «IP not allowed»?

API ViaBTC проверяет исходный IP-адрес запроса по настроенному белому списку аккаунта независимо от того, действителен ли сам API-ключ. Верный ключ, отправленный с адреса, которого нет в белом списке, всё равно вернёт ошибку 12004.

Почему один эндпоинт возвращает ошибку подписи, а другой нормально работает с тем же ключом?

Не все эндпоинты ViaBTC требуют подписи. Эндпоинт без подписи может успешно выполняться без X-SIGNATURE, если выполнены его прочие требования. Если эндпоинт, требующий подписи, возвращает 12002 при использовании того же API-ключа и того же исходящего IP, проверьте, что секретный ключ сопоставлен именно с этим API-ключом и что подпись рассчитывается из фактически передаваемых данных запроса.

Следует ли сбрасывать API-ключ после получения ошибки недействительного tonce?

Нет, не в качестве первого шага. Ошибка 12003 указывает на проблему с параметром временной метки, а не с ключом. Прежде чем рассматривать какую-либо замену учётных данных, проверьте синхронизацию системных часов и убедитесь, что tonce отправляется как текущая временная метка в миллисекундах, а не в секундах.

Источники

• ViaBTC Pool API, "API Authentication", GitHub wiki.
• ViaBTC Pool API, "Error Code", GitHub wiki.
• ViaBTC Pool API, "Acquire Account Hashrate", GitHub wiki.
• ViaBTC Help Center, "What is API and How to Set Up".