How to use the Moonshot Text UI
--------------------------------------
This UI version comes with support for text interface. In order to make
use of it with either the ENCRYPTED_FLAT_FILE or the LIBSECRET/GNOME_KEYRING
backends, some conditions need to be met:

1) For the ENCRYPTED_FLAT_FILE backend, an authentication an encryption key
   must be defined. This can be achieved by using one of two approaches:
   a) A key named "moonshot-ui" is defined in the kernel session keyring.
      This can be easily achieved by using the keyctl command, where $PASSWD is
      the encryption key:
      - Option 1: key is provided directly in the command line:
        "keyctl add user moonshot-ui $PASSWD @s"
      - Option 2: key is introduced interactively (use Ctrl+D to finish):
        "keyctl padd user moonshot-ui @s"

   b) The environment variable MOONSHOT_UI_PWD is set.

   When both a) and b) are used at the same time, b) is used.

   When the key is found, the UI will use it as the master password to decrypt
   the AES-GCM encrypted credential file, located in
   $HOME/.local/share/moonshot-ui/identities.txt.aes

2) If the GNOME Keyring backend is to be used (not recommended, unless you
   really need it), a DBUS session MUST exist, so the Moonshot UI can connect
   to it when an application asks for an identity to be used. Besides, an
   unlocked instance of GNOME Keyring must be running and associated to the
   same DBUS session.

   This can be achieved by executing the following commands, where $PASSWD is
   the password for unlocking the default keyring:
   $> eval "$(dbus-launch --sh-syntax)"
   $> echo -n $PASSWD | gnome-keyring-daemon --unlock
   $> eval "$(/usr/bin/gnome-keyring-daemon --start)"

   For convenience, we ship a script that performs these steps. You can find it
   in: /usr/share/moonshot-ui/enable-moonshot-txt-ui-gnome-keyring

Requirements for using GNOME keyring
-------------------------------------
For Moonshot to work properly with GNOME keyring, a default keyring MUST exist.
You may use the "seahorse" application to check the existence of this keyring,
as well as to create it if it does not exist already.

Also, the GTK version of the UI will automatically create a default keyring
called "login" upon start if a default keyring is not found.

Using GNOME keyring and PAM
---------------------------
You may use PAM to automatically unlock the user's keyring during console
and/or SSH login. In this case, a default keyring called "login" would
automatically be created by PAM if it does not exist.

In this case, the "gnome-keyring-daemon --unlock" described above is not
required, although it would still be required to start the daemon manually.

Known issues of GNOME keyring with CentOS 6
-----------------------------------------
In CentOS 6 the keyring will not be unlocked neither with the "--unlock"
parameter nor using the PAM method. This is due to a misbehaviour of GNOME
keyring in these distribution and has nothing to do with Moonshot.

As a work around, we ship a tool called "moonshot-keyring-tool" that can be
used for that purpose.