The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
WWW-HKP-0.03
River stage zero No dependents
/ WWW::HKP

NAME

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

VERSION

version 0.03

DESCRIPTION

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

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

SYNOPSIS

use WWW::HKP;

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

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

METHODS

new([%options])

The new() constructor method instantiates 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 = WWW::HKP->new(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 undef is returned, 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 hash keys in the second 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 above 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.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/zurborg/libwww-hkp-perl/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

David Zurborg <zurborg@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2014 by David Zurborg.

This is free software, licensed under:

The ISC License