Reference Guide

Contents

Audience

This document is intended for programmers who want to use Google phishing and malware data to protect users from potentially malicious websites.

It's a reference document; it assumes that you understand the concepts presented in the Developer's Guide.

Request Types

The API consists of two different types of HTTP requests:

• https://sb-ssl.google.com/safebrowsing/getkey: This request requires SSL support. It provides the client with a private key for confidential communication with the server.

• http://sb.google.com/safebrowsing/update: The client provides a list of tables that it wants the server to update. The server either provides the full content of the current tables or incremental updates to bring the client's tables up to the current version.

The getkey request takes one required parameter (client).

The response to the getkey request includes a client key and a wrapped key.

The update request takes three required parameters (client, apikey and version and one optional parameter (wrkey).

The response to the update request includes the appropriate table data, to bring that client up to date.

Query Parameters

The API supports the following query parameters:

• client - should be used to specify the type of client, in this case "api". (Required for both getkey and update requests.)
• apikey - authenticates the user as a valid api user. See the Getting Started section in the Developer's Guide for information on getting an API key. (Required for update request only)
• version - specifies the tables and versions that the client has, i.e. "version=goog-black-hash:1:432,goog-malware-hash:1:32". (Required for update request only)
• wrkey - the wrapped key sent by the server in response to a getkey request. It should only be used if the client wishes to receive a MAC. (Optional for update request)

Canonicalization Examples

This section provides some examples of canonicalizing IP addresses and URLs. To make sure you're able to look up URLs in the blacklists, you should verify that your client implementation handles these test cases correctly.

The first set of examples covers normalizing IP addresses into dotted decimal form:

Original	Canonicalized	Explanation
1.2.3.4	1.2.3.4	normal decimal form
012.034.01.055	10.28.1.45	octal components, identified by a leading zero
0x12.0x43.0x44.0x01	18.67.68.1	hex components, identified by a leading 0[xX]
167838211	10.1.2.3	fewer than 4 components, extend the last component to fill the remaining bytes
12.0x12.01234	12.18.2.156	mixed bases, fewer than 4 components
276.2.3	20.2.0.3	since 276 is not the last component, it's only allowed to take up 1 byte in the result
0x10000000b	0.0.0.11	if the number is larger than 32 bits, take the low 32 bits

The following strings are not well-formed IP addresses, and should not be normalized:
"0x120x34"
"123.123.0.0.1"
"1.2.3.00x0"

These examples cover canonicalizing URLs so that they can be used to create suffix/prefix expressions:

Original	Canonicalized	Explanation
http://google.com/	http://google.com/	already in canonical form
http://GOOgle.com	http://google.com/	need a trailing slash, and lowercase the host
http://..google..com../	http://google.com/	strip leading and trailing dots, collapse multiple dots
http://google.com/%25%34%31%25%31%46	http://google.com/A%1F	fully unescape, then re-escape once
http://google^.com/	http://google%5E.com/	escape characters in the hostname
http://google.com/1/../2/././	http://google.com/2/	relative path resolution
http://google.com/1//2?3//4	http://google.com/1/2?3//4	collapse consecutive slashes in the path