Files
@ f629e9a0c376
Branch filter:
Location: kallithea/docs/installation.rst
f629e9a0c376
6.8 KiB
text/prs.fallenstein.rst
auth: secure password reset implementation
This is a better implementation of password reset function, which
doesn't involve sending a new password to the user's email address
in clear text, and at the same time is stateless.
The old implementation generated a new password and sent it
in clear text to whatever email assigned to the user currently,
so that any user, possibly unauthenticated, could request a reset
for any username or email. Apart from potential insecurity, this
made it possible for anyone to disrupt users' workflow by repeatedly
resetting their passwords.
The idea behind this implementation is to generate
an authentication token which is dependent on the user state
at the time before the password change takes place, so the token
is one-time and can't be reused, and also to bind the token to
the browser session.
The token is calculated as SHA1 hash of the following:
* user's identifier (number, not a name)
* timestamp
* hashed user's password
* session identifier
* per-application secret
We use numeric user's identifier, as it's fixed and doesn't change,
so renaming users doesn't affect the mechanism. Timestamp is added
to make it possible to limit the token's validness (currently hard
coded to 24h), and we don't want users to be able to fake that field
easily. Hashed user's password is needed to prevent using the token
again once the password has been changed. Session identifier is
an additional security measure to ensure someone else stealing the
token can't use it. Finally, per-application secret is just another
way to make it harder for an attacker to guess all values in an
attempt to generate a valid token.
When the token is generated, an anonymous user is directed to a
confirmation page where the timestamp and the usernames are already
preloaded, so the user needs to specify the token. User can either
click the link in the email if it's really them reading it, or to type
the token manually.
Using the right token in the same session as it was requested directs
the user to a password change form, where the user is supposed to
specify a new password (twice, of course). Upon completing the form
(which is POSTed) the password change happens and a notification
mail is sent.
The test is updated to test the basic functionality with a bad and
a good token, but it doesn't (yet) cover all code paths.
The original work from Andrew has been thorougly reviewed and heavily
modified by Søren Løvborg.
This is a better implementation of password reset function, which
doesn't involve sending a new password to the user's email address
in clear text, and at the same time is stateless.
The old implementation generated a new password and sent it
in clear text to whatever email assigned to the user currently,
so that any user, possibly unauthenticated, could request a reset
for any username or email. Apart from potential insecurity, this
made it possible for anyone to disrupt users' workflow by repeatedly
resetting their passwords.
The idea behind this implementation is to generate
an authentication token which is dependent on the user state
at the time before the password change takes place, so the token
is one-time and can't be reused, and also to bind the token to
the browser session.
The token is calculated as SHA1 hash of the following:
* user's identifier (number, not a name)
* timestamp
* hashed user's password
* session identifier
* per-application secret
We use numeric user's identifier, as it's fixed and doesn't change,
so renaming users doesn't affect the mechanism. Timestamp is added
to make it possible to limit the token's validness (currently hard
coded to 24h), and we don't want users to be able to fake that field
easily. Hashed user's password is needed to prevent using the token
again once the password has been changed. Session identifier is
an additional security measure to ensure someone else stealing the
token can't use it. Finally, per-application secret is just another
way to make it harder for an attacker to guess all values in an
attempt to generate a valid token.
When the token is generated, an anonymous user is directed to a
confirmation page where the timestamp and the usernames are already
preloaded, so the user needs to specify the token. User can either
click the link in the email if it's really them reading it, or to type
the token manually.
Using the right token in the same session as it was requested directs
the user to a password change form, where the user is supposed to
specify a new password (twice, of course). Upon completing the form
(which is POSTed) the password change happens and a notification
mail is sent.
The test is updated to test the basic functionality with a bad and
a good token, but it doesn't (yet) cover all code paths.
The original work from Andrew has been thorougly reviewed and heavily
modified by Søren Løvborg.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 | .. _installation:
==========================
Installation on Unix/Linux
==========================
The following describes three different ways of installing Kallithea:
- :ref:`installation-source`: The simplest way to keep the installation
up-to-date and track any local customizations is to run directly from
source in a Kallithea repository clone, preferably inside a virtualenv
virtual Python environment.
- :ref:`installation-virtualenv`: If you prefer to only use released versions
of Kallithea, the recommended method is to install Kallithea in a virtual
Python environment using `virtualenv`. The advantages of this method over
direct installation is that Kallithea and its dependencies are completely
contained inside the virtualenv (which also means you can have multiple
installations side by side or remove it entirely by just removing the
virtualenv directory) and does not require root privileges.
- :ref:`installation-without-virtualenv`: The alternative method of installing
a Kallithea release is using standard pip. The package will be installed in
the same location as all other Python packages you have ever installed. As a
result, removing it is not as straightforward as with a virtualenv, as you'd
have to remove its dependencies manually and make sure that they are not
needed by other packages.
.. _installation-source:
Installation from repository source
-----------------------------------
To install Kallithea in a virtualenv_ using the stable branch of the development
repository, follow the instructions below::
hg clone https://kallithea-scm.org/repos/kallithea -u stable
cd kallithea
virtualenv ../kallithea-venv
source ../kallithea-venv/bin/activate
python setup.py develop
python setup.py compile_catalog # for translation of the UI
You can now proceed to :ref:`setup`.
To upgrade, simply update the repository with ``hg pull -u`` and restart the
server.
.. _installation-virtualenv:
Installing a released version in a virtualenv
---------------------------------------------
It is highly recommended to use a separate virtualenv_ for installing Kallithea.
This way, all libraries required by Kallithea will be installed separately from your
main Python installation and other applications and things will be less
problematic when upgrading the system or Kallithea.
An additional benefit of virtualenv_ is that it doesn't require root privileges.
- Assuming you have installed virtualenv_, create a new virtual environment
for example, in `/srv/kallithea/venv`, using the virtualenv command::
virtualenv /srv/kallithea/venv
- Activate the virtualenv_ in your current shell session by running::
source /srv/kallithea/venv/bin/activate
.. note:: You can't use UNIX ``sudo`` to source the ``virtualenv`` script; it
will "activate" a shell that terminates immediately. It is also perfectly
acceptable (and desirable) to create a virtualenv as a normal user.
- Make a folder for Kallithea data files, and configuration somewhere on the
filesystem. For example::
mkdir /srv/kallithea
- Go into the created directory and run this command to install Kallithea::
pip install kallithea
Alternatively, download a .tar.gz from http://pypi.python.org/pypi/Kallithea,
extract it and run::
python setup.py install
- This will install Kallithea together with pylons_ and all other required
python libraries into the activated virtualenv.
You can now proceed to :ref:`setup`.
.. _installation-without-virtualenv:
Installing a released version without virtualenv
------------------------------------------------
For installation without virtualenv, 'just' use::
pip install kallithea
Note that this method requires root privileges and will install packages
globally without using the system's package manager.
To install as a regular user in ``~/.local``, you can use::
pip install --user kallithea
You can now proceed to :ref:`setup`.
Upgrading Kallithea from Python Package Index (PyPI)
----------------------------------------------------
.. note::
It is strongly recommended that you **always** perform a database and
configuration backup before doing an upgrade.
These directions will use '{version}' to note that this is the version of
Kallithea that these files were used with. If backing up your Kallithea
instance from version 0.1 to 0.2, the ``my.ini`` file could be
backed up to ``my.ini.0-1``.
If using a SQLite database, stop the Kallithea process/daemon/service, and
then make a copy of the database file::
service kallithea stop
cp kallithea.db kallithea.db.{version}
Back up your configuration file::
cp my.ini my.ini.{version}
Ensure that you are using the Python virtual environment that you originally
installed Kallithea in by running::
pip freeze
This will list all packages installed in the current environment. If
Kallithea isn't listed, activate the correct virtual environment::
source /srv/kallithea/venv/bin/activate
Once you have verified the environment you can upgrade Kallithea with::
pip install --upgrade kallithea
Then run the following command from the installation directory::
paster make-config Kallithea my.ini
This will display any changes made by the new version of Kallithea to your
current configuration. It will try to perform an automerge. It is recommended
that you recheck the content after the automerge.
.. note::
Please always make sure your .ini files are up to date. Errors can
often be caused by missing parameters added in new versions.
It is also recommended that you rebuild the whoosh index after upgrading since
the new whoosh version could introduce some incompatible index changes. Please
read the changelog to see if there were any changes to whoosh.
The final step is to upgrade the database. To do this simply run::
paster upgrade-db my.ini
This will upgrade the schema and update some of the defaults in the database,
and will always recheck the settings of the application, if there are no new
options that need to be set.
.. note::
The DB schema upgrade library has some limitations and can sometimes fail if you try to
upgrade from older major releases. In such a case simply run upgrades sequentially, e.g.,
upgrading from 0.1.X to 0.3.X should be done like this: 0.1.X. > 0.2.X > 0.3.X
You can always specify what version of Kallithea you want to install for example in pip
`pip install Kallithea==0.2`
You may find it helpful to clear out your log file so that new errors are
readily apparent::
echo > kallithea.log
Once that is complete, you may now start your upgraded Kallithea Instance::
service kallithea start
Or::
paster serve /srv/kallithea/my.ini
.. note::
If you're using Celery, make sure you restart all instances of it after
upgrade.
.. _virtualenv: http://pypi.python.org/pypi/virtualenv
.. _pylons: http://www.pylonsproject.org/
|