Migration From V4

Google 세이프 브라우징 v5 (특히 v4 Update API)는 v4에 비해 데이터 최신성 및 적용 범위가 크게 개선되었습니다. 보호는 클라이언트가 유지 관리하는 로컬 데이터베이스에 크게 의존하므로 로컬 데이터베이스 업데이트의 지연 및 크기가 보호 누락의 주요 원인입니다. v4에서는 일반적인 클라이언트가 최신 버전의 위협 목록을 가져오는 데 20~50분이 걸립니다. 안타깝게도 피싱 공격은 빠르게 확산됩니다. 2021년 기준, 공격을 실행하는 사이트의 60% 가 10분 미만 동안 운영됩니다. Google의 분석에 따르면 피싱 보호 누락의 약 25~30% 가 이러한 데이터 비활성 상태로 인한 것으로 나타났습니다. 또한 일부 기기는 시간이 지남에 따라 계속 늘어나는 Google 세이프 브라우징 위협 목록 전체를 관리할 수 없습니다.

현재 v4 Update API를 사용 중인 경우 로컬 데이터베이스를 재설정하거나 삭제하지 않고도 v4에서 v5로 원활하게 이전할 수 있습니다. 이 섹션에서는 이를 수행하는 방법을 설명합니다.

목록 업데이트 변환

목록이 위협 유형, 플랫폼 유형, 위협 항목 유형의 튜플로 식별되는 V4와 달리 v5에서는 목록이 이름으로 간단히 식별됩니다. 이렇게 하면 여러 v5 목록에서 동일한 위협 유형을 공유할 수 있는 유연성이 제공됩니다. v5에서는 플랫폼 유형 및 위협 항목 유형이 삭제됩니다.

v4에서는 threatListUpdates.fetch 메서드를 사용하여 목록을 다운로드합니다. v5에서는 hashLists.batchGet 메서드로 전환합니다.

요청을 다음과 같이 변경해야 합니다.

  1. v4 ClientInfo 객체를 모두 삭제합니다. 전용 필드를 사용하여 클라이언트의 식별 정보를 제공하는 대신 잘 알려진 User-Agent 헤더를 사용하세요. 이 헤더에 클라이언트 식별자를 제공하는 지정된 형식은 없지만 원래 클라이언트 ID와 클라이언트 버전을 공백 문자 또는 슬래시 문자로 구분하여 포함하는 것이 좋습니다.
  2. 각 v4 ListUpdateRequest 객체의 경우: * 위의 표에서 해당하는 v5 목록 이름을 찾아 v5 요청에 해당 이름을 제공합니다.
    • threat_entry_type 또는 platform_type와 같이 불필요한 필드를 삭제합니다.
    • v4의 state 필드는 v5 versions 필드와 직접 호환됩니다. v4에서 state 필드를 사용하여 서버로 전송되는 것과 동일한 바이트 문자열은 v5에서 versions 필드를 사용하여 간단히 전송할 수 있습니다.
    • v4 제약 조건의 경우 v5는 SizeConstraints라는 단순화된 버전을 사용합니다. region와 같은 추가 필드는 삭제해야 합니다.

응답을 다음과 같이 변경해야 합니다.

  1. v4 enum ResponseType는 partial_update라는 불리언 필드로 대체됩니다.
  2. 이제 minimum_wait_duration 필드를 0으로 설정하거나 생략할 수 있습니다. 그렇다면 클라이언트는 즉시 다른 요청을 해야 합니다. 이는 클라이언트가 SizeConstraints에서 최대 업데이트 크기에 최대 데이터베이스 크기보다 작은 제약 조건을 지정하는 경우에만 발생합니다.
  3. 32비트 정수용 Rice 디코딩 알고리즘을 조정해야 합니다. 차이점은 인코딩된 데이터가 다른 엔디언으로 인코딩된다는 점입니다. v4와 v5 모두 32비트 해시 접두사는 사전순으로 정렬됩니다. 하지만 v4에서는 이러한 접두사가 정렬될 때 리틀 엔디안으로 취급되는 반면 v5에서는 정렬될 때 빅 엔디안으로 취급됩니다. 즉, 사전순 정렬은 빅엔디언을 사용한 숫자 정렬과 동일하므로 클라이언트는 정렬을 수행할 필요가 없습니다. v4의 Chromium 구현에서 이러한 종류의 예는 여기에서 확인할 수 있습니다. 이러한 정렬은 삭제할 수 있습니다.
  4. Rice 디코딩 알고리즘은 다른 해시 길이에도 구현되어야 합니다.

해시 검색 변환

v4에서는 fullHashes.find 메서드를 사용하여 전체 해시를 가져옵니다. v5의 상응하는 메서드는 hashes.search 메서드입니다.

요청을 다음과 같이 변경해야 합니다.

  1. 길이가 정확히 4바이트인 해시 접두사만 전송하도록 코드를 구성합니다.
  2. v4 ClientInfo 객체를 모두 삭제합니다. 전용 필드를 사용하여 클라이언트의 식별 정보를 제공하는 대신 잘 알려진 User-Agent 헤더를 사용하세요. 이 헤더에 클라이언트 식별자를 제공하는 지정된 형식은 없지만 원래 클라이언트 ID와 클라이언트 버전을 공백 문자 또는 슬래시 문자로 구분하여 포함하는 것이 좋습니다.
  3. client_states 필드를 삭제합니다. 더 이상 필요하지 않습니다.
  4. threat_types 및 유사한 필드를 더 이상 포함할 필요가 없습니다.

응답을 다음과 같이 변경해야 합니다.

  1. minimum_wait_duration 필드가 삭제되었습니다. 클라이언트는 필요에 따라 언제든지 새 요청을 보낼 수 있습니다.
  2. v4 ThreatMatch 객체가 FullHash 객체로 간소화되었습니다.
  3. 캐싱이 단일 캐시 기간으로 단순화되었습니다. 캐시와 상호작용하는 방법은 위의 절차를 참고하세요.