Кеширование

Этот документ распространяется на следующие методы:

• API поиска (v4) : ThreatMatches.find
• Обновление API (v4) : fullHashes.find

О кэшировании

Чтобы уменьшить использование пропускной способности клиента и защитить Google от всплесков трафика, клиенты API поиска и API обновления должны создавать и поддерживать локальный кэш данных об угрозах. В API поиска кэш используется для уменьшения количества запросов threatMatches , которые клиенты отправляют в Google. В API обновления кеш используется для уменьшения количества запросов fullHashes , которые клиенты отправляют в Google. Протокол кэширования для каждого API описан ниже.

API поиска

Клиенты API поиска должны кэшировать каждый возвращаемый элемент ThreatMatch в течение периода, определенного его полем кэшДурион. Затем клиентам необходимо просмотреть кэш, прежде чем отправлять последующий запрос threatMatches на сервер. Если срок кэширования ранее возвращенного ThreatMatch еще не истек, клиент должен предположить, что элемент все еще небезопасен. Кэширование элементов ThreatMatch может сократить количество запросов API, выполняемых клиентом.

Пример: ThreatMatches.find

Нажмите на ссылки запроса и ответа в заголовке таблицы, чтобы просмотреть полные примеры.

"threatEntries": [
 {"url": "http://www.urltocheck.org/"}
]

"matches": [{
 "threat": {"url": "http://www.urltocheck.org/"},
 "cacheDuration": "300.000s"
}]

Обновить API

Чтобы уменьшить общее количество запросов fullHashes , отправляемых в Google с помощью API обновления, клиентам необходимо поддерживать локальный кеш. API устанавливает два типа кэширования: положительное и отрицательное.

Позитивное кеширование

Чтобы клиенты не могли повторно запрашивать состояние определенного небезопасного полного хэша, каждый возвращенный ThreatMatch содержит положительную продолжительность кэша (определяемую полем cacheDuration ), которая указывает, в течение какого времени полный хэш считается небезопасным.

Отрицательное кеширование

Чтобы клиенты не могли повторно запрашивать состояние конкретного безопасного полного хеша, каждый ответ fullHashes определяет отрицательную продолжительность кэша для запрошенного префикса (определяемую полем negativeCacheDuration ). Эта продолжительность указывает, как долго все полные хеши с запрошенным префиксом будут считаться безопасными для запрошенных списков, за исключением тех, которые возвращаются сервером как небезопасные. Такое кэширование особенно важно, поскольку оно предотвращает перегрузку трафика, которая может быть вызвана конфликтом хэш-префикса с безопасным URL-адресом, который получает большой трафик.

Консультация по кешу

Когда клиент хочет проверить состояние URL-адреса, он сначала вычисляет его полный хэш. Если префикс полного хеша присутствует в локальной базе данных, клиент должен затем просмотреть свой кеш, прежде чем отправлять запрос fullHashes на сервер.

Во-первых, клиенты должны проверить наличие положительного попадания в кэш. Если существует неистекшая положительная запись в кэше для полного интересующего хеша, ее следует считать небезопасной. Если срок действия положительной записи кэша истек, клиент должен отправить запрос fullHashes для соответствующего локального префикса. Согласно протоколу, если сервер возвращает полный хэш, это считается небезопасным; в противном случае это считается безопасным.

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

Обновление кеша

Кэш клиента должен обновляться каждый раз при получении ответа fullHashes . Положительная запись в кэше должна быть создана или обновлена ​​для полного хэша в поле cacheDuration . Отрицательная продолжительность кэша хеш-префикса также должна создаваться или обновляться в соответствии с полем negativeCacheDuration ответа.

Если последующий запрос fullHashes не возвращает полный хэш, который в данный момент положительно кэширован, клиенту не требуется удалять положительную запись кэша. На практике это не вызывает беспокойства, поскольку продолжительность положительного кэша обычно невелика (несколько минут), что позволяет быстро исправить ложные срабатывания.

Пример сценария

В следующем примере предположим, что h(url) — это хеш-префикс URL-адреса, а H(url) — это полный хэш URL-адреса. То есть h(url) = SHA256(url).substr(4), H(url) = SHA256(url).

Теперь предположим, что клиент (с пустым кешем) посещает example.com/ и видит, что h(example.com/) находится в локальной базе данных. Клиент запрашивает полноразмерные хэши для префикса хэша h(example.com/) и получает обратно полноразмерный хеш H(example.com/) вместе с положительной продолжительностью кэширования 5 минут и отрицательной продолжительностью кэширования 1 час. .

Положительная длительность кэша в 5 минут сообщает клиенту, как долго полноразмерный хэш H(example.com/) должен считаться небезопасным без отправки еще одного запроса fullHashes . Через 5 минут клиент должен отправить еще один запрос fullHashes для этого префикса h(example.com/), если клиент снова посетит example.com/. Клиент должен сбросить отрицательную длительность кэша хэш-префикса для каждого нового ответа.

Отрицательная продолжительность кэша, равная 1 часу, сообщает клиенту, как долго все остальные полноразмерные хеши, кроме H(example.com/), которые имеют тот же префикс h(example.com/), должны считаться безопасными. В течение 1 часа каждый URL-адрес, такой как h(URL) = h(example.com/), должен считаться безопасным и, следовательно, не приводить к запросу fullHashes (при условии, что H(URL) != H(example.com) /)).

Если ответ fullHashes содержит ноль совпадений и установлена ​​отрицательная длительность кэша, то клиент не должен выдавать какие-либо запросы fullHashes для любого из запрошенных префиксов в течение заданной отрицательной продолжительности кэша.

Если ответ fullHashes содержит одно или несколько совпадений, для всего ответа по-прежнему устанавливается отрицательная длительность кэша. В этом случае продолжительность кэширования одного полного хеша указывает, как долго этот конкретный полноразмерный хеш должен считаться клиентом небезопасным. По истечении срока действия кэша ThreatMatch клиент должен обновить полноразмерный хэш, выдав запрос fullHashes для этого префикса хэша, если запрошенный URL-адрес соответствует существующему полноразмерному хешу в кеше. В этом случае отрицательная длительность кэша не применяется. Отрицательная длительность кэша ответа применяется только к полноразмерным хешам, которые не присутствовали в ответе fullHashes . Для полноразмерных хешей, которые отсутствуют в ответе, клиент должен воздерживаться от выдачи каких-либо запросов fullHashes до тех пор, пока не истечет отрицательная длительность кэша.

Пример: fullHashes.find

Нажмите на ссылки запроса и ответа в заголовке таблицы, чтобы просмотреть полные примеры.

"threatEntries": [
  {"hash": "0xaaaaaaaa"}
]

"matches": [],
"negativeCacheDuration": "3600.000s"

"threatEntries": [
  {"hash": "0xbbbbbbbb"}
]

"matches": [
 "threat": {"hash": "0xbbbbbbbb0000..."}
 "cacheDuration": "600.000s",
],
"negativeCacheDuration": "300.000s"

"threatEntries": [
  {"hash": "0xcccccccc"}
]

"matches": [
 "threat": {"hash": "0xccccccccdddd..."},
 "cacheDuration": "600.000s"
],
"negativeCacheDuration": "3600.000s"