Provided by: libnet-google-safebrowsing2-perl_1.07-6_all bug

NAME

       Net::Google::SafeBrowsing2::Storage - Base class for storing the Google Safe Browsing v2
       database

SYNOPSIS

         package Net::Google::SafeBrowsing2::Sqlite;

         use base 'Net::Google::SafeBrowsing2::Storage';

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.

       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.

CONSTRUCTOR

   new()
         Create a Net::Google::SafeBrowsing2::Storage object

         my $storage   => Net::Google::SafeBrowsing2::Storage->new();

PUBLIC FUNCTIONS

   add_chunks()
       Add chunk information to the local database

         $storage->add_chunks(type => 'a', chunknum => 2154, chunks => [{host => HEX, prefix => ''}], list => 'goog-malware-shavar');

       Does not return anything.

       Arguments

       type
           Required. Type of chunk: 'a' (add chunk) or 's' (sub chunk).

       chunknum
           Required. Chunk number.

       chunks
           Required. Array of chunks

           For add chunks, each element of the array is an hash reference in the following
           format:

             {
               host => HEX,
                   prefix => HEX
             }

           For sub chunks, each element of the array is an hash reference in the following
           format:

             {
               host => HEX,
                   prefix => HEX,
               add_chunknum => INTEGER
             }

       list
           Required. Google Safe Browsing list name.

   get_add_chunks()
       Returns a list of chunks for a given host key for all lists.

               my @chunks = $storage->get_add_chunks(hostkey => HEX);

       Arguments

       hostkey.
           Required. Host key.

       Return value

           Array of add chunks in the same format as described above:

               (
                           {
                                   chunknum        => 25121,
                                   hostkey         => hex('12345678'),
                                   prefix          => '',
                                   list            => 'goog-malware-shavar'
                           },
                           {
                                   chunknum        => '25121',
                                   hostkey         => hex('12345678'),
                                   prefix          => hex('2fc96b9f'),
                                   list            => 'goog-malware-shavar'
                           },
                   );

   get_sub_chunks()
       Returns a list of sub chunks for a given host key for all lists.

               my @chunks = $storage->get_sub_chunks(hostkey => HEX);

       Arguments

       hostkey
           Required. Host key.

       Return value

           Array of add chunks in the same format as described above:

               (
                           {
                                   chunknum        => 37441,
                                   prefix          => '',
                                   addchunknum     => 23911,
                                   list            => 'goog-malware-shavar'
                           },
                           {
                                   chunknum        => 37441,
                                   prefix          => '',
                                   addchunknum     => 22107,
                                   list            => 'goog-malware-shavar'
                           },
                   );

   get_add_chunks_nums()
       Returns a list of unique add chunk numbers for a specific list.

       IMPORTANT: this list should be sorted in ascendant order.

               my @ids = $storage->get_add_chunks_nums(list => 'goog-malware-shavar');

       Arguments

       list
           Required. Google Safe Browsing list name

       Return value

           Array of integers sorted in ascendant order:

               qw(25121 25122 25123 25124 25125 25126)

   get_sub_chunks_nums()
       Returns a list of unique sub chunk numbers for a specific list.

       IMPORTANT: this list should be sorted in ascendant order.

               my @ids = $storage->get_sub_chunks_nums(list => 'goog-malware-shavar');

       Arguments

       list
           Required. Google Safe Browsing list name

       Return value

           Array of integers sorted in ascendant order:

               qw(37441 37442 37443 37444 37445 37446 37447 37448 37449 37450)

   delete_add_chunks()
       Delete add chunks from the local database

               $storage->delete_add_chunks(chunknums => [qw/37444 37445 37446/], list => 'goog-malware-shavar');

       Arguments

       chunknums
           Required. Array of chunk numbers

       list
           Required. Google Safe Browsing list name

       No return value

   delete_sub_chunks()
       Delete sub chunks from the local database

               $storage->delete_sub_chunks(chunknums => [qw/37444 37445 37446/], list => 'goog-malware-shavar');

       Arguments

       chunknums
           Required. Array of chunk numbers

       list
           Required. Google Safe Browsing list name

       No return value

   get_full_hashes()
       Return a list of full hashes

               $storage->get_full_hashes(chunknum => 37444, timestamp => time() - 45 * 60 * 60, list => 'goog-malware-shavar');

       Arguments

       chunknum
           Required. Add chunk number

       timestamp
           Required. Request hashes retrieved after this timestamp value.

       list
           Required. Google Safe Browsing list name

       Return value

           Array of full hashes:

               (HEX, HEX, HEX)

   updated()
       Save information about a successful database update

               $storage->updated('time' => time(), wait => 1800, list => 'goog-malware-shavar');

       Arguments

       time
           Required. Time of the update.

       wait
           Required. Number o seconds to wait before doing the next update.

       list
           Required. Google Safe Browsing list name.

       No return value

   update_error()
       Save information about a failed database update

               $storage->update_error('time' => time(), wait => 60, list => 'goog-malware-shavar', errors => 1);

       Arguments

       time
           Required. Time of the update.

       wait
           Required. Number o seconds to wait before doing the next update.

       list
           Required. Google Safe Browsing list name.

       errors
           Required. Number of errors.

       No return value

   last_update()
       Return information about the last database update

               my $info = $storage->last_update(list => 'goog-malware-shavar');

       Arguments

       list
           Required. Google Safe Browsing list name.

       Return value

           Hash reference

                   {
                           time    => time(),
                           wait    => 1800,
                           errors  => 0
                   }

   add_full_hashes()
       Add full hashes to the local database

               $storage->add_full_hashes(timestamp => time(), full_hashes => [{chunknum => 2154, hash => HEX, list => 'goog-malware-shavar'}]);

       Arguments

       timestamp
           Required. Time when the full hash was retrieved.

       full_hashes
           Required. Array of full hashes. Each element is an hash reference in the following
           format:

                   {
                           chunknum        => INTEGER,
                           hash            => HEX,
                           list            => 'goog-malware-shavar'
                   }

       No return value

   delete_full_hashes()
       Delete full hashes from the local database

               $storage->delete_full_hashes(chunknums => [qw/2154 2156 2158/], list => 'goog-malware-shavar');

       Arguments

       chunknums
           Required. Array of chunk numbers.

       list
           Required. Google Safe Browsing list name.

       No return value

   full_hash_error()
       Save information about failed attempt to retrieve a full hash

               $storage->full_hash_error(timestamp => time(), prefix => HEX);

       Arguments

       timestamp
           Required. Time when the Google returned an error.

       prefix
           Required. Host prefix.

       No return value

   full_hash_ok()
       Save information about a successful attempt to retrieve a full hash

               $storage->full_hash_ok(timestamp => time(), prefix => HEX);

       Arguments

       timestamp
           Required. Time when the Google returned an error.

       prefix
           Required. Host prefix.

       No return value

   get_full_hash_error()
       Save information about a successful attempt to retrieve a full hash

               my $info = $storage->get_full_hash_error(prefix => HEX);

       Arguments

       prefix
           Required. Host prefix.

       Return value

           undef if there was no error

           Hash reference in the following format if there was an error:

                   {
                           timestamp       => time(),
                           errors          => 3
                   }

   get_mac_keys()
       Retrieve the Message Authentication Code (MAC) keys.

               my $keys = $storage->get_mac_keys();

       No arguments

       Return value

           Hash reference in the following format:

                   {
                           client_key      => '',
                           wrapped_key     => ''
                   }

   delete_add_keys()
       Add the Message Authentication Code (MAC) keys.

               $storage->delete_mac_keys(client_key => 'KEY', wrapped_key => 'KEY');

       Arguments

       client_key
           Required. Client key.

       wrapped_key
           Required. Wrapped key.

       No return value

   delete_mac_keys()
       Delete the Message Authentication Code (MAC) keys.

               $storage->delete_mac_keys();

       No arguments

       No return value

   reset()
       Remove all local data

               $storage->delete_mac_keys();

       Arguments

       list
           Required. Google Safe Browsing list name.

       No return value

PRIVATE FUNCTIONS

       These functions are not intended for debugging purpose.

   hex_to_ascii()
       Transform hexadecimal strings to printable ASCII strings. Used mainly for debugging.

         print $storage->hex_to_ascii('hex value');

   ascii_to_hex()
       Transform ASCII strings to hexadecimal strings.

                 print $storage->ascii_to_hex('ascii value');

CHANGELOG

       0.4 Add reset mehtod to empty local database.

       0.3 Return the hostkey as part of the add chunks (get_add_chunks).

       0.2 Add functions to store and retrieve Message Authentication Code (MAC) keys.

SEE ALSO

       See Net::Google::SafeBrowsing2 for handling Google Safe Browsing v2.

       See Net::Google::SafeBrowsing2::Sqlite or Net::Google::SafeBrowsing2::MySQL for an example
       of storing and managing the Google Safe Browsing database.

       Google Safe Browsing v2 API:
       <http://code.google.com/apis/safebrowsing/developers_guide_v2.html>

AUTHOR

       Julien Sobrier, <jsobrier@zscaler.com> or <julien@sobrier.net>

COPYRIGHT AND LICENSE

       Copyright (C) 2011 by Julien Sobrier

       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.