riboseinc/hkp_client

= 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.

[source,ruby]
--------------------------------------------------------------------------------
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:

[source,ruby]
--------------------------------------------------------------------------------
[
  {
    :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
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:

[source,ruby]
--------------------------------------------------------------------------------
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.

[source,ruby]
--------------------------------------------------------------------------------
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.

[source,ruby]
--------------------------------------------------------------------------------
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
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

- https://tools.ietf.org/html/draft-shaw-openpgp-hkp-00[HKP protocol definition (IETF draft)]
- http://www.mit.edu/afs/net.mit.edu/project/pks/thesis/paper/thesis.html[A PGP Public Key Server thesis]
- https://www.openpgp.org/about/standard/[More documents on OpenPGP]
- https://sks-keyservers.net/[SKS keyservers]