Class KeyRing
In: keyring.rb
Parent: Object

keyring - manage encrypted storage for authentication information

The keyring library stores authentication information such as username and passwords in a keyring directory in encrypted form.

The keyring directory is ~/.keyring by default.

gpg is used for the encryption.

You needs your public and secret key for the encryption. (Use "gpg —gen-key" if you don‘t have one yet.)

How to specify your authentication information in the keyring.

The keyring library uses ASCII armored gpg encrypted file to store passwords and related data.

Comment field is used to select the file.

~/.keyring/foobar.asc :

  -----BEGIN PGP MESSAGE-----
  Version: GnuPG v1.4.5 (GNU/Linux)
  Comment: non-encrypted-prefix-of-the-strings

  ... encrypted-sequence-of-strings ...
  -----END PGP MESSAGE-----

Example 1. TypeKey

The following example stores a username and password for TypeKey. <www.sixapart.jp/typekey/>

 % mkdir ~/.keyring
 % cd ~/.keyring
 % echo TypeKey typekey-username typekey-password |
   gpg --comment TypeKey -e -a --default-recipient-self > typekey.asc

It creates a file ~/.keyring/typekey.asc as follows.

  -----BEGIN PGP MESSAGE-----
  Version: GnuPG v1.4.5 (GNU/Linux)
  Comment: TypeKey

  ... "TypeKey typekey-username typekey-password\n" in encrypted form ...
  -----END PGP MESSAGE-----

Now, KeyRing.with_authinfo("TypeKey") {|username, password| … } can be used to retrieve the typekey-username and typekey-password. It use gpg to decrypt the file. So gpg may ask you a passphrase of your key.

Example 2. HTTP Basic Authentication

 % echo http://www.example.org basic "realm" username password |
   gpg --comment 'http://www.example.org basic "realm" username' -e -a --default-recipient-self > example-org.asc

It creates a file ~/.keyring/example-org.asc as follows.

  -----BEGIN PGP MESSAGE-----
  Version: GnuPG v1.4.5 (GNU/Linux)
  Comment: http://www.example.org basic "realm" username

  ... "http://www.example.org basic "realm" username password\n" in encrypted form ...
  -----END PGP MESSAGE-----

Now, KeyRing.with_authinfo can be used to lookup username and password.

  KeyRing.with_authinfo("http://www.example.org", "basic", "realm", "username") {|password| ... }

It is possible to lookup username AND password as follows.

  KeyRing.with_authinfo("http://www.example.org", "basic", "realm") {|username, password| ... }

It is also possible to lookup realm and authentication scheme.

  KeyRing.with_authinfo("http://www.example.org", "basic") {|realm, username, password| ... }
  KeyRing.with_authinfo("http://www.example.org") {|auth_scheme, realm, username, password| ... }

Keyring Directory Layout and File Format

The keyring directory is ~/.keyring.

~/.keyring may have any number of authentication information file. The file must be named with ".asc" suffix.

The keyring library searches ~/.keyring/*.asc for authentication information. The filename is not important.

The authentication information file should be ASCII armored gpg encrypted file as follows.

~/.keyring/foobar.asc :

  -----BEGIN PGP MESSAGE-----
  Version: GnuPG v1.4.5 (GNU/Linux)
  Comment: non-encrypted-prefix

  ... encrypted-sequence-of-strings ...
  -----END PGP MESSAGE-----

The file should contain Comment field and encrypted contents.

The encrypted contents should be sequence of strings separated by white spaces. (The syntax of the strings is described later.)

  Example: A B C D

The Comment field should contain prefix of the sequence of strings.

  Example: A B C
  Example: A B
  Example: A

Each string in the Comment field can be a hexadecimal SHA256 hash prepended with "sha256:" prefix.

  Example: sha256:559aead08264d5795d3909718cdd05abd49572e84fe55590eef31a88a08fdffd B
  Example: A sha256:df7e70e5021544f4834bbee64a9e3789febc4be81470df629cad6ddb03320a5c
  Example: sha256:559aead08264d5795d3909718cdd05abd49572e84fe55590eef31a88a08fdffd sha256:df7e70e5021544f4834bbee64a9e3789febc4be81470df629cad6ddb03320a5c

A string contained in the Comment field and encrypted contents must be one of following forms.

  • A string not containing a white space and beginning with a digit or alphabet. /[0-9A-Za-z][!-~]*/
  • A string quoted by double quotes "…". The string content may contain printable ASCII character including space and escape sequences \, \" and \xHH. /"((?:[ !#-\[\]-~]|\["\]|\x[0-9a-fA-F][0-9a-fA-F])*)"/
  • A white space is one of space, tab, newline, carriage return, form feed. /\s/

Convention of Authentication Information

Although the keyring library itself doesn‘t define the semantics of the sequence of strings, it is useful to standardize the usage of the strings.

So the keyring library provides convenience methods to make protection domains for TypeKey and HTTP Authentication. They returns a protection domain appropriate for an argument of KeyRing.with_authinfo.

  • KeyRing.typekey_protection_domain

    For TypeKey authentication, protection domain is ["TypeKey"]. The authentication information, username and password, can be stored as follows.

     % echo TypeKey typekey-username typekey-password |
       gpg --comment TypeKey -e -a --default-recipient-self > typekey.asc
    
  • KeyRing.http_protection_domain(uri, scheme, realm)

    For HTTP authentication, protection domain is [canonical-root-URL, scheme, realm]. In Basic authentication, "basic" is used for the scheme.

    The Basic authentication information, username and password, can be stored as follows.

     % echo 'canonical-root-url basic "realm" username password' |
       gpg --comment 'canonical-root-URL basic "realm"' -e -a --default-recipient-self > service.asc
    

Method

Methods

Classes and Modules

Class KeyRing::AuthInfoNotFound

Public Class methods

KeyRing.http_protection_domain returns [canonical-root-URL-of-given-uri, scheme, realm]

KeyRing.with_authinfo takes one or more strings as the argument. protection_domain can be a string or an array of strings.

protection_domain is compared to the Comment fields in ~/.keyring/*.asc. If a matched Comment field is found, the corresponding file is decrypted to obtain the authentication information represented as a sequence of strings using gpg.

KeyRing.with_authinfo yields the sequence of strings excluded with beginning words given with protection_domain.

[Validate]