/ 
WWW-HKP-0.02
River stage zero No dependents
/ WWW::HKP

NAME

WWW::HKP - Interface to HTTP Keyserver Protocol (HKP)

VERSION

Version 0.02

SYNOPSIS

use WWW::HKP;

my $hkp = WWW::HKP->new();

$hkp->query(index => 'foo@bar.baz');
$hkp->query(get => 'DEADBEEF');

DESCRIPTION

This module implements the IETF draft of the OpenPGP HTTP Keyserver Protocol.

More Informationen about HKP is available at http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00.

FUNCTIONS

new([%options])

The new() constructor method instanciates a new WWW::HKP object. The following example shows available options and its default values.

    my $hkp = WWW::HKP->new(
	host => 'localhost',
	port => 11371
    );

In most cases you just need to set the host parameter:

my $hkp = new WWW::HKP host => 'pool.sks-keyservers.net';

query($type => $search [, %options ])

The query() method implements both query operations of HKP: index and get

index operation

$hkp->query(index => 'foo@bar.baz');

The first parameter must be index, the secondend parameter an email-address or key-id.

If any keys where found, a hashref is returned. Otherwise returns undef, an error message can be fetched with $hkp->error().

The returned hashref may look like this:

    {
	'DEADBEEF' => {
	    'algo' => '1',
	    'keylen' => '2048',
	    'created' => '1253025510',
	    'expires' => '1399901151',
	    'deleted' => 0,
	    'expired' => 0,
	    'revoked' => 0,
	    'ok' => 1,
	    'uids' => [
		{
		    'uid' => 'Lorem Ipsum (This is an example) <foo@bar.baz>'
		    'created' => '1253025510',
		    'expires' => '1399901151',
		    'deleted' => 0,
		    'expired' => 0,
		    'revoked' => 0,
		    'ok' => 1
		}
	    ]
	}
    }

The keys of the hashref are key-ids. The meaning of the hashkeys in the seconded level:

algo

The algorithm of the key. The values are described in RFC 2440

keylen

The key length in bytes

created

Creation date of the key, in seconds since 1970-01-01 UTC.

expires

Expiration date of the key

deleted, expired, revoked

Indication details, whether the key is deleted, expired or revoked. If the flag is that, the value is 1, otherwise 0.

ok

The creation date and expiration date is checked against time(). If it doesn't match or any of the flags obove are set, ok will be 0, otherwise 1.

uids

A arrayref of user-ids.

uid

The user-id in common format. It can be parsed by Email::Address for example.

created, expires, deleted, expired, revoked, ok

This fields have the same meaning as described above. The information is taken from the self-signature, if any. created and expired may be undef if not available (e.g. empty string).

Available options

exact

Set the filter_ok parameter to 1 (or any expression that evaluates to true), if you want an exact match of your search expression.

filter_ok

Set the filter_ok parameter to 1 (or any expression that evaluates to true), if you want only valid results. All keys or user IDs having ok-parameter of 0 are ignored.

$hkp->query(index => 'foo@bar.baz', filter_ok => 1);

get operation

$hkp->query(get => 'DEADBEEF');

The operation returns the public key of specified key-id or undef, if not found. Any error messages can be fetched with $hkp->error().

unimplemented operations

A HKP server may implement various other operations. Unimplemented operation cause the module to die with a stack trace.

submit

Submit one or more ASCII-armored version of public keys to the server.

$pubkey = "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...";

$hkp->submit($pubkey);

@pubkeys = ($pubkey1, $pubkey2, ...);

$hkp->submit(@pubkeys);

In case of success, 1 is returned. Otherweise 0 and an error message can be fetched from $hkp-error>.

error

Returns last error message, if any.

$hkp->error; # "404 Not found", for example.

AUTHOR

David Zurborg, <zurborg at cpan.org>

BUGS

Please report any bugs or feature requests trough my project management tool at http://development.david-zurb.org/projects/libwww-hkp-perl/issues/new. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc WWW::HKP

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2014 David Zurborg, all rights reserved.

This program is not really free software; you can redistribute it and/or modify it under certain circumstances. See file LICENSE for details.