NAME

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

VERSION

version 0.041

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 information about HKP is available at http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00.

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,
                secure => 0, # if 1, use https on port 443
        );

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.

In scalar context, if any keys were 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).

In list context, only the found key-ids are returned or an empty list if none.

Available options

exact

Set the exact 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);

fingerprint

Provide the pull fingerprint in key-id instead of the abbreviated form. Note that not every server supports this keyword.

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.

import_keys($gnupg, @search)

This methods imports keys to an AnyEvent::GnuPG object. @search is a list of email addresses to search for. The method imports all found and valid public keys to the keyring.

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().

When the first parameter is an AnyEvent::GnuPG object, then public keys from the keyring will be submitted to the keyserver. Further arguments restrict the public keys to be exported.

        # export and sumbit all public keys in the keyring
        $hkp->submit($gnupg);
        
        # export and submit only a subset
        $hkp->submit($gnupg, qw( foo@bar.net baz@baf.org ))

error

Returns last error message, if any.

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

FUNCTIONS

discover($email, %options)

Discover a corresponding HKP server via SRV lookup and query the server for public keys. %options will be passed to in index operation of the "query" method.

When no server could be discovered, undef will be returned.

        my $result = WWW::HKP::discover('foo@bar', fingerprint => 1);

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

cpanm WWW::HKP

perl -MCPAN -e shell
install WWW::HKP