[chopwood] / chpwd.rst

=======================================
 Chopwood: a password changing service
=======================================

:Author: Mark Wooding

.. sectnum::
	:depth: 3

.. contents::

Introduction
############


Congratulations.  You've just installed Squid, or nginx, or Exim, or
Dovecot, or, well, something.  And it has a marvellous access control
system with users and passwords and stuff.  Yet another little file with
*user*\ **:**\ *password* lines, or maybe a database or something.
Which will all be great.  Just as soon as your users can actually set
passwords, or change them.  Chopwood is a service for letting them do
that.

Of course, you could set up some single sign-on system.  They're quite
complicated.  Also, they probably aren't really what you wanted, because
these various services that you've set up probably have rather different
security levels and it's just not a good plan to feed high-value
credentials to a low-security service.

Chopwood isn't a single sign-on system: in fact it's the opposite.  It's
a tool to let users manage a number of passwords on the same system.

Chopwood has three user interfaces.

  * Local users can communicate with it as a `GNU Userv`_ service.  Most
    of the necessary plumbing is provided.  Local users don't need to do
    authenticate explicitly via Userv, so this is simple, convenient,
    reliable, and relatively pain free.  The only downside is that you
    have to give users shell access to your server.

  * Remote users can reach it using SSH, using OpenSSH_\ 's forced
    command feature.  Maintaining the ``authorized_keys`` file is a bit
    of a nuisance, especially if they need to keep changing their keys
    [#keymgmt]_.

  * Remote users can also get to it with a web browser, using good
    old-fashioned CGI.  Unfortunately, we don't have a better approach
    for authenticating users than more passwords.  Of course, Chopwood
    can manage its own password, but that's not really the point.

.. [#keymgmt] Maybe someone should build a similar tool for managing
	      authorized keys for SSH services.

.. _GNU Userv: http://www.gnu.org/software/userv/

.. _OpenSSH: http://www.openssh.org/


Installation
############


Chopwood is written in Python, and doesn't depend on any additional
libraries.  The program is tested with Python 2.7, but I expect that it
works with Python 2.6, and it's intended to work with 2.5 too.

You'll also need GNU Make and at least of

  * GNU Userv;

  * OpenSSH, or some other SSH server with a forced-command feature;

  * a web server which can run CGI scripts as some other user; or

  * some willingness to get your hands dirty hooking Chopwood up to some
    other interface.

Chopwood is designed to be run from a Git working tree.  You can clone
it from

  * <git://git.distorted.org.uk/~mdw/chopwood/>
  * <http://git.distorted.org.uk/~mdw/chopwood/>
  * <https://git.distorted.org.uk/~mdw/chopwood/>

I recommend that you use the HTTPS transport if you can; unfortunately,
at the moment, that server doesn't have a certificate from a well-known
CA.  Please check the certificate against the TLSA record, which is
secured using DNSsec.

The working tree needs a very quick build step, which you can accomplish
by running ::

	$ make

This does three things:

  * it generates the ``auto.py`` file which tells Chopwood its
    installation directory, version number, and various other
    automatically discovered things; and

  * it generates the static files for the web interface; and

  * it causes Python to byte-compile the various Python modules.


Basic configuration
-------------------

Great so far.  Now it's time to shut up the warning about not having a
configuration file.  


Configuration parameters
------------------------

**ALLOWOP**:
	An object holding three boolean attributes.  If **ALLOWOP.set**
	is true then users are allowed to set passwords to values of
	their choosing; if **ALLOWOP.reset** is true then they're
	allowed to ask for passwords to be reset to a value chosen by
	Chopwood; and if **ALLOWOP.clear** is true then they're allowed
	to clear passwords, leaving them unable to log into the
	applicable service.

**AUTHHASH**:
	The hash function to use when making HTTP authentication
	cookies.  This should be a function (or other callable) which
	behaves like one of the **hashlib** hash functions.  The default
	is **hashlib**.\ **sha256**, which is likely to be good enough.

**DB**:
	The database which Chopwood should use to store its state.  This
	should be a pair (*module*, *modargs*), where *module* names a
	PEP 249 database module and *modargs* is a sequence or
	dictionary of arguments to pass to its **connect** function.
	The default is to create a SQLite3 database in Chopwood's
	working directory.

**HASH**:
	The password hash to use for Chopwood's own user database.  See
	`Chopwood password hashes`_ for more information about the
	password hashes provided and the protocol in which hash objects
	participate.  The default is to use a **crypt**\ (3)-style hash
	with MD5.

**LOCKDIR**:
	A string naming the directory in which Chopwood should store
	its lockfiles.

**RQCLASS** and **RQMIXIN**:
	Classes used to determine password policies.  See `Applying
	local policy`_ for details.  The default is to allow everything.

**SCRIPT_NAME**:
	A (possibly relative) URL referring to Chopwood's CGI script.
	This will usually be set appropriately by the webserver, but
	this setting exists so that you can override it if it's wrong.

**SECRETFRESH**:
	The time in seconds for which a cookie authentication key is
	used for issuing fresh cookies.  After this, a new key is
	generated, and the old ones kept and used to validate existing
	cookies until their lifetime expires (see **SECRETLIFE** below).
	The default is five minutes.

**SECRETLIFE**:
	The total lifetime, in seconds, of a key used to ensure
	cryptographically the integrity of session cookies.  See
	**SECRETFRESH** above.  Users' browsers are instructed to
	discard the cookie after `**SECRETLIFE** - **SECRETFRESH**`:m:
	seconds.  The default is half an hour.

**STATIC**:
	The URL prefix for static content: the location of static
	resource *file* is reported to the user agent as *STATIC*\
	**/**\ *file*.  The default is to attempt (see **SCRIPT_NAME**
	above) to link back to Chopwood's CGI script to generate the
	content dynamically.  You can improve responsiveness by
	configuring Chopwood and your webserver to serve actual static
	files instead.


..  LocalWords:  nginx www userv CGI keymgmt https TLSA py ALLOWOP sha
..  LocalWords:  AUTHHASH RQCLASS RQMIXIN modargs
Commit	Line	Data
8f6848e2 MW	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