<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Network Model</title><link rel="stylesheet" href="styles.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><link rel="start" href="index.html" title="Version Control with Subversion" /><link rel="up" href="svn.advanced.html" title="Chapter 3. Advanced Topics" /><link rel="prev" href="svn.advanced.changelists.html" title="Changelists" /><link rel="next" href="svn.branchmerge.html" title="Chapter 4. Branching and Merging" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Network Model</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="svn.advanced.changelists.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="svn.branchmerge.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="svn.serverconfig.netmodel"></a>Network Model</h2></div></div></div><p>At some point, you're going to need to understand how your
Subversion client communicates with its server. Subversion's
networking layer is abstracted, meaning that Subversion clients
exhibit the same general behaviors no matter what sort of server
they are operating against. Whether speaking the HTTP protocol
(<code class="literal">http://</code>) with the Apache HTTP Server or
speaking the custom Subversion protocol
(<code class="literal">svn://</code>) with <span class="command"><strong>svnserve</strong></span>,
the basic network model is the same. In this section, we'll
explain the basics of that network model, including how
Subversion manages authentication and authorization
matters.</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="svn.serverconfig.netmodel.reqresp"></a>Requests and Responses</h3></div></div></div><p>The Subversion client spends most of its time managing
working copies. When it needs information from a remote
repository, however, it makes a network request, and the
server responds with an appropriate answer. The details of
the network protocol are hidden from the user—the client
attempts to access a URL, and depending on the URL scheme, a
particular protocol is used to contact the server (see <a class="xref" href="svn.basic.in-action.html#svn.basic.in-action.wc.sb-1" title="Repository URLs">Repository URLs</a>).</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>Run <span class="command"><strong>svn --version</strong></span> to see
which URL schemes and protocols the client knows how to
use.</p></div><p>When the server process receives a client request, it
often demands that the client identify itself. It issues
an authentication challenge to the client, and the client
responds by providing <em class="firstterm">credentials</em> back
to the server. Once authentication is complete, the server
responds with the original information the client asked for.
Notice that this system is different from systems like CVS,
where the client pre-emptively offers credentials (“<span class="quote">logs
in</span>”) to the server before ever making a request. In
Subversion, the server “<span class="quote">pulls</span>” credentials by
challenging the client at the appropriate moment, rather than
the client “<span class="quote">pushing</span>” them. This makes certain
operations more elegant. For example, if a server is
configured to allow anyone in the world to read a repository,
then the server will never issue an authentication challenge
when a client attempts to <span class="command"><strong>svn checkout</strong></span>.</p><p>If the particular network requests issued by the client
result in a new revision being created in the repository,
(e.g. <span class="command"><strong>svn commit</strong></span>), then Subversion uses the
authenticated username associated with those requests as the
author of the revision. That is, the authenticated user's
name is stored as the value of the
<code class="literal">svn:author</code> property on the new revision
(see <a class="xref" href="svn.ref.properties.html" title="Subversion properties">the section called “Subversion properties”</a>). If
the client was not authenticated (in other words, the server
never issued an authentication challenge), then the revision's
<code class="literal">svn:author</code> property is empty.
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="svn.serverconfig.netmodel.credcache"></a>Client Credentials Caching</h3></div></div></div><p>Many servers are configured to require authentication on
every request. This would be a big annoyance to users, if
they were forced to type their passwords over and over again.
Fortunately, the Subversion client has a remedy for
this—a built-in system for caching authentication
credentials on disk. By default, whenever the command-line
client successfully responds to a server's authentication
challenge, it saves the credentials in the user's private
runtime configuration area
(<code class="filename">~/.subversion/auth/</code> on Unix-like systems
or <code class="filename">%APPDATA%/Subversion/auth/</code> on Windows;
see <a class="xref" href="svn.advanced.confarea.html" title="Runtime Configuration Area">the section called “Runtime Configuration Area”</a> for more details
about the runtime configuration system). Successful
credentials are cached on disk, keyed on a combination of the
server's hostname, port, and authentication realm.</p><p>When the client receives an authentication challenge, it
first looks for the appropriate credentials in the user's disk
cache. If seemingly suitable credentials are not present, or
if the cached credentials ultimately fail to authenticate,
then the client will, by default, fall back to prompting the
user for the necessary information.</p><p>The security-conscious reader will suspect immediately
that there is reason for concern here. “<span class="quote">Caching
passwords on disk? That's terrible! You should never do
that!</span>”</p><p>The Subversion developers recognize the legitimacy of such
concerns, and so Subversion works with available mechanisms
provided by the operating system and environment to try to
minimize the risk of leaking this information. Here's a
breakdown of what this means for users on the most common
platforms:</p><div class="itemizedlist"><ul type="disc"><li><p>On Windows 2000 and later, the Subversion client uses
standard Windows cryptography services to encrypt the
password on disk. Because the encryption key is managed
by Windows and is tied to the user's own login
credentials, only the user can decrypt the cached
password. (Note that if the user's Windows account password
is reset by an administrator, all of the cached passwords
become undecipherable. The Subversion client will behave
as if they don't exist, prompting for passwords when
required.)</p></li><li><p>Similarly, on Mac OS X, the Subversion client stores
all repository passwords in the login keyring (managed by
the Keychain service), which is protected by the user's
account password. User preference settings can impose
additional policies, such as requiring the user's account
password be entered each time the Subversion password is
used.</p></li><li><p>For other Unix-like operating systems, no standard
“<span class="quote">keychain</span>” services exist. However,
the <code class="filename">auth/</code> caching area is still
permission-protected so that only the user (owner) can
read data from it, not the world at large. The operating
system's own file permissions protect the passwords.</p></li></ul></div><p>Of course, for the truly paranoid, none of these
mechanisms meets the test of perfection. So for those folks
willing to sacrifice convenience for the ultimate security,
Subversion provides various ways of disabling its credentials
caching system altogether.</p><p>To disable caching for a single command, pass the
<code class="option">--no-auth-cache</code> option:</p><pre class="screen">
$ svn commit -F log_msg.txt --no-auth-cache
Authentication realm: <svn://host.example.com:3690> example realm
Username: joe
Password for 'joe':
Adding newfile
Transmitting file data .
Committed revision 2324.
# password was not cached, so a second commit still prompts us
$ svn delete newfile
$ svn commit -F new_msg.txt
Authentication realm: <svn://host.example.com:3690> example realm
Username: joe
…
</pre><p>Or, if you want to disable credential caching permanently,
you can edit the <code class="filename">config</code> file in your
runtime configuration area, and set the
<code class="option">store-auth-creds</code> option to
<code class="literal">no</code>. This will prevent the storing of
credentials used in any Subversion interactions you perform on
the affected computer. This can be extended to cover all
users on the computer, too, by modifying the system-wide
runtime configuration area (described in <a class="xref" href="svn.advanced.confarea.html#svn.advanced.confarea.layout" title="Configuration Area Layout">the section called “Configuration Area Layout”</a>).</p><pre class="screen">
[auth]
store-auth-creds = no
</pre><p>Sometimes users will want to remove specific credentials
from the disk cache. To do this, you need to navigate into
the <code class="filename">auth/</code> area and manually delete the
appropriate cache file. Credentials are cached in individual
files; if you look inside each file, you will see keys and
values. The <code class="literal">svn:realmstring</code> key describes
the particular server realm that the file is associated
with:</p><pre class="screen">
$ ls ~/.subversion/auth/svn.simple/
5671adf2865e267db74f09ba6f872c28
3893ed123b39500bca8a0b382839198e
5c3c22968347b390f349ff340196ed39
$ cat ~/.subversion/auth/svn.simple/5671adf2865e267db74f09ba6f872c28
K 8
username
V 3
joe
K 8
password
V 4
blah
K 15
svn:realmstring
V 45
<https://svn.domain.com:443> Joe's repository
END
</pre><p>Once you have located the proper cache file, just delete
it.</p><p>One last word about <span class="command"><strong>svn</strong></span>'s
authentication behavior, specifically regarding the
<code class="option">--username</code> and <code class="option">--password</code>
options. Many client subcommands accept these options, but it
is important to understand using these options does
<span class="emphasis"><em>not</em></span> automatically send credentials to the
server. As discussed earlier, the server “<span class="quote">pulls</span>”
credentials from the client when it deems necessary; the
client cannot “<span class="quote">push</span>” them at will. If a username
and/or password are passed as options, they will only be
presented to the server if the server requests them.
<sup>[<a id="id363974" href="#ftn.id363974" class="footnote">21</a>]</sup>
These options are typically used to authenticate as a
different user than Subversion would have chosen by default
(such as your system login name), or when trying to avoid
interactive prompting (such as when calling
<span class="command"><strong>svn</strong></span> from a script).</p><p>Here is a final summary that describes how a Subversion
client behaves when it receives an authentication
challenge.</p><div class="orderedlist"><ol type="1"><li><p>First, the client checks whether the user specified
any credentials as command-line options
(<code class="option">--username</code> and/or
<code class="option">--password</code>). If not, or if these options
fail to authenticate successfully, then</p></li><li><p>the client looks up the server's hostname, port, and realm in
the runtime <code class="filename">auth/</code> area, to see if the
user already has the appropriate credentials cached. If
not, or if the cached credentials fail to authenticate,
then</p></li><li><p>finally, the client resorts to prompting the user
(unless instructed not to do so via the
<code class="option">--non-interactive</code> option or its
client-specific equivalents).</p></li></ol></div><p>If the client successfully authenticates by any of the
methods listed above, it will attempt to cache the credentials
on disk (unless the user has disabled this behavior, as
mentioned earlier).</p></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id363974" href="#id363974" class="para">21</a>] </sup>Again, a common mistake is to misconfigure a
server so that it never issues an authentication challenge.
When users pass <code class="option">--username</code> and
<code class="option">--password</code> options to the client, they're
surprised to see that they're never used, i.e. new revisions
still appear to have been committed
anonymously!</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="svn.advanced.changelists.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="svn.advanced.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="svn.branchmerge.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Changelists </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 4. Branching and Merging</td></tr></table></div></body></html>
