chiark - git - mdw - chopwood/blob - chpwd.rst

   1 =======================================
   2  Chopwood: a password changing service
   3 =======================================
   4
   5 :Author: Mark Wooding
   6
   7 .. sectnum::
   8         :depth: 3
   9
  10 .. contents::
  11
  12 Introduction
  13 ############
  14
  15
  16 Congratulations.  You've just installed Squid, or nginx, or Exim, or
  17 Dovecot, or, well, something.  And it has a marvellous access control
  18 system with users and passwords and stuff.  Yet another little file with
  19 *user*\ **:**\ *password* lines, or maybe a database or something.
  20 Which will all be great.  Just as soon as your users can actually set
  21 passwords, or change them.  Chopwood is a service for letting them do
  22 that.
  23
  24 Of course, you could set up some single sign-on system.  They're quite
  25 complicated.  Also, they probably aren't really what you wanted, because
  26 these various services that you've set up probably have rather different
  27 security levels and it's just not a good plan to feed high-value
  28 credentials to a low-security service.
  29
  30 Chopwood isn't a single sign-on system: in fact it's the opposite.  It's
  31 a tool to let users manage a number of passwords on the same system.
  32
  33 Chopwood has three user interfaces.
  34
  35   * Local users can communicate with it as a `GNU Userv`_ service.  Most
  36     of the necessary plumbing is provided.  Local users don't need to do
  37     authenticate explicitly via Userv, so this is simple, convenient,
  38     reliable, and relatively pain free.  The only downside is that you
  39     have to give users shell access to your server.
  40
  41   * Remote users can reach it using SSH, using OpenSSH_\ 's forced
  42     command feature.  Maintaining the ``authorized_keys`` file is a bit
  43     of a nuisance, especially if they need to keep changing their keys
  44     [#keymgmt]_.
  45
  46   * Remote users can also get to it with a web browser, using good
  47     old-fashioned CGI.  Unfortunately, we don't have a better approach
  48     for authenticating users than more passwords.  Of course, Chopwood
  49     can manage its own password, but that's not really the point.
  50
  51 .. [#keymgmt] Maybe someone should build a similar tool for managing
  52               authorized keys for SSH services.
  53
  54 .. _GNU Userv: http://www.gnu.org/software/userv/
  55
  56 .. _OpenSSH: http://www.openssh.org/
  57
  58
  59
  60 Installation
  61 ############
  62
  63
  64 Chopwood is written in Python, and doesn't depend on any additional
  65 libraries.  The program is tested with Python 2.7, but I expect that it
  66 works with Python 2.6, and it's intended to work with 2.5 too.
  67
  68 You'll also need GNU Make and at least of
  69
  70   * GNU Userv;
  71
  72   * OpenSSH, or some other SSH server with a forced-command feature;
  73
  74   * a web server which can run CGI scripts as some other user; or
  75
  76   * some willingness to get your hands dirty hooking Chopwood up to some
  77     other interface.
  78
  79 Chopwood is designed to be run from a Git working tree.  You can clone
  80 it from
  81
  82   * <git://git.distorted.org.uk/~mdw/chopwood/>
  83   * <http://git.distorted.org.uk/~mdw/chopwood/>
  84   * <https://git.distorted.org.uk/~mdw/chopwood/>
  85
  86 I recommend that you use the HTTPS transport if you can; unfortunately,
  87 at the moment, that server doesn't have a certificate from a well-known
  88 CA.  Please check the certificate against the TLSA record, which is
  89 secured using DNSsec.
  90
  91 The working tree needs a very quick build step, which you can accomplish
  92 by running ::
  93
  94         $ make
  95
  96 This does three things:
  97
  98   * it generates the ``auto.py`` file which tells Chopwood its
  99     installation directory, version number, and various other
 100     automatically discovered things; and
 101
 102   * it generates the static files for the web interface; and
 103
 104   * it causes Python to byte-compile the various Python modules.
 105
 106
 107 Basic configuration
 108 -------------------
 109
 110 Great so far.  Now it's time to shut up the warning about not having a
 111 configuration file.
 112
 113
 114 Configuration parameters
 115 ------------------------
 116
 117 **ALLOWOP**:
 118         An object holding three boolean attributes.  If **ALLOWOP.set**
 119         is true then users are allowed to set passwords to values of
 120         their choosing; if **ALLOWOP.reset** is true then they're
 121         allowed to ask for passwords to be reset to a value chosen by
 122         Chopwood; and if **ALLOWOP.clear** is true then they're allowed
 123         to clear passwords, leaving them unable to log into the
 124         applicable service.
 125
 126 **AUTHHASH**:
 127         The hash function to use when making HTTP authentication
 128         cookies.  This should be a function (or other callable) which
 129         behaves like one of the **hashlib** hash functions.  The default
 130         is **hashlib**.\ **sha256**, which is likely to be good enough.
 131
 132 **DB**:
 133         The database which Chopwood should use to store its state.  This
 134         should be a pair (*module*, *modargs*), where *module* names a
 135         PEP 249 database module and *modargs* is a sequence or
 136         dictionary of arguments to pass to its **connect** function.
 137         The default is to create a SQLite3 database in Chopwood's
 138         working directory.
 139
 140 **HASH**:
 141         The password hash to use for Chopwood's own user database.  See
 142         `Chopwood password hashes`_ for more information about the
 143         password hashes provided and the protocol in which hash objects
 144         participate.  The default is to use a **crypt**\ (3)-style hash
 145         with MD5.
 146
 147 **LOCKDIR**:
 148         A string naming the directory in which Chopwood should store
 149         its lockfiles.
 150
 151 **RQCLASS** and **RQMIXIN**:
 152         Classes used to determine password policies.  See `Applying
 153         local policy`_ for details.  The default is to allow everything.
 154
 155 **SCRIPT_NAME**:
 156         A (possibly relative) URL referring to Chopwood's CGI script.
 157         This will usually be set appropriately by the webserver, but
 158         this setting exists so that you can override it if it's wrong.
 159
 160 **SECRETFRESH**:
 161         The time in seconds for which a cookie authentication key is
 162         used for issuing fresh cookies.  After this, a new key is
 163         generated, and the old ones kept and used to validate existing
 164         cookies until their lifetime expires (see **SECRETLIFE** below).
 165         The default is five minutes.
 166
 167 **SECRETLIFE**:
 168         The total lifetime, in seconds, of a key used to ensure
 169         cryptographically the integrity of session cookies.  See
 170         **SECRETFRESH** above.  Users' browsers are instructed to
 171         discard the cookie after `**SECRETLIFE** - **SECRETFRESH**`:m:
 172         seconds.  The default is half an hour.
 173
 174 **STATIC**:
 175         The URL prefix for static content: the location of static
 176         resource *file* is reported to the user agent as *STATIC*\
 177         **/**\ *file*.  The default is to attempt (see **SCRIPT_NAME**
 178         above) to link back to Chopwood's CGI script to generate the
 179         content dynamically.  You can improve responsiveness by
 180         configuring Chopwood and your webserver to serve actual static
 181         files instead.
 182
 183
 184 ..  LocalWords:  nginx www userv CGI keymgmt https TLSA py ALLOWOP sha
 185 ..  LocalWords:  AUTHHASH RQCLASS RQMIXIN modargs