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


version 0.041


    use WWW::HKP;
    my $hkp = WWW::HKP->new();
    $hkp->query(index => 'foo@bar.baz');
    $hkp->query(get => 'DEADBEEF');


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

More information about HKP is available at



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 => '');

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:


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


The key length in bytes.


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


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.


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.


A arrayref of user-ids.


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


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


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);

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 one or more ASCII-armored version of public keys to the server.

    $pubkey = "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...";
    @pubkeys = ($pubkey1, $pubkey2, ...);

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
        # export and submit only a subset
        $hkp->submit($gnupg, qw( ))


Returns last error message, if any.

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


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);


Please report any bugs or feature requests on the bugtracker website

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.


David Zurborg <>


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

This is free software, licensed under:

  The ISC License