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.

AUTHOR

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

COPYRIGHT AND LICENSE

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.

To install Net::Google::SafeBrowsing2, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::Google::SafeBrowsing2

CPAN shell

perl -MCPAN -e shell
install Net::Google::SafeBrowsing2

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

CONSTRUCTOR

new()

PUBLIC FUNCTIONS

add_chunks()

get_add_chunks()

get_sub_chunks()

get_add_chunks_nums()

get_sub_chunks_nums()

delete_add_chunks()

delete_sub_chunks()

get_full_hashes()

updated()

update_error()

last_update()

add_full_hashes()

delete_full_hashes()

full_hash_error()

full_hash_ok()

get_full_hash_error()

get_mac_keys()

delete_add_keys()

delete_mac_keys()

reset()

PRIVATE FUNCTIONS

hex_to_ascii()

ascii_to_hex()

CHANGELOG

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions