Indice
SafeBrowsing(interfaccia)BatchGetHashListsRequest(messaggio)BatchGetHashListsResponse(messaggio)FullHash(messaggio)FullHash.FullHashDetail(messaggio)GetHashListRequest(messaggio)HashList(messaggio)HashListMetadata(messaggio)HashListMetadata.HashLength(enum)LikelySafeType(enum)ListHashListsRequest(messaggio)ListHashListsResponse(messaggio)RiceDeltaEncoded128Bit(messaggio)RiceDeltaEncoded256Bit(messaggio)RiceDeltaEncoded32Bit(messaggio)RiceDeltaEncoded64Bit(messaggio)SearchHashesRequest(messaggio)SearchHashesResponse(messaggio)SizeConstraints(messaggio)ThreatAttribute(enum)ThreatType(enum)
SafeBrowsing
Le API Navigazione sicura consentono ai client di verificare le risorse web (solitamente gli URL) rispetto agli elenchi costantemente aggiornati di risorse web non sicure di Google.
| BatchGetHashLists |
|---|
|
Ricevi più elenchi di hash contemporaneamente. È molto comune che un cliente debba ottenere più elenchi di hash. L'utilizzo di questo metodo è preferibile all'utilizzo ripetuto del metodo Get standard. Si tratta di un metodo Get batch standard come definito da https://google.aip.dev/231 e il metodo HTTP è anche GET. |
| GetHashList |
|---|
|
Recupera i contenuti più recenti di un elenco di hash. Un elenco di hash può essere un elenco di minacce o un elenco di non minacce, come la cache globale. Si tratta di un metodo Get standard come definito da https://google.aip.dev/131 e il metodo HTTP è anche GET. |
| ListHashLists |
|---|
|
Elenca gli elenchi di hash. Nell'API V5, Google non rimuoverà mai un elenco di hash restituito da questo metodo. In questo modo i client possono saltare l'utilizzo di questo metodo e codificare semplicemente tutti gli elenchi di hash di cui hanno bisogno. Si tratta di un metodo List standard come definito da https://google.aip.dev/132 e il metodo HTTP è GET. |
| SearchHashes |
|---|
|
Cerca gli hash completi corrispondenti ai prefissi specificati. Si tratta di un metodo personalizzato come definito da https://google.aip.dev/136 (il metodo personalizzato si riferisce a questo metodo che ha un nome personalizzato all'interno della nomenclatura generale di sviluppo dell'API di Google; non si riferisce all'utilizzo di un metodo HTTP personalizzato). |
BatchGetHashListsRequest
La richiesta di ottenere più elenchi di hash contemporaneamente.
| Campi | |
|---|---|
names[] |
Obbligatorio. I nomi dei singoli elenchi di hash. L'elenco POTREBBE essere un elenco di minacce o la cache globale. I nomi NON DEVONO contenere duplicati. In caso contrario, il cliente riceverà un errore. |
version[] |
Le versioni dell'elenco di hash già in possesso del client. Se è la prima volta che il client recupera gli elenchi di hash, il campo deve essere lasciato vuoto. In caso contrario, il client deve fornire le versioni ricevute in precedenza dal server. Il client NON DEVE manipolare questi byte. Il cliente non deve inviare le versioni nello stesso ordine dei nomi degli elenchi corrispondenti. Il cliente può inviare in una richiesta meno o più versioni rispetto al numero di nomi. Tuttavia, il client NON DEVE inviare più versioni corrispondenti allo stesso nome, altrimenti riceverà un errore. Nota storica: nella versione 4 dell'API, questo valore si chiamava |
desired_hash_length |
La lunghezza in byte del prefisso dell'hash desiderato degli hash restituiti. Il server restituirà quindi tutti i prefissi degli hash di questa lunghezza specificata. Elenchi di hash diversi hanno requisiti diversi per i valori accettabili del campo In particolare, per |
size_constraints |
I limiti di dimensione per ogni elenco. Se omesso, non ci sono vincoli. Tieni presente che le dimensioni riportate si riferiscono a ciascun elenco e non sono aggregate in tutti gli elenchi. |
BatchGetHashListsResponse
La risposta contenente più elenchi di hash.
| Campi | |
|---|---|
hash_lists[] |
Gli hash sono elencati nello stesso ordine indicato nella richiesta. |
FullHash
L'hash completo identificato con una o più corrispondenze.
| Campi | |
|---|---|
full_hash |
L'hash completo corrispondente. Si tratta dell'hash SHA256. La lunghezza sarà esattamente di 32 byte. |
full_hash_details[] |
Elenco non ordinato. Un campo ripetuto che identifica i dettagli pertinenti a questo hash completo. |
FullHashDetail
Dettagli su un hash completo corrispondente.
Una nota importante sulla compatibilità futura: il server può aggiungere nuovi tipi di minacce e attributi delle minacce in qualsiasi momento; queste aggiunte sono considerate modifiche minori alla versione. È norma di Google non esporre i numeri delle versioni secondarie nelle API (consulta https://cloud.google.com/apis/design/versioning per le norme relative al controllo delle versioni), pertanto i client DEVONO essere preparati a ricevere messaggi FullHashDetail contenenti valori enumerati ThreatType o ThreatAttribute considerati non validi dal client. Pertanto, è responsabilità del cliente verificare la validità di tutti i valori enumerati ThreatType e ThreatAttribute. Se un valore è considerato non valido, il cliente DEVE ignorare l'intero messaggio FullHashDetail.
| Campi | |
|---|---|
threat_type |
Il tipo di minaccia. Questo campo non sarà mai vuoto. |
attributes[] |
Elenco non ordinato. Attributi aggiuntivi relativi a questi hash completi. Questo campo può essere vuoto. |
GetHashListRequest
Una richiesta di ottenebrare un elenco di hash, che può essere un elenco di minacce o un elenco di non minacce come la cache globale.
Novità della versione 5: l'elemento precedentemente denominato states nella versione 4 è stato rinominato version per maggiore chiarezza. Gli elenchi ora sono denominati, i tipi di piattaforma e i tipi di voci di minaccia sono stati rimossi. Ora è possibile che più elenchi abbiano lo stesso tipo di minaccia o che un singolo elenco riguardi più tipi di minacce. I client hanno ora la possibilità di specificare la lunghezza dell'hash desiderata. Questa è parte della risposta ai prefissi degli hash di lunghezza variabile della versione 4 che hanno causato problemi in molte implementazioni dei client: ora tutti gli hash in un elenco hanno una sola lunghezza, il che consente implementazioni dei client molto più efficienti. I vincoli sono stati semplificati e il tipo di compressione è stato rimosso (la compressione viene sempre applicata).
| Campi | |
|---|---|
name |
Obbligatorio. Il nome di questo elenco di hash specifico. Potrebbe trattarsi di un elenco di minacce o della cache globale. |
version |
La versione dell'elenco di hash già in possesso del client. Se è la prima volta che il client recupera l'elenco di hash, questo campo DEVE essere lasciato vuoto. In caso contrario, il client DEVE fornire la versione precedentemente ricevuta dal server. Il client NON DEVE manipolare questi byte. Novità della versione 5: nella versione 4 dell'API, questo parametro si chiamava |
desired_hash_length |
La lunghezza in byte del prefisso dell'hash desiderato degli hash restituiti. Il server restituirà quindi tutti i prefissi degli hash di questa lunghezza specificata. Elenchi di hash diversi hanno requisiti diversi per i valori accettabili del campo |
size_constraints |
I vincoli di dimensioni dell'elenco. Se omesso, non ci sono vincoli. I vincoli sono consigliati su tutti i dispositivi con potenza di elaborazione, larghezza di banda o spazio di archiviazione limitati. |
HashList
Un elenco di hash identificati dal nome.
| Campi | |
|---|---|
name |
Il nome dell'elenco di hash. Tieni presente che anche la cache globale è solo un elenco di hash e può essere richiamata qui. |
version |
La versione dell'elenco di hash. Il client NON DEVE manipolare questi byte. |
partial_update |
Se il valore è true, si tratta di una differenza parziale contenente aggiunte e rimozioni in base a ciò che il cliente ha già. Se è false, si tratta dell'elenco completo degli hash. Se è false, il client DEVE eliminare qualsiasi versione archiviata localmente per questo elenco di hash. Ciò significa che la versione in possesso del cliente è molto obsoleta o che si ritiene che i dati del cliente siano danneggiati. Il campo Se true, il client DEVE applicare un aggiornamento incrementale applicando le rimozioni e poi le aggiunte. |
compressed_removals |
La versione codificata Rice-delta degli indici di rimozione. Poiché ogni elenco di hash ha sicuramente meno di 2^32 voci, gli indici vengono trattati come interi a 32 bit e codificati. |
minimum_wait_duration |
I client devono attendere almeno questo tempo per ricevere di nuovo l'elenco di hash. Se omesso o pari a zero, i client DEVONO eseguire il recupero immediatamente perché indica che il server ha un aggiornamento aggiuntivo da inviare al client, ma non può farlo a causa delle limitazioni specificate dal client. |
sha256_checksum |
L'elenco ordinato di tutti gli hash, sottoposti nuovamente ad hashing con SHA256. Si tratta del checksum dell'elenco ordinato di tutti gli hash presenti nel database dopo l'applicazione dell'aggiornamento fornito. Se non sono stati forniti aggiornamenti, il server omette questo campo per indicare che il client deve utilizzare il checksum esistente. |
metadata |
Metadati relativi all'elenco di hash. Questo valore non viene compilato dal metodo |
Campo unione compressed_additions. La versione con codifica Rice-delta degli aggiunti. Le lunghezze dei prefissi degli hash delle aggiunte sono uniformi per tutte le aggiunte nell'elenco. Si tratta del valore desired_hash_length inviato dal client o di un valore scelto dal server se il client ha omesso il campo. compressed_additions può essere solo uno dei seguenti: |
|
additions_four_bytes |
Le aggiunte di 4 byte. |
additions_eight_bytes |
Le aggiunte di 8 byte. |
additions_sixteen_bytes |
Le aggiunte di 16 byte. |
additions_thirty_two_bytes |
Le aggiunte di 32 byte. |
HashListMetadata
Metadati relativi a un determinato elenco di hash.
| Campi | |
|---|---|
threat_types[] |
Elenco non ordinato. Se non è vuoto, specifica che l'elenco di hash è un tipo di elenco di minacce ed elenca il tipo di minacce associate agli hash o ai prefissi di hash in questo elenco di hash. Può essere vuoto se la voce non rappresenta una minaccia, ad esempio se rappresenta un tipo probabilmente sicuro. |
likely_safe_types[] |
Elenco non ordinato. Se non è vuoto, specifica che l'elenco di hash rappresenta un elenco di hash probabilmente sicuri ed elenca i modi in cui sono considerati probabilmente sicuri. Questo campo è mutuamente esclusivo con il campo threat_types. |
description |
Una descrizione leggibile di questo elenco. Scritto in inglese. |
supported_hash_lengths[] |
Le lunghezze degli hash supportate per questo elenco di hash. Ogni elenco di hash supporta almeno una lunghezza. Pertanto, questo campo non sarà vuoto. |
hash_length |
La lunghezza dell'hash supportata per questo elenco di hash. Ogni elenco di hash supporta esattamente una lunghezza. Se viene introdotta una lunghezza dell'hash diversa per lo stesso insieme di tipi di minacce o tipi sicuri, verrà introdotta come elenco separato con un nome distinto e la rispettiva lunghezza dell'hash impostata. |
HashLength
La lunghezza degli hash in un elenco di hash.
| Enum | |
|---|---|
HASH_LENGTH_UNSPECIFIED |
Lunghezza non specificata. Il server non restituirà questo valore nelle risposte al client (nel campo supported_hash_lengths), ma il client è autorizzato a inviarlo al server (nel campo desired_hash_length), nel qual caso il server sceglierà un valore automaticamente. I client DEVONO consentire al server di scegliere un valore. |
FOUR_BYTES |
Ogni hash è un prefisso di quattro byte. |
EIGHT_BYTES |
Ogni hash è un prefisso di otto byte. |
SIXTEEN_BYTES |
Ogni hash è un prefisso di sedici byte. |
THIRTY_TWO_BYTES |
Ogni hash è un hash completo di 32 byte. |
LikelySafeType
Tipi di siti probabilmente sicuri.
Tieni presente che SearchHashesResponse non contiene intenzionalmente LikelySafeType.
| Enum | |
|---|---|
LIKELY_SAFE_TYPE_UNSPECIFIED |
Sconosciuto. |
GENERAL_BROWSING |
È probabile che questo sito sia abbastanza sicuro per la navigazione generale. È nota anche come cache globale. |
CSD |
È probabile che questo sito sia abbastanza sicuro da non dover eseguire modelli di rilevamento lato client o controlli di protezione della password. |
DOWNLOAD |
È probabile che questo sito sia abbastanza sicuro da non dover controllare i download. |
ListHashListsRequest
La richiesta di elencare gli elenchi di hash disponibili.
| Campi | |
|---|---|
page_size |
Il numero massimo di elenchi di hash da restituire. Il servizio potrebbe restituire meno di questo valore. Se non specificato, il server sceglierà una dimensione di pagina, che potrebbe essere maggiore del numero di elenchi di hash, in modo che la paginazione non sia necessaria. |
page_token |
Un token di pagina ricevuto da una chiamata |
ListHashListsResponse
La risposta contenente i metadati degli elenchi di hash.
| Campi | |
|---|---|
hash_lists[] |
L'hash viene elencato in un ordine arbitrario. Verranno inclusi solo i metadati degli elenchi di hash, non i contenuti. |
next_page_token |
Un token che può essere inviato come |
RiceDeltaEncoded128Bit
È uguale a RiceDeltaEncoded32Bit, tranne per il fatto che codifica numeri a 128 bit.
| Campi | |
|---|---|
first_value_hi |
I 64 bit superiori della prima voce nei dati codificati (hash). Se il campo è vuoto, i 64 bit superiori sono tutti pari a zero. |
first_value_lo |
I 64 bit più bassi della prima voce nei dati codificati (hash). Se il campo è vuoto, i 64 bit inferiori sono tutti pari a zero. |
rice_parameter |
Il parametro Golomb-Rice. Questo parametro è garantito compreso tra 99 e 126, inclusi. |
entries_count |
Il numero di voci con codifica delta nei dati codificati. Se è stato codificato un solo numero intero, questo sarà zero e il singolo valore verrà memorizzato in |
encoded_data |
I delta codificati che vengono codificati utilizzando il codificatore Golomb-Rice. |
RiceDeltaEncoded256Bit
È uguale a RiceDeltaEncoded32Bit, tranne per il fatto che codifica numeri a 256 bit.
| Campi | |
|---|---|
first_value_first_part |
I primi 64 bit della prima voce nei dati codificati (hash). Se il campo è vuoto, i primi 64 bit sono tutti pari a zero. |
first_value_second_part |
I bit da 65 a 128 della prima voce nei dati codificati (hash). Se il campo è vuoto, i bit da 65 a 128 sono tutti pari a zero. |
first_value_third_part |
I bit da 129 a 192 della prima voce nei dati codificati (hash). Se il campo è vuoto, i bit da 129 a 192 sono tutti pari a zero. |
first_value_fourth_part |
Gli ultimi 64 bit della prima voce nei dati codificati (hash). Se il campo è vuoto, gli ultimi 64 bit sono tutti pari a zero. |
rice_parameter |
Il parametro Golomb-Rice. Questo parametro è garantito essere compreso tra 227 e 254, inclusi. |
entries_count |
Il numero di voci con codifica delta nei dati codificati. Se è stato codificato un solo numero intero, questo sarà zero e il singolo valore verrà memorizzato in |
encoded_data |
I delta codificati che vengono codificati utilizzando il codificatore Golomb-Rice. |
RiceDeltaEncoded32Bit
I dati codificati Rice-Golomb. Utilizzato per gli hash o gli indici di rimozione. È garantito che ogni hash o indice qui abbia la stessa lunghezza, che è esattamente di 32 bit.
In generale, se ordiniamo tutte le voci in ordine alfabetico, scopriremo che i bit di ordine superiore tendono a non cambiare con la stessa frequenza dei bit di ordine inferiore. Ciò significa che, se prendiamo anche la differenza adiacente tra le voci, i bit di ordine superiore hanno un'alta probabilità di essere pari a zero. Sfrutta questa elevata probabilità di zero scegliendo essenzialmente un determinato numero di bit; tutti i bit più significativi di questo sono probabilmente pari a zero, quindi utilizziamo la codifica unaria. Visualizza il campo rice_parameter.
Nota storica: la codifica Rice-delta è stata utilizzata per la prima volta nella versione 4 di questa API. Nella versione 5 sono stati apportati due miglioramenti significativi: innanzitutto, la codifica Rice-delta è ora disponibile con prefissi hash più lunghi di 4 byte; in secondo luogo, i dati codificati vengono ora trattati come big endian per evitare un costoso passaggio di ordinamento.
| Campi | |
|---|---|
first_value |
La prima voce nei dati codificati (hash o indici) oppure, se è stato codificato un solo prefisso o indice di hash, il valore di quella voce. Se il campo è vuoto, la voce è pari a zero. |
rice_parameter |
Il parametro Golomb-Rice. Questo parametro è garantito essere compreso tra 3 e 30, inclusi. |
entries_count |
Il numero di voci con codifica delta nei dati codificati. Se è stato codificato un solo numero intero, questo sarà zero e il singolo valore verrà memorizzato in |
encoded_data |
I delta codificati che vengono codificati utilizzando il codificatore Golomb-Rice. |
RiceDeltaEncoded64Bit
È uguale a RiceDeltaEncoded32Bit, tranne per il fatto che codifica i numeri a 64 bit.
| Campi | |
|---|---|
first_value |
La prima voce nei dati codificati (hash) o, se è stato codificato un solo prefisso hash, il valore di quella voce. Se il campo è vuoto, la voce è pari a zero. |
rice_parameter |
Il parametro Golomb-Rice. Questo parametro è garantito essere compreso tra 35 e 62, inclusi. |
entries_count |
Il numero di voci con codifica delta nei dati codificati. Se è stato codificato un solo numero intero, questo sarà zero e il singolo valore verrà memorizzato in |
encoded_data |
I delta codificati che vengono codificati utilizzando il codificatore Golomb-Rice. |
SearchHashesRequest
Una richiesta inviata dal client per cercare prefissi hash specifici.
È progettato per cercare solo negli elenchi di minacce e non negli elenchi non di minacce come la cache globale.
Novità della versione 5: i client non devono specificare un ClientInfo o gli stati degli elenchi di hash nel proprio database locale. Questo serve a migliorare la privacy. Inoltre, i clienti non devono inviare i tipi di minacce che li interessano.
| Campi | |
|---|---|
hash_prefixes[] |
Obbligatorio. I prefissi degli hash da cercare. I client NON DEVONO inviare più di 1000 prefissi hash. Tuttavia, seguendo la procedura di elaborazione dell'URL, i client NON DOVREBBERO dover inviare più di 30 prefissi hash. Attualmente è necessario che ogni prefisso di hash abbia una lunghezza di esattamente 4 byte. Questa limitazione POTREBBE essere allentata in futuro. |
filter |
Facoltativo. Se il cliente è interessato all'applicazione di filtri, ad esempio al recupero solo di tipi specifici di minacce, può specificarlo. Se omesso, vengono restituite tutte le minacce corrispondenti. Ti consigliamo vivamente di omettere questo parametro per usufruire della protezione più completa offerta da Navigazione sicura. Il filtro viene specificato utilizzando il linguaggio Common Expression Language di Google, disponibile all'indirizzo https://github.com/google/cel-spec, insieme a esempi generali. Ecco alcuni esempi specifici che possono essere utilizzati: Il filtro Il filtro |
SearchHashesResponse
La risposta restituita dopo la ricerca degli hash delle minacce.
Se non viene trovato nulla, il server restituirà uno stato OK (codice di stato HTTP 200) con il campo full_hashes vuoto, anziché uno stato NOT_FOUND (codice di stato HTTP 404).
Novità della versione 5: è presente una separazione tra FullHash e FullHashDetail. Se un hash rappresenta un sito con più minacce (ad es. sia MALWARE che SOCIAL_ENGINEERING), non è necessario inviare l'hash completo due volte come nella versione 4. Inoltre, la durata della cache è stata semplificata in un unico campo cache_duration.
| Campi | |
|---|---|
full_hashes[] |
Elenco non ordinato. L'elenco non ordinato degli hash completi trovati. |
cache_duration |
La durata della cache lato client. Il client DEVE aggiungere questa durata all'ora corrente per determinare l'ora di scadenza. La data e l'ora di scadenza si applicano a ogni prefisso di hash interrogato dal client nella richiesta, indipendentemente dal numero di hash completi restituiti nella risposta. Anche se il server non restituisce hash completi per un determinato prefisso di hash, questo fatto DEVE essere memorizzato nella cache anche dal client. Se e solo se il campo Importante: il client NON DEVE presumere che il server restituirà la stessa durata della cache per tutte le risposte. Il server PUÒ scegliere durate della cache diverse per risposte diverse a seconda della situazione. |
SizeConstraints
I vincoli relativi alle dimensioni degli elenchi di hash.
| Campi | |
|---|---|
max_update_entries |
La dimensione massima in numero di voci. L'aggiornamento non conterrà più voci di questo valore, ma è possibile che contenga meno voci di questo valore. Il valore DEVE essere almeno 1024. Se omesso o pari a zero, non viene impostato alcun limite di dimensione dell'aggiornamento. |
max_database_entries |
Imposta il numero massimo di voci che il client è disposto ad avere nel database locale per l'elenco. Il server POTREBBE causare l'archiviazione da parte del client di un numero inferiore di voci. Se omesso o pari a zero, non viene impostato alcun limite di dimensione del database. |
ThreatAttribute
Attributi delle minacce. Questi attributi possono conferire un significato aggiuntivo a una determinata minaccia, ma non influiscono sul tipo di minaccia. Ad esempio, un attributo può specificare una confidenza inferiore, mentre un altro attributo può specificare una confidenza superiore. In futuro è possibile che vengano aggiunti altri attributi.
| Enum | |
|---|---|
THREAT_ATTRIBUTE_UNSPECIFIED |
Attributo sconosciuto. Se viene restituito dal server, il client deve ignorare del tutto il FullHashDetail che lo racchiude. |
CANARY |
Indica che threat_type non deve essere utilizzato per l'applicazione. |
FRAME_ONLY |
Indica che threat_type deve essere utilizzato solo per l'applicazione delle norme nei frame. |
ThreatType
Tipi di minacce.
| Enum | |
|---|---|
THREAT_TYPE_UNSPECIFIED |
Tipo di minaccia sconosciuto. Se viene restituito dal server, il client deve ignorare del tutto il FullHashDetail che lo racchiude. |
MALWARE |
Tipo di minaccia malware. I malware sono software o applicazioni per dispositivi mobili pensati appositamente per danneggiare un computer, un dispositivo mobile, il software in esecuzione o gli utenti. I comportamenti dei malware includono l'installazione di software senza il consenso dell'utente e l'installazione di software dannoso, come i virus. Ulteriori informazioni sono disponibili qui. |
SOCIAL_ENGINEERING |
Tipo di minaccia di ingegneria sociale. Le pagine di ingegneria sociale dichiarano falsamente di agire per conto di una terza parte con l'intenzione di confondere gli spettatori e indurli a eseguire un'azione per la quale si affiderebbero solo a un vero agente di quella terza parte. Il phishing è un tipo di ingegneria sociale che ingannevolmente induce lo spettatore a eseguire l'azione specifica di fornire informazioni, ad esempio le credenziali di accesso. Ulteriori informazioni sono disponibili qui. |
UNWANTED_SOFTWARE |
Tipo di minaccia di software indesiderato. Per software indesiderato si intende qualsiasi software che non rispetta i Principi sul software di Google, ma non è malware. |
POTENTIALLY_HARMFUL_APPLICATION |
Tipo di minaccia di app potenzialmente dannose come utilizzato da Google Play Protect per il Play Store. |