.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::Google::SafeBrowsing2 3pm"
.TH Net::Google::SafeBrowsing2 3pm "2021-01-07" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::Google::SafeBrowsing2 \- Perl extension for the Google Safe Browsing v2 API. (Google Safe Browsing v1 has been deprecated by Google.)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Net::Google::SafeBrowsing2;
\&  use Net::Google::SafeBrowsing2::Sqlite;
\&  
\&  my $storage = Net::Google::SafeBrowsing2::Sqlite\->new(file => \*(Aqgoogle\-v2.db\*(Aq);
\&  my $gsb = Net::Google::SafeBrowsing2\->new(
\&        key     => "my key", 
\&        storage => $storage,
\&  );
\&  
\&  $gsb\->update();
\&  my $match = $gsb\->lookup(url => \*(Aqhttp://www.gumblar.cn/\*(Aq);
\&  
\&  if ($match eq MALWARE) {
\&        print "http://www.gumblar.cn/ is flagged as a dangerous site\en";
\&  }
\&
\&  $storage\->close();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Net::Google::SafeBrowsing2 implements the Google Safe Browsing v2 \s-1API.\s0
.PP
The library passes most of the unit tests listed in the \s-1API\s0 documentation. See the documentation (<http://code.google.com/apis/safebrowsing/developers_guide_v2.html>) for more details about the failed tests.
.PP
The Google Safe Browsing database must be stored and managed locally. Net::Google::SafeBrowsing2::Sqlite uses Sqlite as the storage back-end, Net::Google::SafeBrowsing2::MySQL uses MySQL. Other storage mechanisms (databases, memory, etc.) can be added and used transparently with this module.
.PP
You may want to look at \*(L"Google Safe Browsing v2: Implementation Notes\*(R" (<http://www.zscaler.com/research/Google%20Safe%20Browsing%20v2%20API.pdf>), a collection of notes and real-world numbers about the \s-1API.\s0 This is intended for people who want to learn more about the \s-1API,\s0 whether as a user or to make their own implementation.
.PP
The source code is available on github at <https://github.com/juliensobrier/Net\-Google\-SafeBrowsing2>.
.PP
If you do not need to inspect more than 10,000 URLs a day, you can use Net::Google::SafeBrowsing2::Lookup with the Google Safe Browsing v2 Lookup \s-1API\s0 which does not require to store and maintain a local database.
.PP
\&\s-1IMPORTANT:\s0 If you start with an empty database, you will need to perform several updates to retrieve all the Google Safe Browsing information. This may require up to 24 hours. This is a limitation of the Google \s-1API,\s0 not of this module. See \*(L"Google Safe Browsing v2: Implementation Notes\*(R" at <http://www.zscaler.com/research/Google%20Safe%20Browsing%20v2%20API.pdf>.
.SH "CONSTANTS"
.IX Header "CONSTANTS"
Several  constants are exported by this module:
.IP "\s-1DATABASE_RESET\s0" 4
.IX Item "DATABASE_RESET"
Google requested to reset (empty) the local database.
.IP "\s-1MAC_ERROR\s0" 4
.IX Item "MAC_ERROR"
The replies from Google could not be validated with the \s-1MAC\s0 keys.
.IP "\s-1MAC_KEY_ERROR\s0" 4
.IX Item "MAC_KEY_ERROR"
The request for the \s-1MAC\s0 keys failed.
.IP "\s-1INTERNAL_ERROR\s0" 4
.IX Item "INTERNAL_ERROR"
An internal error occurred.
.IP "\s-1SERVER_ERROR\s0" 4
.IX Item "SERVER_ERROR"
The server sent an error back to the client.
.IP "\s-1NO_UPDATE\s0" 4
.IX Item "NO_UPDATE"
No update was performed, probably because it is too early to make a new request to Google Safe Browsing.
.IP "\s-1NO_DATA\s0" 4
.IX Item "NO_DATA"
No data was sent back by Google to the client, probably because the database is up to date.
.IP "\s-1SUCCESSFUL\s0" 4
.IX Item "SUCCESSFUL"
The operation was successful.
.IP "\s-1MALWARE\s0" 4
.IX Item "MALWARE"
Name of the Malware list in Google Safe Browsing (shortcut to 'goog\-malware\-shavar')
.IP "\s-1PHISHING\s0" 4
.IX Item "PHISHING"
Name of the Phishing list in Google Safe Browsing (shortcut to 'googpub\-phish\-shavar')
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "\fBnew()\fP"
.IX Subsection "new()"
Create a Net::Google::SafeBrowsing2 object
.PP
.Vb 7
\&  my $gsb = Net::Google::SafeBrowsing2\->new(
\&        key     => "my key", 
\&        storage => Net::Google::SafeBrowsing2::Sqlite\->new(file => \*(Aqgoogle\-v2.db\*(Aq),
\&        debug   => 0,
\&        mac             => 0,
\&        list    => MALWARE,
\&  );
.Ve
.PP
Arguments
.IP "key" 4
.IX Item "key"
Required. Your Google Safe browsing \s-1API\s0 key
.IP "storage" 4
.IX Item "storage"
Required. Object which handle the storage for the Google Safe Browsing database. See Net::Google::SafeBrowsing2::Storage for more details.
.IP "list" 4
.IX Item "list"
Optional. The Google Safe Browsing list to handle. By default, handles both \s-1MALWARE\s0 and \s-1PHISHING.\s0
.IP "mac" 4
.IX Item "mac"
Optional. Set to 1 to enable Message Authentication Code (\s-1MAC\s0). 0 (disabled) by default.
.IP "debug" 4
.IX Item "debug"
Optional. Set to 1 to enable debugging. 0 (disabled) by default.
.Sp
The debug output maybe quite large and can slow down significantly the update and lookup functions.
.IP "errors" 4
.IX Item "errors"
Optional. Set to 1 to show errors to \s-1STDOUT. 0\s0 (disabled by default).
.IP "version" 4
.IX Item "version"
Optional. Google Safe Browsing version. 2.2 by default
.SH "PUBLIC FUNCTIONS"
.IX Header "PUBLIC FUNCTIONS"
.SS "\fBupdate()\fP"
.IX Subsection "update()"
Perform a database update.
.PP
.Vb 1
\&  $gsb\->update();
.Ve
.PP
Return the status of the update (see the list of constants above): \s-1INTERNAL_ERROR, SERVER_ERROR, NO_UPDATE, NO_DATA\s0 or \s-1SUCCESSFUL\s0
.PP
This function can handle two lists at the same time. If one of the list should not be updated, it will automatically skip it and update the other one. It is faster to update two lists at once rather than doing them one by one.
.PP
\&\s-1NOTE:\s0 If you start with an empty database, you will need to perform several updates to retrieve all the Google Safe Browsing information. This may require up to 24 hours. This is a limitation of the Google \s-1API,\s0 not of this module. See \*(L"Google Safe Browsing v2: Implementation Notes\*(R" at <http://www.zscaler.com/research/Google%20Safe%20Browsing%20v2%20API.pdf>.
.PP
Arguments
.IP "list" 4
.IX Item "list"
Optional. Update a specific list. Use the list(s) from \fBnew()\fR by default.
.IP "mac" 4
.IX Item "mac"
Optional. Set to 1 to enable Message Authentication Code (\s-1MAC\s0). Use the value from \fBnew()\fR by default.
.IP "force" 4
.IX Item "force"
Optional. Force the update (1). Disabled by default (0).
.Sp
Be careful if you set this option to 1 as too frequent updates might result in the blacklisting of your \s-1API\s0 key.
.SS "\fBimport_chunks()\fP"
.IX Subsection "import_chunks()"
Import add and sub chunks from a file.
.PP
.Vb 1
\&  my $result = $gsb\->import_chunks(list => MALWARE, file => \*(Aqmalware.dat\*(Aq);
.Ve
.PP
Return the status of the import: \s-1INTERNAL_ERROR\s0 or \s-1SUCCESSFUL.\s0
.PP
This function should be used to initialize an empty back-end storage.
.PP
Arguments
.IP "list" 4
.IX Item "list"
Required. Google list to use.
.IP "file" 4
.IX Item "file"
Required. File that contains the list of chunks. This file can be created with the \f(CW\*(C`export\*(C'\fR function inherited from \f(CW\*(C`Net::Google::SafeBrowsing2::DBI\*(C'\fR.
.SS "\fBlookup()\fP"
.IX Subsection "lookup()"
Lookup a \s-1URL\s0 against the Google Safe Browsing database.
.PP
.Vb 1
\&  my $match = $gsb\->lookup(url => \*(Aqhttp://www.gumblar.cn\*(Aq);
.Ve
.PP
Returns the name of the list if there is any match, returns an empty string otherwise.
.PP
Arguments
.IP "list" 4
.IX Item "list"
Optional. Lookup against a specific list. Use the list(s) from \fBnew()\fR by default.
.IP "url" 4
.IX Item "url"
Required. \s-1URL\s0 to lookup.
.SS "\fBget_lists()\fP"
.IX Subsection "get_lists()"
Returns the name of all the Google Safe Browsing lists
.PP
.Vb 1
\&  my $@lists = $gsb\->get_lists();
.Ve
.PP
\&\s-1NOTE:\s0 this function is useless in practice because Google includes some lists which cannot be used by the Google Safe Browsing \s-1API,\s0 like lists used by the Google toolbar.
.SS "\fBlast_error()\fP"
.IX Subsection "last_error()"
Get/Set the last error message.
.PP
.Vb 2
\&  print "Last error: ", $gsb\->last_error(), "\en";
\&  $gsb\->last_error(\*(Aq\*(Aq); # Reset last error
.Ve
.PP
\&\s-1NOTE:\s0 the last error message might not come from the last call. Returns an empty string if no errors.
.SH "PRIVATE FUNCTIONS"
.IX Header "PRIVATE FUNCTIONS"
These functions are not intended to be used externally.
.SS "\fBlookup_suffix()\fP"
.IX Subsection "lookup_suffix()"
Lookup a host prefix.
.SS "\fBlookup_suffix()\fP"
.IX Subsection "lookup_suffix()"
Lookup a host prefix in the local database only.
.SS "\fBlocal_lookup()\fP"
.IX Subsection "local_lookup()"
Lookup a \s-1URL\s0 against the local Google Safe Browsing database \s-1URL.\s0 This should be used for debugging purpose only. See the lookup for normal use.
.PP
.Vb 1
\&  my $match = $gsb\->local_lookup(url => \*(Aqhttp://www.gumblar.cn\*(Aq);
.Ve
.PP
Returns the name of the list if there is any match, returns an empty string otherwise.
.PP
Arguments
.IP "list" 4
.IX Item "list"
Optional. Lookup against a specific list. Use the list(s) from \fBnew()\fR by default.
.IP "url" 4
.IX Item "url"
Required. \s-1URL\s0 to lookup.
.SS "\fBrequest_key()\fP"
.IX Subsection "request_key()"
Request the Message Authentication Code (\s-1MAC\s0) keys
.SS "\fBrequest_mac_keys()\fP"
.IX Subsection "request_mac_keys()"
Request the Message Authentication Code (\s-1MAC\s0) keys from Google.
.SS "\fBvalidate_data_mac()\fP"
.IX Subsection "validate_data_mac()"
Validate data against the \s-1MAC\s0 keys.
.SS "\fBupdate_error()\fP"
.IX Subsection "update_error()"
Handle server errors during a database update.
.SS "\fBlookup_whitelist()\fP"
.IX Subsection "lookup_whitelist()"
Lookup a host prefix and suffix in the whitelist (s chunks)
.SS "\fBua()\fP"
.IX Subsection "ua()"
Create LWP::UserAgent to make \s-1HTTP\s0 requests to Google.
.SS "\fBparse_s()\fP"
.IX Subsection "parse_s()"
Parse data from a rediration (add asnd sub chunk information).
.SS "\fBparse_s()\fP"
.IX Subsection "parse_s()"
Parse s chunks information for a database update.
.SS "\fBparse_a()\fP"
.IX Subsection "parse_a()"
Parse a chunks information for a database update.
.SS "\fBhex_to_ascii()\fP"
.IX Subsection "hex_to_ascii()"
Transform hexadecimal strings to printable \s-1ASCII\s0 strings. Used mainly for debugging.
.PP
.Vb 1
\&  print $gsb\->hex_to_ascii(\*(Aqhex value\*(Aq);
.Ve
.SS "\fBascii_to_hex()\fP"
.IX Subsection "ascii_to_hex()"
Transform \s-1ASCII\s0 strings to hexadecimal strings.
.SS "\fBdebug()\fP"
.IX Subsection "debug()"
Print debug output.
.SS "\fBerror()\fP"
.IX Subsection "error()"
Print error message.
.SS "\fBcanonical_domain_suffixes()\fP"
.IX Subsection "canonical_domain_suffixes()"
Find all suffixes for a domain.
.SS "\fBcanonical_domain()\fP"
.IX Subsection "canonical_domain()"
Find all canonical domains a domain.
.SS "\fBcanonical_path()\fP"
.IX Subsection "canonical_path()"
Find all canonical paths for a \s-1URL.\s0
.SS "\fBcanonical()\fP"
.IX Subsection "canonical()"
Find all canonical URLs for a \s-1URL.\s0
.SS "\fBcanonical_uri()\fP"
.IX Subsection "canonical_uri()"
Create a canonical \s-1URI.\s0
.PP
\&\s-1NOTE: URI\s0 cannot handle all the test cases provided by Google. This method is a hack to pass most of the test. A few tests are still failing. The proper way to handle \s-1URL\s0 canonicalization according to Google would be to create a new module to handle URLs. However, I believe most real-life cases are handled correctly by this function.
.SS "\fBcanonical()\fP"
.IX Subsection "canonical()"
Return all possible full hashes for a \s-1URL.\s0
.SS "\fBprefix()\fP"
.IX Subsection "prefix()"
Return a hash prefix. The size of the prefix is set to 4 bytes.
.SS "\fBrequest_full_hash()\fP"
.IX Subsection "request_full_hash()"
Request full full hashes for specific prefixes from Google.
.SS "\fBparse_full_hashes()\fP"
.IX Subsection "parse_full_hashes()"
Process the request for full hashes from Google.
.SS "\fBget_a_range()\fP"
.IX Subsection "get_a_range()"
Get the list of a chunks ranges for a list update.
.SS "\fBget_s_range()\fP"
.IX Subsection "get_s_range()"
Get the list of s chunks ranges for a list update.
.SS "\fBcreate_range()\fP"
.IX Subsection "create_range()"
Create a list of ranges (1\-3, 5, 7\-11) from a list of numbers.
.SS "\fBexpand_range()\fP"
.IX Subsection "expand_range()"
Explode list of ranges (1\-3, 5, 7\-11) into a list of numbers (1,2,3,5,7,8,9,10,11).
.SH "CHANGELOG"
.IX Header "CHANGELOG"
.IP "1.07" 4
.IX Item "1.07"
Add \f(CW\*(C`import_chunks()\*(C'\fR feature to import add chunks and sub chunks from a file.
.IP "1.05" 4
.IX Item "1.05"
No code change. Move \f(CW\*(C`local_lookup\*(C'\fR to \s-1PRIVATE FUNCTIONS\s0 to avoid confusions.
.IP "1.04" 4
.IX Item "1.04"
Introduce Net::Google::SafeBrowsing2::Lookup. Remind people that Google Safe Browsing v1 has been deprecated by Google.
.IP "1.03" 4
.IX Item "1.03"
The source code is available on github at <https://github.com/juliensobrier/Net\-Google\-SafeBrowsing2>.
.IP "1.02" 4
.IX Item "1.02"
Fix uninitialized \f(CW$self\fR\->{errors} variable
.IP "1.01" 4
.IX Item "1.01"
Use String::HexConvert for faster hex_to_ascii.
.IP "1.0" 4
.IX Item "1.0"
Separate the error output from the debug output.
.IP "0.9" 4
.IX Item "0.9"
Fix bug with local whitelisting (sub chunks). Fix the parsing of full hashes.
.IP "0.8" 4
.IX Item "0.8"
Reduce the number of full hash requests.
.IP "0.7" 4
.IX Item "0.7"
Add local_lookup to perform a lookup against the local database only. This function should be used for debugging purpose only.
Small code optimizations.
.IP "0.6" 4
.IX Item "0.6"
Handle local database reset.
.IP "0.5" 4
.IX Item "0.5"
Update documentation.
.IP "0.4" 4
.IX Item "0.4"
Speed update the database update. The first update went down from 20 minutes to 20 minutes.
.IP "0.3" 4
.IX Item "0.3"
Fix typos in the documentation.
.Sp
Remove dependency on Switch (thanks to Curtis Jewel).
.Sp
Fix value of \s-1FULL_HASH_TIME.\s0
.IP "0.2" 4
.IX Item "0.2"
Add support for Message Authentication Code (\s-1MAC\s0)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See Net::Google::SafeBrowsing2::Storage, Net::Google::SafeBrowsing2::Sqlite and Net::Google::SafeBrowsing2::MySQL for information on storing and managing the Google Safe Browsing database.
.PP
Google Safe Browsing v2 \s-1API:\s0 <http://code.google.com/apis/safebrowsing/developers_guide_v2.html>
.PP
Net::Google::SafeBrowsing (Google Safe Browsing v1) is deprecated by Google since 12/01/2011.
.SH "AUTHOR"
.IX Header "AUTHOR"
Julien Sobrier, <jsobrier@zscaler.com> or <julien@sobrier.net>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2012 by Julien Sobrier
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.8 or,
at your option, any later version of Perl 5 you may have available.