HKP Client

HKP Client is a minimalist HKP (OpenPGP HTTP Keyserver Protocol) client, which queries PGP public keyservers, and downloads public keys. It does not support submitting keys to keyserver.

Note	This gem registers hkp, and hkps URI schemes (adds them to URI.scheme_list).

Usage

Searching

Searching by some criteria. Returns search results as an array of arrays.

The search term does not have to be an e-mail address, but that’s

For exact searches, an exact option can be set to true. The meaning of "exact" is not defined by standard, and may be ignored by servers.

HkpClient.search "linus@example.com"
HkpClient.search "linus@example.com", exact: true

Search operations returns an array of hashes. In this case, it is a one-element array:

[
  {
    :key_id=>"06DA6D18CED048CE87E3E3A01CBBDA571B331AB5",
    :algorithm=>"1",
    :key_length=>"2048",
    :creation_date=>"1507718293",
    :expiration_date=>nil,
    :flags=>nil,
    :uids=>[
      {
        :name=>"Linus Torvalds (Example) <linus@example.com>",
        :creation_date=>"1507718293",
        :expiration_date=>nil,
        :flags=>nil
      }
    ]
  }
]

Each array item describes a primary key uploaded to keyserver, and is associated with one or more UIDs. For field descriptions, refer to HKP draft, section 5.2.

UID’s name is already percent-decoded. Other values may require parsing or casting (e.g. timestamps and numbers).

Search results may include expired keys. If that’s unwanted, these keys must be filtered out by user.

Fetching keys

Operation returns the ASCII-armored keyring as defined in RFC 2440, section 11.1, or nil.

For example, executing following snippet:

HkpClient.get "linus@example.com"

will return string similar to:

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: SKS 1.1.6
Comment: Hostname: pgp.lehigh.edu

mQENBFnd9JUBCAC1NMfsImuRAUcsKEjdLlSj0THHNytUDE8CB2I728gJAeixdZMEcPpRKHfc
BXjW+Q864S4yEY4xgaboFkg/qABA/o0PWzZn2AzhvD5gzrfpfvK4BMrgOtPya7MySgImG1NC
UYqj2vvJt4/bh8MWxSqvADB3SfLNueBQGvISeGwss9kYHEqoP0lxNSEJPJJpLKeqSov7mZOz
(…)
c2gFngOSVOrxJswb8/BUkA==
=jGC1
-----END PGP PUBLIC KEY BLOCK-----

Arbitrary queries

When above two methods are not flexible enough, a #query method can be called. It returns an instance of Faraday::Response. All the arguments become query string parameters (with exception of keyserver, which is described in the next section).

For example, a following snippet performs a vindex operation for linus@example.com query. The mr option specifies that search results should be presented in a machine-readable format. By default, a human-readable format is used, typically HTML.

HkpClient.query(op: "vindex", search: "linus@example.com", options: "mr")

Using custom keyserver

A keyserver option can be passed to either #search, #get, or #query method. Accepted URI schemes are http, https, hkp, and hkps.

TODO: Easy support for custom certificates.

HkpClient.get "linus@example.com", keyserver: "hkp://server.you.want:8888"

Contributing

First, thank you for contributing! We love pull requests from everyone. By participating in this project, you hereby grant Ribose Inc. the right to grant or transfer an unlimited number of non exclusive licenses or sub-licenses to third parties, under the copyright covering the contribution to use the contribution by all means.

Here are a few technical guidelines to follow:

1. Open an issue to discuss a new feature prior implementing it.

2. Write tests for new features or bugfixes.

3. Make sure the entire test suite passes locally and on CI.

4. Follow our style guide (you can validate your contribution locally with Rubocop, also Hound CI will report any offences when you open a pull request).

Credits

This gem is developed, maintained and funded by Ribose Inc.

License

The gem is available as open source under the terms of the MIT License.

Resources

• HKP protocol definition (IETF draft)

• A PGP Public Key Server thesis

• More documents on OpenPGP

• SKS keyservers