add a README, adapted from the legacy version

README.rst

@@ -0,0 +1,112 @@
+=====================
+mozilla-gnome-keyring
+=====================
+
+A mozilla extension to store passwords and form logins in gnome-keyring
+
+This replaces the default password manager in Firefox and Thunderbird
+with an implementation which uses Gnome Keyring. This is a centralised
+system-based password manager, which is more simple to handle than
+per-application management.
+
+You need ``libgnome-keyring0`` to be installed, for this extension to
+work. When this extension is enabled, passwords stored in the default
+password manager are not accessible. See `migrating old passwords`_
+for an efficient set of instructions to manually work around this.
+
+You can find more technical information on `bugzilla issue`_ or on the
+`github project pages`_.
+
+.. _bugzilla issue: https://bugzilla.mozilla.org/show_bug.cgi?id=309807
+.. _github project pages: https://github.com/swick/mozilla-gnome-keyring
+
+=====
+Usage
+=====
+
+You can change the keyring in which passwords are saved by creating or
+editing the preference item ``extensions.gnome-keyring.keyringName``.
+The default keyring is ``mozilla``. This is a per-profile setting, so if
+you don't manually change it, all profiles will share the same keyring.
+
+You can backup your passwords easily, separately from the rest of your
+mozilla profile. Your keyrings are stored ``~/.gnome2/keyrings`` - even
+gnome-keyring 3.0-3.16 does this, though this may change in the future.
+
+You can also take advantage of the more fine-tuned keyring management
+features of gnome-keyring, such as:
+
+* No need to prompt for password, if you store in the ``login`` keyring
+  and the password for that keyring is the same as your login password.
+* If the keyring is already open, don't need to prompt for a password
+  each time you start Firefox or Thunderbird.
+* You can explicitly re-lock the keyring when you feel you need to.
+* In gnome-keyring 3, the keyring password prompt disables keyboard
+  input to other windows, so you don't need to worry about accidentally
+  typing it somewhere you shouldn't
+
+Note: gnome-keyring stores the passwords encrypted on permanent storage
+but it keeps unlocked passwords in memory without encryption. As a
+result, programs with access to the memory space of gnome-keyring (such
+as debuggers and applications running as root) may be able to extract
+the passwords. The same applies to the default Firefox and Thunderbird
+implementations, so this extension should not be any less secure.
+
+=================================
+Non-working cases and workarounds
+=================================
+
+Passwords will not be saved or filled in if:
+
+* the username or password element has attribute ``autocomplete="on"``
+
+  * workaround: delete the attribute using the DOM inspector
+
+* the username or password element is already filled in by the page
+
+  * see https://bugzilla.mozilla.org/show_bug.cgi?id=618698
+  * note: not a browser bug
+
+* (mozilla bug): the page is XML+XSLT
+
+  * see https://bugzilla.mozilla.org/show_bug.cgi?id=354706
+
+Actually, these issues are all browser issues, and not directly fixable
+by this extension.
+
+=======================
+Migrating old passwords
+=======================
+
+Currently there is no migration facility. If you have many passwords in
+the default password manager, you'll need to manually transfer them
+to gnome-keyring:
+
+* Create a TEMP profile, and install/enable this extension in it.
+* In the TEMP profile, edit ``extensions.gnome-keyring.keyringName`` to
+  whatever you eventually want to use.
+* Restart the TEMP profile for setting changes to take effect.
+* Open up the MAIN profile using ``firefox -no-remote -P <MAIN name>``
+  so that you have *both* profiles open.
+* Open up the password manager on the MAIN profile.
+* For each website listed:
+
+  * Right-click on its entry and select "copy password".
+  * Visit the website in the TEMP profile and login again, which should
+    trigger the "save password" prompt.
+
+* Once you're done, you can close the TEMP profile and delete it.
+* In the MAIN profile, install/enable this extension, and edit
+  ``extensions.gnome-keyring.keyringName`` to whatever you chose before.
+* Restart the MAIN profile for setting changes to take effect.
+
+The old data of the default password manager remains untouched, so you
+also need to delete that manually if you want to. This is done by going
+to your profile folder, and deleting ``key3.db`` and ``signons.sqlite``.
+After deleting, the data may still be forensically retrievable from your
+disk, but if you were protecting it with a master password, this data
+would still be be encrypted.
+
+Deleting old data will also clear the master password for the default
+password manager. If you don't clear it, you'll still be asked for it
+when you choose to "show passwords", even if this extension is active.