Migration From V4

Google Safe Browsing v5가 v4 (특히 v4 업데이트 API)에 비해 크게 개선된 점은 데이터 업데이트 빈도와 적용 범위입니다. 보호는 클라이언트에서 유지관리하는 로컬 데이터베이스에 크게 의존하므로 로컬 데이터베이스 업데이트의 지연과 크기가 보호 누락의 주요 원인입니다. 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. Rice-Golomb 인코딩된 해시를 디코딩하는 로직에는 다음 두 가지 주요 조정이 필요합니다.
    • 엔디언 및 정렬: v4에서는 반환된 해시가 리틀 엔디언 값으로 정렬되었습니다. v5에서는 빅엔디언 값으로 처리됩니다. 바이트 문자열의 사전순 정렬은 빅엔디언 값의 숫자 정렬과 동일하므로 클라이언트가 더 이상 특별한 정렬 단계를 실행할 필요가 없습니다. Chromium v4 구현의 경우와 같은 맞춤 리틀 엔디언 정렬은 이전에 구현된 경우 삭제할 수 있습니다.
    • 가변 해시 길이: 디코딩 알고리즘은 v4에서 사용된 4바이트 해시 길이뿐만 아니라 HashList.compressed_additions 필드에서 반환될 수 있는 다양한 해시 길이를 지원하도록 업데이트해야 합니다. 대답에 반환된 해시의 길이는 hashLists.list에서 반환된 HashList.metadata.hash_length에 따라 결정될 수 있습니다. 또는 요청된 해시 목록의 이름은 목록에서 반환될 것으로 예상되는 해시 크기를 나타냅니다. 해시 목록에 대한 자세한 내용은 로컬 데이터베이스 페이지를 참고하세요.

해시 검색 변환

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. 캐싱이 단일 캐시 기간으로 단순화되었습니다. 캐시와 상호작용하는 방법은 위의 절차를 참고하세요.