.\" 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::Storage 3pm"
.TH Net::Google::SafeBrowsing2::Storage 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::Storage \- Base class for storing the Google Safe Browsing v2 database
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  package Net::Google::SafeBrowsing2::Sqlite;
\&
\&  use base \*(AqNet::Google::SafeBrowsing2::Storage\*(Aq;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the base class for implementing a storage mechanism for the Google Safe Browsing v2 database. See Net::Google::SafeBrowsing2::Sqlite for an example of implementation.
.PP
This module cannot be used on its own as it does not actually store anything. All methods should redefined. Check the code to see which arguments are used, and what should be returned.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "\fBnew()\fP"
.IX Subsection "new()"
.Vb 1
\&  Create a Net::Google::SafeBrowsing2::Storage object
\&
\&  my $storage   => Net::Google::SafeBrowsing2::Storage\->new();
.Ve
.SH "PUBLIC FUNCTIONS"
.IX Header "PUBLIC FUNCTIONS"
.SS "\fBadd_chunks()\fP"
.IX Subsection "add_chunks()"
Add chunk information to the local database
.PP
.Vb 1
\&  $storage\->add_chunks(type => \*(Aqa\*(Aq, chunknum => 2154, chunks => [{host => HEX, prefix => \*(Aq\*(Aq}], list => \*(Aqgoog\-malware\-shavar\*(Aq);
.Ve
.PP
Does not return anything.
.PP
Arguments
.IP "type" 4
.IX Item "type"
Required. Type of chunk: 'a' (add chunk) or 's' (sub chunk).
.IP "chunknum" 4
.IX Item "chunknum"
Required. Chunk number.
.IP "chunks" 4
.IX Item "chunks"
Required. Array of chunks
.Sp
For add chunks, each element of the array is an hash reference in the following format:
.Sp
.Vb 4
\&  {
\&    host => HEX,
\&        prefix => HEX
\&  }
.Ve
.Sp
For sub chunks, each element of the array is an hash reference in the following format:
.Sp
.Vb 5
\&  {
\&    host => HEX,
\&        prefix => HEX,
\&    add_chunknum => INTEGER
\&  }
.Ve
.IP "list" 4
.IX Item "list"
Required. Google Safe Browsing list name.
.SS "\fBget_add_chunks()\fP"
.IX Subsection "get_add_chunks()"
Returns a list of chunks for a given host key for all lists.
.PP
.Vb 1
\&        my @chunks = $storage\->get_add_chunks(hostkey => HEX);
.Ve
.PP
Arguments
.IP "hostkey." 4
.IX Item "hostkey."
Required. Host key.
.PP
Return value
.Sp
.RS 4
Array of add chunks in the same format as described above:
.Sp
.Vb 10
\&    (
\&                { 
\&                        chunknum        => 25121,
\&                        hostkey         => hex(\*(Aq12345678\*(Aq),
\&                        prefix          => \*(Aq\*(Aq,
\&                        list            => \*(Aqgoog\-malware\-shavar\*(Aq
\&                },
\&                { 
\&                        chunknum        => \*(Aq25121\*(Aq,
\&                        hostkey         => hex(\*(Aq12345678\*(Aq),
\&                        prefix          => hex(\*(Aq2fc96b9f\*(Aq),
\&                        list            => \*(Aqgoog\-malware\-shavar\*(Aq
\&                },
\&        );
.Ve
.RE
.SS "\fBget_sub_chunks()\fP"
.IX Subsection "get_sub_chunks()"
Returns a list of sub chunks for a given host key for all lists.
.PP
.Vb 1
\&        my @chunks = $storage\->get_sub_chunks(hostkey => HEX);
.Ve
.PP
Arguments
.IP "hostkey" 4
.IX Item "hostkey"
Required. Host key.
.PP
Return value
.Sp
.RS 4
Array of add chunks in the same format as described above:
.Sp
.Vb 10
\&    (
\&                { 
\&                        chunknum        => 37441,
\&                        prefix          => \*(Aq\*(Aq,
\&                        addchunknum     => 23911,
\&                        list            => \*(Aqgoog\-malware\-shavar\*(Aq
\&                },
\&                { 
\&                        chunknum        => 37441,
\&                        prefix          => \*(Aq\*(Aq,
\&                        addchunknum     => 22107,
\&                        list            => \*(Aqgoog\-malware\-shavar\*(Aq
\&                },
\&        );
.Ve
.RE
.SS "\fBget_add_chunks_nums()\fP"
.IX Subsection "get_add_chunks_nums()"
Returns a list of unique add chunk numbers for a specific list.
.PP
\&\fB\s-1IMPORTANT\s0\fR: this list should be sorted in ascendant order.
.PP
.Vb 1
\&        my @ids = $storage\->get_add_chunks_nums(list => \*(Aqgoog\-malware\-shavar\*(Aq);
.Ve
.PP
Arguments
.IP "list" 4
.IX Item "list"
Required. Google Safe Browsing list name
.PP
Return value
.Sp
.RS 4
Array of integers sorted in ascendant order:
.Sp
.Vb 1
\&    qw(25121 25122 25123 25124 25125 25126)
.Ve
.RE
.SS "\fBget_sub_chunks_nums()\fP"
.IX Subsection "get_sub_chunks_nums()"
Returns a list of unique sub chunk numbers for a specific list.
.PP
\&\fB\s-1IMPORTANT\s0\fR: this list should be sorted in ascendant order.
.PP
.Vb 1
\&        my @ids = $storage\->get_sub_chunks_nums(list => \*(Aqgoog\-malware\-shavar\*(Aq);
.Ve
.PP
Arguments
.IP "list" 4
.IX Item "list"
Required. Google Safe Browsing list name
.PP
Return value
.Sp
.RS 4
Array of integers sorted in ascendant order:
.Sp
.Vb 1
\&    qw(37441 37442 37443 37444 37445 37446 37447 37448 37449 37450)
.Ve
.RE
.SS "\fBdelete_add_chunks()\fP"
.IX Subsection "delete_add_chunks()"
Delete add chunks from the local database
.PP
.Vb 1
\&        $storage\->delete_add_chunks(chunknums => [qw/37444 37445 37446/], list => \*(Aqgoog\-malware\-shavar\*(Aq);
.Ve
.PP
Arguments
.IP "chunknums" 4
.IX Item "chunknums"
Required. Array of chunk numbers
.IP "list" 4
.IX Item "list"
Required. Google Safe Browsing list name
.PP
No return value
.SS "\fBdelete_sub_chunks()\fP"
.IX Subsection "delete_sub_chunks()"
Delete sub chunks from the local database
.PP
.Vb 1
\&        $storage\->delete_sub_chunks(chunknums => [qw/37444 37445 37446/], list => \*(Aqgoog\-malware\-shavar\*(Aq);
.Ve
.PP
Arguments
.IP "chunknums" 4
.IX Item "chunknums"
Required. Array of chunk numbers
.IP "list" 4
.IX Item "list"
Required. Google Safe Browsing list name
.PP
No return value
.SS "\fBget_full_hashes()\fP"
.IX Subsection "get_full_hashes()"
Return a list of full hashes
.PP
.Vb 1
\&        $storage\->get_full_hashes(chunknum => 37444, timestamp => time() \- 45 * 60 * 60, list => \*(Aqgoog\-malware\-shavar\*(Aq);
.Ve
.PP
Arguments
.IP "chunknum" 4
.IX Item "chunknum"
Required. Add chunk number
.IP "timestamp" 4
.IX Item "timestamp"
Required. Request hashes retrieved after this timestamp value.
.IP "list" 4
.IX Item "list"
Required. Google Safe Browsing list name
.PP
Return value
.Sp
.RS 4
Array of full hashes:
.Sp
.Vb 1
\&    (HEX, HEX, HEX)
.Ve
.RE
.SS "\fBupdated()\fP"
.IX Subsection "updated()"
Save information about a successful database update
.PP
.Vb 1
\&        $storage\->updated(\*(Aqtime\*(Aq => time(), wait => 1800, list => \*(Aqgoog\-malware\-shavar\*(Aq);
.Ve
.PP
Arguments
.IP "time" 4
.IX Item "time"
Required. Time of the update.
.IP "wait" 4
.IX Item "wait"
Required. Number o seconds to wait before doing the next update.
.IP "list" 4
.IX Item "list"
Required. Google Safe Browsing list name.
.PP
No return value
.SS "\fBupdate_error()\fP"
.IX Subsection "update_error()"
Save information about a failed database update
.PP
.Vb 1
\&        $storage\->update_error(\*(Aqtime\*(Aq => time(), wait => 60, list => \*(Aqgoog\-malware\-shavar\*(Aq, errors => 1);
.Ve
.PP
Arguments
.IP "time" 4
.IX Item "time"
Required. Time of the update.
.IP "wait" 4
.IX Item "wait"
Required. Number o seconds to wait before doing the next update.
.IP "list" 4
.IX Item "list"
Required. Google Safe Browsing list name.
.IP "errors" 4
.IX Item "errors"
Required. Number of errors.
.PP
No return value
.SS "\fBlast_update()\fP"
.IX Subsection "last_update()"
Return information about the last database update
.PP
.Vb 1
\&        my $info = $storage\->last_update(list => \*(Aqgoog\-malware\-shavar\*(Aq);
.Ve
.PP
Arguments
.IP "list" 4
.IX Item "list"
Required. Google Safe Browsing list name.
.PP
Return value
.Sp
.RS 4
Hash reference
.Sp
.Vb 5
\&        {
\&                time    => time(),
\&                wait    => 1800,
\&                errors  => 0
\&        }
.Ve
.RE
.SS "\fBadd_full_hashes()\fP"
.IX Subsection "add_full_hashes()"
Add full hashes to the local database
.PP
.Vb 1
\&        $storage\->add_full_hashes(timestamp => time(), full_hashes => [{chunknum => 2154, hash => HEX, list => \*(Aqgoog\-malware\-shavar\*(Aq}]);
.Ve
.PP
Arguments
.IP "timestamp" 4
.IX Item "timestamp"
Required. Time when the full hash was retrieved.
.IP "full_hashes" 4
.IX Item "full_hashes"
Required. Array of full hashes. Each element is an hash reference in the following format:
.Sp
.Vb 5
\&        {
\&                chunknum        => INTEGER,
\&                hash            => HEX,
\&                list            => \*(Aqgoog\-malware\-shavar\*(Aq
\&        }
.Ve
.PP
No return value
.SS "\fBdelete_full_hashes()\fP"
.IX Subsection "delete_full_hashes()"
Delete full hashes from the local database
.PP
.Vb 1
\&        $storage\->delete_full_hashes(chunknums => [qw/2154 2156 2158/], list => \*(Aqgoog\-malware\-shavar\*(Aq);
.Ve
.PP
Arguments
.IP "chunknums" 4
.IX Item "chunknums"
Required. Array of chunk numbers.
.IP "list" 4
.IX Item "list"
Required. Google Safe Browsing list name.
.PP
No return value
.SS "\fBfull_hash_error()\fP"
.IX Subsection "full_hash_error()"
Save information about failed attempt to retrieve a full hash
.PP
.Vb 1
\&        $storage\->full_hash_error(timestamp => time(), prefix => HEX);
.Ve
.PP
Arguments
.IP "timestamp" 4
.IX Item "timestamp"
Required. Time when the Google returned an error.
.IP "prefix" 4
.IX Item "prefix"
Required. Host prefix.
.PP
No return value
.SS "\fBfull_hash_ok()\fP"
.IX Subsection "full_hash_ok()"
Save information about a successful attempt to retrieve a full hash
.PP
.Vb 1
\&        $storage\->full_hash_ok(timestamp => time(), prefix => HEX);
.Ve
.PP
Arguments
.IP "timestamp" 4
.IX Item "timestamp"
Required. Time when the Google returned an error.
.IP "prefix" 4
.IX Item "prefix"
Required. Host prefix.
.PP
No return value
.SS "\fBget_full_hash_error()\fP"
.IX Subsection "get_full_hash_error()"
Save information about a successful attempt to retrieve a full hash
.PP
.Vb 1
\&        my $info = $storage\->get_full_hash_error(prefix => HEX);
.Ve
.PP
Arguments
.IP "prefix" 4
.IX Item "prefix"
Required. Host prefix.
.PP
Return value
.Sp
.RS 4
undef if there was no error
.Sp
Hash reference in the following format if there was an error:
.Sp
.Vb 4
\&        {
\&                timestamp       => time(),
\&                errors          => 3
\&        }
.Ve
.RE
.SS "\fBget_mac_keys()\fP"
.IX Subsection "get_mac_keys()"
Retrieve the Message Authentication Code (\s-1MAC\s0) keys.
.PP
.Vb 1
\&        my $keys = $storage\->get_mac_keys();
.Ve
.PP
No arguments
.PP
Return value
.Sp
.RS 4
Hash reference in the following format:
.Sp
.Vb 4
\&        {
\&                client_key      => \*(Aq\*(Aq,
\&                wrapped_key     => \*(Aq\*(Aq
\&        }
.Ve
.RE
.SS "\fBdelete_add_keys()\fP"
.IX Subsection "delete_add_keys()"
Add the Message Authentication Code (\s-1MAC\s0) keys.
.PP
.Vb 1
\&        $storage\->delete_mac_keys(client_key => \*(AqKEY\*(Aq, wrapped_key => \*(AqKEY\*(Aq);
.Ve
.PP
Arguments
.IP "client_key" 4
.IX Item "client_key"
Required. Client key.
.IP "wrapped_key" 4
.IX Item "wrapped_key"
Required. Wrapped key.
.PP
No return value
.SS "\fBdelete_mac_keys()\fP"
.IX Subsection "delete_mac_keys()"
Delete the Message Authentication Code (\s-1MAC\s0) keys.
.PP
.Vb 1
\&        $storage\->delete_mac_keys();
.Ve
.PP
No arguments
.PP
No return value
.SS "\fBreset()\fP"
.IX Subsection "reset()"
Remove all local data
.PP
.Vb 1
\&        $storage\->delete_mac_keys();
.Ve
.PP
Arguments
.IP "list" 4
.IX Item "list"
Required. Google Safe Browsing list name.
.PP
No return value
.SH "PRIVATE FUNCTIONS"
.IX Header "PRIVATE FUNCTIONS"
These functions are not intended for debugging purpose.
.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 $storage\->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.
.PP
.Vb 1
\&          print $storage\->ascii_to_hex(\*(Aqascii value\*(Aq);
.Ve
.SH "CHANGELOG"
.IX Header "CHANGELOG"
.IP "0.4" 4
.IX Item "0.4"
Add reset mehtod to empty local database.
.IP "0.3" 4
.IX Item "0.3"
Return the hostkey as part of the add chunks (get_add_chunks).
.IP "0.2" 4
.IX Item "0.2"
Add functions to store and retrieve Message Authentication Code (\s-1MAC\s0) keys.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See Net::Google::SafeBrowsing2 for handling Google Safe Browsing v2.
.PP
See Net::Google::SafeBrowsing2::Sqlite or Net::Google::SafeBrowsing2::MySQL for an example of 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>
.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) 2011 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.