Class | KeyRing |
In: |
keyring.rb
|
Parent: | Object |
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.)
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-----
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.
% 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| ... }
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.
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.
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
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
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.