Fossil

Check-in [cac5675e]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Add the /doc/tip/www/password.wiki document.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | experimental
Files: files | file ages | folders
SHA1: cac5675e6c618ae27e44883aceaed6529b704909
User & Date: drh 2010-01-11 15:07:29
Context
2010-01-11
16:09
Updates to the Password Management document. check-in: 1cba86ea user: drh tags: experimental
15:07
Add the /doc/tip/www/password.wiki document. check-in: cac5675e user: drh tags: experimental
2010-01-10
20:56
Change the hash algorithm for passwords so that USER.PW field stores a SHA1 hash of the project-code, user login, and user password, rather than just a hash of the user password. That way, the if two users select the same password, or if the one user selects the same password for multiple projects, the password hashes are still different. check-in: 4b58a7b8 user: drh tags: experimental
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Added www/password.wiki.





























































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
<title>Fossil Password Management</title>
<h1 align="center">Password Management</h1>

Fossil handles user authentication using passwords.
Passwords are unique to each repository.  Passwords are not part of the
persistent state of a project.  Passwords are not versioned and
are not transmitted from one repository to another during a sync.
Passwords are local configuration information that can (and usually does)
vary from one repository to the next within the same project.

Passwords are stored in the PW field of the USER table.
In older versions of Fossil (prior to 2010-01-11) the password 
is stored as cleartext.  In newer versions of Fossil, the password
can be either cleartext or an SHA1 hash (written as a 40-character
lower-case hexadecimal number).  If the USER.PW field contains
a 40-character string, that string is assumed to be a SHA1 hash.
If the size of USER.PW is anything other than 40 characters, then
it is understood as a plain-text password.

The SHA1 hash in the USER.PW field is a hash of a string composed of
the project-code, the user login, and the user cleartext password.
Suppose user "alice" with password "asdfg" had an account on the
Fossil self-hosting repository.  Then the value of USER.PW
for alice would be the SHA1 hash of

<blockquote>
CE59BB9F186226D80E49D1FA2DB29F935CCA0333/alice/asdfg
</blockquote>

That hash value is "f1b699cc9af3eeb98e5de244ca7802ae38e77bae".  Note
that by including the project-code and the login as part of the hash,
a different USER.PW value results even if two or more users on the
repository select the same "asdfg" password or if user alice reuses the
same password on multiple projects.

<h2>Web Interface Authtentication</h2>

When a user logs into Fossil using the web interface, the login name
and password are sent in the clear to the server.  The server then
hashes the password and compares it against the value stored in USER.PW.
If they match, the server sets a cookie on the client to record the
login.  This cookie contains a large amount of high-quality randomness
and is thus impossible to guess.  The value of the cookie and the IP
address of the client is stored in the USER.COOKIE and USER.IPADDR fields
of the USER table on the server.  
The USER.CEXPIRE field holds an expiration date
for the cookie, encoded as a julian day number.  On all subsequent
HTTP requests, the cookie value is matched against the USER table to 
enable access to the repository.

A login cookie will only work if the IP address matches.  This feature
is designed to make it more difficult for an attacker to sniff the cookie
and take over the connection.  A cookie-sniffing attack will only work
if the attacker is able to send and receive from the same IP address as
the original login.  However, we found that doing an exact IP match
caused problems for some users who are behind proxy firewalls where the proxy
might use a different IP address for each query.  To work around this
problem, newer versions of fossil only check the first 16 bits of the
32-bit IP address.  This makes a cookie sniffing attack easier since now
the attacker only has to send and receive from any IP address in a range
of IPs that are similar to the initial login.  But that is seen as an
acceptable compromise in exchange for ease of use.  If higher security
is really needed, then HTTPS can be used instead of HTTP.

Note that in order to log into a Fossil server, it is necessary to
write information into the repository database.  Hence, login is not
possible on a Fossil repository with a read-only database file.

The user password is sent over the wire as cleartext on the initial
login attempt.  The plan moving forward is to compute the SHA1 hash of
the password on the client using javascript and then send only the hash
over the wire, but that plan has not yet been set in code.

<h2>Sync Protocol Authentication</h2>

A different authentication mechanism is used when one repository wants
to sync (or push or pull or clone) another respository.  When two
respositories are syncing, the one that initiates the transaction is
the client and the repository that responds is the server.  The client
works by sending HTTP requests to the server with a method of "xfer"
and a content-type of "application/x-fossil".  The content is Zlib-compressed
text consisting of "cards" of instructions.  The first card of this content
is a "login" card responsible for authentication.  The login card contains
the login name of the user and a "signature" where the signature is the
SHA1 hash of a nonce and the value of USER.PW.  The nonce is the
SHA1 hash of the remainder of the request content after the newline
(ASCII 14) character that terminates the login card.

Using this approach, the USER.PW value is treated as a shared secret
between the client and server.  The USER.PW value is never sent over
the wire, but the protocol establishes that both client and server know
the value of USER.PW.  Furthermore, the use of a SHA1 hash over the entire
message prevents an attacker from sniffing a valid login from a legitimate
users and then replaying the message modified content.