Phishing Protection: Server Spec: Difference between revisions

Phishing Protection: Server Spec (view source)

Revision as of 21:35, 5 May 2006

7,541 bytes added , 5 May 2006

no edit summary

Brianr@gmail.com

14

edits

@@ Line 1: / Line 1: @@
 == Safe Browsing Server Specification ==
-<i>Niels Provos</i>
+_Niels Provos_
 This documents contains the relevant information necessary to implement a server that talks the Google Safe Browsing protocol.  The Google Safe Browsing protocol does not use binary data but instead uses human-readable text only.  An implementation is relatively straight forward.
@@ Line 82: / Line 82: @@
 to instruct the client to issue a new GetKey? request.
-To decrypt an encrypted a
+To decrypt an encrypted a bad wrapped key, a server may also output
+ pleaserekey:1:1
+to instruct the client to issue a new GetKey? request.
+To decrypt an encrypted lookup request, a server needs to inspect the following query parameters:
+    * encver: The algorithm version used by the client to construct the encrypted URL. The only valid version is currently 1.
+    * nonce: A random nonce selected by the client to seed the encryption algorithm. The server needs to convert it into an
+unsigned 32-bit integer.
+    * wrkey: The wrappedkey provided by the server as response to a GetKey? request.
+    * encparams: The encrypted content of the lookup request.
+The description of the current encryption algorithm can be found below. Decryption results, in an unencrypted lookup request; see above.
+If the URL reported in the q query parameter belongs to a phishing site, return:
+ phishy:1:1
+If you want the client to update their wrapped key, instruct it to do so by including pleaserekey:1:1 in the output.
+The client query parameter tells you which version of the Anti-Phishing extension is talking to your servers.
+== Decryption Algorithm Version 1: ==
+The wrappedkey and the encparams are Websafe Base64 encoded and need to be decoded into binary first.
+The server drives an decryption key from the client key and nonce, in the following fashion:
+    * Create MD5 context ctx.
+    * Update the MD5 context with the 16-byte client key.
+    * Convert the nonce into a 32-bit unsigned integer; represent the integer in network order (most-significant byte first) and update the MD5 context with it.
+    * Use the 128-bit MD5 digest from this context as decryption key.
+The algorithm for encrypting lookups is RC4. It is also being used to decrypt the encparams. Remove all the parameters relating to encryption from the URL and add the decrypt content as new query parameters. As a result, you should have a request that looks like an unencrypted lookup.
+== Update Requests ==
+The client can download and update various kinds of tables (lists) via the update request. Each table has a name with three components: ''provider''-''type''-''format''. The provider is just a name used to identify where the list comes from. The type indicates whether the list is a white or blacklist. The format indicates how URLs should be looked up in the list, for example the list might contain domains, hosts, or URLs. For example:
+ goog-black-url      // A blacklist from Google; lookups should be by URL
+ acme-white-domain   // A whitelist of domains from Acme, Inc.; lookups by domain
+Tables are versioned with a major and minor numbers. The major version is currently 1, and is used to describe the wire format (see below), how the table is serialized. The minor number is the version of the list. When providers add new items to a list or take items out of it, they increment the minor version number.
+The client keeps a list of tables it knows about, as well as the version it has of each. To request an update from a provider, the client issues an update request and expresses its tables and versions as a query parameter like: version=type:major:minor[,type:major:minor]*. For example:
+ http://www.example.com/phishing/update?client=foo&version=goog-black-url:1:432,acme-white-domain:1:32
+The server responds with updates to all tables in the wire format. For each table, the response includes either a completely new table or a diff between the client's version of the table and the most current version, whichever is smaller. If the client provided a wrapped key, the server also needs to compute a Message Authentication Code for the response data that the client use to verify the integrity of the tabels.
+=== Wire Format ===
+The serialized form of the tables is called the wire format. It's the format of an update response.
+The wire format is a simple line-oriented protocol. It consists of a sequence of sections consisting of a header line like
+ [type major.minor [update]][[mac=<digest>]]
+followed by lines of data comprising the table described by the header. If the "update" token appears in the header line, the data following constitute an update to the client's existing table. Else the data specify a full, new table. If the client provided a wrappedkey, the response must include the message authentication code. Here are a few possible first-line responses:
+    * [goog-black-url 1.372 update]
+    * [goog-black-url 1.372]
+    * [goog-white-domain 1.10][mac=iA5vLUidpXAPwfcAH9+8OQ==]
+    * [goog-white-domain 1.10 update][mac=iA5vLUidpXAPwfcAH9+8OQ==]
+Data lines start with a + or -. A plus indicates an addition to the table and is followed by a tab-separated key/value pair. A minus means to remove a key from the table and is followed by the key itself.
+An example update response is:
+ [goog-black-url 1.372 update]
+ +http://payments.g00gle.com/   1
+ +http://www.ovrture.com/givemeallyourmoney.htm   1
+ +http://www.microfist.com/foo?bar=x   1
+ -http://www.gewgul.com/index.html
+ -http://yah0o.com/login.shtml
+ ...
+ [acme-white-domain 1.13]
+ +google.com 1
+ +slashdot.org 1
+ +amazon.co.uk 1
+ ...
+In this example, the client has some version of goog-black-url prior to 372 and the server is telling the client to bring itself up to version 372 by applying the adds and deletes that follow. The client has some version of acme-white-domain earlier than version 13, but the diff would be longer than the entire version 13 table, so it is sending a complete replacement.
+The data lines are opaque to the wire format. They come in some format that the extension knows how to use, based on the table type. More complicated types of tables than just domain-, host-, and URL-lookup are possible. For example, a table could map hosts to regular expressions matching phishy pages on the host in question.
+The client provided a wrapped key via the wrkey query parameter. The server must compute a MAC over the update contents. See below for a description of the message authentication code.
+=== Message Authentication Code for Table Updates ===
+The client provides a wrapped key to the server which the server needs to convert into the shard client key; see above. The MAC is computed from an MD5 Digest over the following information: client_key|separator|table data|separator|client_key. The separator is the string :coolgoog: - that is a colon followed by "coolgoog" followed by a colon. The resulting 128-bit MD5 digest is websafe baset64 encoded and provided via [mac=<encoded digest>] on the first line of a table update; see above.
+Here is an example, that you can use to verify the MAC algorithm in your server:
+ client key: "dtmbEN1kgN/LmuEoYifaFw=="
+A sample query to get table data protected by the client key looks like this:
+ www.example.com/phishing/update?version=test-white-domain:1:-1&wrkey=MTpPH3pnLDKihecOci%2B0W5dk"
+Below is a sample response including a correct MAC based on the keys provided to the server above.
+ [test-white-domain 1.1][mac=iA5vLUidpXAPwfcAH9+8OQ==]
+ +white1.com     1
+ +white2.com     1
+ +white3.com     1
+== Report Requests ==
+In enhanced mode, a client informs the server about phishing pages it encounters. For example, it might report that the user declined the warning on a blacklisted page, a cue to the provider that the page might be a false positive (or that the warning is ineffective). For example:
+ http://www.example.com/phishing/report?client=foo&evts=phishdecline&evtd=http://somephishydomain.com/login.html
+The client does not expect an answer to a report request.