dispass.el/README.org

#+STARTUP: showall

* dispass.el

  Generate and disperse/dispell passwords.

  ~dispass.el~ is an emacs wrapper around [[http://dispass.babab.nl][DisPass]].

** Installation

   Place this file somewhere on your filesystem, either in your
   ~load-path~ or somewhere else which you will have to add to your
   ~load-path~, like so:

   #+begin_src emacs-lisp
     (add-to-list 'load-path "/location/of/dispass.el")
   #+end_src

   And then ~load~, ~require~ or ~autoload~ it in your emacs init file, for
   example:

   #+begin_src emacs-lisp
     (require 'dispass)
   #+end_src

   /Or/ if you have ~package.el~ with the Marmalade and/or MELPA
   repositories set-up you could use ~package-install-file~.

** Customization

   ~dispass.el~ offers a few customizable settings, all of these can be
   changed using the Emacs customization interface, or of course your
   Emacs init file:

   - =dispass-default-length= :: The default length of passprases
        generated by DisPass, when no length has been specified in
        the labels file for a given label.

   - =dispass-executable= :: The place where the ~dispass~ executable
        script is located.

   - =dispass-labels-executable= :: The place where the ~dispass-labels~
        executable script is located.

** Usage

   Using dispass.el is simple, once installed.

*** Creating and regenerating passphrases

    To create a new passphrase use the command ~dispass-create~, to
    regenerate a previously stored one use ~dispass~.[fn:1]

    When a numeric argument is used when calling either =dispass-create=
    or =dispass=, that argument is sent to the dispass program along
    with the ~-l~ switch. This cuts the length of the password to that
    many characters. For example:

    #+begin_example
      C-5 M-x dispass<RET> test<RET> test<RET>
    #+end_example

    will generate a passphrase of 5 characters for label "test" and
    password "test".

    Once a passphrase has been generated it is inserted into the kill
    ring and the system's clipboard so it can be easily inserted into
    any password field, unfortunately this also makes the generated
    passphrase easy to see in plaintext in the =kill-ring= variable,
    though.

*** Listing/managing labels

    With the command ~dispass-list-labels~ you can get an overview of
    the labels you have stored in your labels file, along with their
    stored meta-data.

    Some label management functions are available in this mode,
    namely adding and removing labels.  See the mode description for
    a list of keybindings.

    Apart from the keybindings available in the list buffer there are
    also the commands ~dispass-add-label~ and ~dispass-remove-label~
    which add and remove a label respectively.

* Footnotes

[fn:1] There is no requirement to first call ~dispass-create~ before
using ~dispass~, but the former asks for confirmation of the password
and newer version of DisPass will automatically store the label and
its meta-data (such as length) in your labels file.