캐싱

이 문서는 다음 메서드에 적용됩니다.

• Lookup API: uris.search
• Update API: hashes.search

캐싱 정보

클라이언트 대역폭 사용량을 줄이고 트래픽 급증으로부터 Google을 보호하려면 Lookup API와 Update API의 클라이언트 모두 위협 데이터의 로컬 캐시를 만들고 유지해야 합니다. Lookup API는 캐시를 사용하여 클라이언트가 Google에 보내는 uris.search 요청 수를 줄입니다. Update API의 경우 캐시를 사용하여 클라이언트가 Google에 보내는 hashes.search 요청 수를 줄입니다. 다음은 각 API의 캐싱 프로토콜에 대한 설명입니다.

Lookup API

Lookup API의 클라이언트는 expireTime 필드에 정의된 시간까지 반환된 각 ThreatUrl 항목을 캐시해야 합니다. 그런 다음 클라이언트는 서버에 후속 uris.search 요청을 하기 전에 캐시를 참조해야 합니다. 이전에 반환된 ThreatUrl의 캐시 항목이 아직 만료되지 않은 경우 클라이언트는 항목이 여전히 안전하지 않다고 가정해야 합니다. ThreatUrl 항목을 캐시하면 클라이언트의 API 요청 수가 줄어들 수 있습니다.

Update API

Update API를 사용하여 Google에 전송되는 전체 hashes.search 요청 수를 줄이려면 클라이언트가 로컬 캐시를 유지관리해야 합니다. API는 양성 및 음성의 두 가지 유형의 캐싱을 만듭니다.

양성 캐싱

클라이언트가 특정한 안전하지 않은 전체 해시의 상태를 반복적으로 요청하지 않도록 반환된 각 ThreatHash에는 양성 캐시 시간(expireTime 필드로 정의)이 포함됩니다. 전체 해시는 이 시간까지는 안전하지 않은 것으로 간주될 수 있습니다.

음성 캐싱

클라이언트가 특정한 안전한 전체 해시의 상태를 반복적으로 요청하지 않도록 응답은 요청된 프리픽스(negativeExpireTime 필드로 정의)의 음성 캐시 기간을 정의합니다. 요청된 프리픽스가 있는 모든 전체 해시는 이 시간까지는 요청된 위협 유형에 대해 안전하다고 간주됩니다(서버에서 안전하지 않은 것으로 반환된 것은 제외). 이 캐싱은 대량의 트래픽을 수신하는 안전한 URL과 해시 프리픽스 충돌로 인해 발생할 수 있는 트래픽 과부하를 방지하기 때문에 특히 중요합니다.

캐시 참조

클라이언트는 URL의 상태를 확인하려고 하는 경우 먼저 전체 해시를 계산합니다. 전체 해시의 프리픽스가 로컬 데이터베이스에 있으면 클라이언트는 서버에 hashes.search 요청을 보내기 전에 캐시를 참조해야 합니다.

먼저 클라이언트는 캐시 적중을 확인해야 합니다. 대상의 전체 해시에 대해 만료되지 않은 양성 캐시 항목이 있으면 안전하지 않은 것으로 간주해야 합니다. 양성 캐시 항목이 만료되었으면 클라이언트는 연결된 로컬 프리픽스에 대해 hashes.search 요청을 보내야 합니다. 프로토콜별로 서버가 전체 해시를 반환하면 안전하지 않은 것으로 간주되고, 그렇지 않으면 안전하다고 간주됩니다.

전체 해시에 대해 양성 캐시 항목이 없으면 클라이언트는 음성 캐시 적중을 확인해야 합니다. 연결된 로컬 프리픽스에 대해 만료되지 않은 음성 캐시 항목이 있으면 전체 해시가 안전하다고 간주됩니다. 음성 캐시 항목이 만료되었거나 존재하지 않으면 클라이언트는 연결된 로컬 프리픽스에 대해 hashes.search 요청을 보내고 응답을 정상적으로 해석해야 합니다.

캐시 업데이트

hashes.search 응답이 수신될 때마다 클라이언트 캐시를 업데이트해야 합니다. expireTime 필드에 따라 전체 해시에 대해 양성 캐시 항목을 만들거나 업데이트해야 합니다. 해시 프리픽스의 음성 캐시 기간도 응답의 negativeExpireTime 필드에 따라 만들거나 업데이트해야 합니다.

후속 hashes.search 요청이 현재 양성으로 캐시된 전체 해시를 반환하지 않는 경우 클라이언트는 양성 캐시 항목을 삭제할 필요가 없습니다. 양성 캐시 기간은 일반적으로 짧아서(몇 분) 거짓양성을 신속하게 수정할 수 있으므로 실제로는 걱정하지 않아도 됩니다.

예시 시나리오

다음 예시에서는 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/)가 또 다른 hashes.search 요청을 전송하는 것 없이 안전하지 않은 것으로 간주하는 기간을 클라이언트에게 알려줍니다. 5분 후에 클라이언트가 example.com/을 다시 방문하면 해당 프리픽스 h(example.com/)에 대해 다른 hashes.search 요청을 실행해야 합니다. 클라이언트는 새 응답에 따라 해시 프리픽스의 음성 캐시 만료 시간을 재설정해야 합니다.

1시간의 음성 캐시 기간은 h(example.com/)의 동일한 프리픽스를 공유하는 H(example.com/) 이외의 다른 모든 전체 길이 해시를 안전한 것으로 간주하는 기간을 클라이언트에 알려줍니다. 1시간 동안 h(URL) = h(example.com/)과 같은 모든 URL은 안전하다고 간주하므로 hashes.search 요청을 보내지 않습니다(H(URL) != H(example.com/)이라고 가정).

fullHashes 응답에 일치 항목이 0이고 음성 캐시 만료 시간이 설정되어 있으면 클라이언트는 지정된 음성 캐시 시간 동안 요청된 모든 프리픽스에 대해 hashes.search 요청을 실행해서는 안 됩니다.

hashes.search 응답에 일치 항목이 하나 이상 포함되어 있으면 전체 응답에 대해 음성 캐시 만료 시간이 계속 설정됩니다. 이 경우 단일 전체 해시의 캐시 만료 시간은 클라이언트가 특정 전체 길이 해시가 안전하지 않다고 가정해야 하는 기간을 나타냅니다. ThreatHash 캐시 기간이 경과한 후 요청된 URL이 캐시의 기존 전체 길이 해시와 일치하면 클라이언트는 해당 해시 프리픽스에 대한 hashes.search 요청을 실행하여 전체 길이 해시를 새로고침해야 합니다. 이 경우 음성 캐시 기간은 적용되지 않습니다. 응답의 음성 캐시 기간은 hashes.search 응답에 없는 전체 길이 해시에만 적용됩니다. 응답에 없는 전체 길이 해시의 경우 클라이언트는 음성 캐시 기간이 경과할 때까지 hashes.search 요청을 실행하지 않아야 합니다.