= HKP Client
image:https://img.shields.io/gem/v/hkp_client.svg["Gem Version", link="https://rubygems.org/gems/hkp_client"] image:https://img.shields.io/travis/riboseinc/hkp_client/master.svg["Build Status", link="https://travis-ci.org/riboseinc/hkp_client"] image:https://img.shields.io/codecov/c/github/riboseinc/hkp_client.svg["Test Coverage", link="https://codecov.io/gh/riboseinc/hkp_client"] image:https://img.shields.io/codeclimate/maintainability/riboseinc/hkp_client.svg["Maintainability", link="https://codeclimate.com/github/riboseinc/hkp_client/maintainability"]
:source-highlighter: pygments
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.
Search operations returns an array of hashes. In this case, it is a one-element array:
Each array item describes a primary key uploaded to keyserver, and is associated with one or more UIDs. For field descriptions, refer to https://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#section-5.2[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
https://tools.ietf.org/html/rfc2440#section-11.1[RFC 2440, section 11.1],
or nil
.
For example, executing following snippet:
will return string similar to:
-----BEGIN PGP PUBLIC KEY BLOCK----- Version: SKS 1.1.6 Comment: Hostname: pgp.lehigh.edu
=== 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.
=== 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.
== 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:
== Credits
This gem is developed, maintained and funded by https://www.ribose.com[Ribose Inc].
== License
The gem is available as open source under the terms of the https://opensource.org/licenses/MIT[MIT License].
== Resources