[svnbook] r3890 committed - * src/en/book/ch06-server-configuration.xml...
svnbook at googlecode.com
svnbook at googlecode.com
Thu Jul 7 09:26:13 CDT 2011
Revision: 3890
Author: cmpilato at gmail.com
Date: Thu Jul 7 07:25:44 2011
Log: * src/en/book/ch06-server-configuration.xml
(svn.serverconfig.httpd.ssl): Reorganize and expand the SSL
documentation.
Patch by: quinntaylor at mac.com
(Tweaked by me.)
http://code.google.com/p/svnbook/source/detail?r=3890
Modified:
/trunk/src/en/book/ch06-server-configuration.xml
=======================================
--- /trunk/src/en/book/ch06-server-configuration.xml Thu Jul 7 06:50:34
2011
+++ /trunk/src/en/book/ch06-server-configuration.xml Thu Jul 7 07:25:44
2011
@@ -2244,52 +2244,73 @@
<sect2 id="svn.serverconfig.httpd.ssl">
<title>Protecting network traffic with SSL</title>
- <para>Businesses that need to expose their repositories for access
- outside the company firewall should be conscious of the
- possibility that unauthorized parties could be
- <quote>sniffing</quote> their network traffic. SSL makes
- that kind of unwanted attention less likely to result in
- sensitive data leaks.</para>
+ <para>Connecting to a repository via <literal>http://</literal>
+ means that all Subversion activity is sent across the network
+ in the clear. This means that actions such as checkouts,
+ commits, and updates could potentially be intercepted by an
+ unauthorized party <quote>sniffing</quote> network traffic.
+ Encrypting traffic using SSL is a good way to protect
+ potentially sensitive information over the network.</para>
<para>If a Subversion client is compiled to use OpenSSL,
it gains the ability to speak to an Apache server via
- <literal>https://</literal> URLs. The Neon library used by
+ <literal>https://</literal> URLs, so all traffic is encrypted
+ with a per-connection session key. The WebDAV library used by
the Subversion client is not only able to verify server
certificates, but can also supply client certificates when
- challenged. When the client and server have exchanged SSL
- certificates and successfully authenticated one another, all
- further communication is encrypted via a session key.</para>
-
- <para>It's beyond the scope of this book to describe how to
- generate client and server certificates and how to
- configure Apache to use them. Many other books, including
- Apache's own documentation, describe this task. But what we
- <emphasis>can</emphasis> cover here is how to manage
- server and client certificates from an ordinary Subversion
- client.</para>
-
- <para>When speaking to Apache via <literal>https://</literal>,
- a Subversion client can receive two different types of
- information:</para>
-
- <itemizedlist>
- <listitem><para>A server certificate</para></listitem>
- <listitem><para>A demand for a client certificate</para></listitem>
- </itemizedlist>
-
- <para>If the client receives a server certificate, it needs to
- verify that it trusts the certificate: is the server really
- who it claims to be? The OpenSSL library does this by
- examining the signer of the server certificate, or
- <firstterm>certificate authority</firstterm> (CA). If
- OpenSSL is unable to automatically trust the CA, or if some
- other problem occurs (such as an expired certificate or
- hostname mismatch), the Subversion command-line client will
- ask you whether you want to trust the server certificate
- anyway:</para>
-
- <informalexample>
- <screen>
+ challenged by the server.</para>
+
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-->
+ <sect3 id="svn.serverconfig.httpd.ssl.server">
+ <title>Subversion server SSL certificate configuration</title>
+
+ <para>It's beyond the scope of this book to describe how to
+ generate client and server SSL certificates and how to
+ configure Apache to use them. Many other references,
+ including Apache's own documentation, describe the
process.</para>
+
+ <tip>
+ <para>SSL certificates from well-known entities generally
+ cost money, but at a bare minimum, you can configure
+ Apache to use a self-signed certificate generated with a
+ tool such as OpenSSL (<ulink url="http://openssl.org"
+ />).<footnote><para>While self-signed certificates are
+ still vulnerable to a <quote>man-in-the-middle</quote>
+ attack, such an attack is much more difficult for a casual
+ observer to pull off, compared to sniffing unprotected
+ passwords.</para></footnote></para>
+ </tip>
+
+ </sect3>
+
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-->
+ <sect3 id="svn.serverconfig.httpd.ssl.client">
+ <title>Subversion client SSL certificate management</title>
+
+ <para>When connecting to Apache via <literal>https://</literal>,
+ a Subversion client can receive two different types of
+ responses:</para>
+
+ <itemizedlist>
+ <listitem><para>A server certificate</para></listitem>
+ <listitem><para>A challenge for a client
certificate</para></listitem>
+ </itemizedlist>
+
+ <sect4 id="svn.serverconfig.httpd.ssl.client.servercert">
+ <title>Server certificate</title>
+
+ <para>When the client receives a server certificate, it needs
+ to verify that the server is who it claims to be. OpenSSL
+ does this by examining the signer of the server certificate,
+ or <firstterm>certificate authority</firstterm> (CA). If
+ OpenSSL is unable to automatically trust the CA, or if some
+ other problem occurs (such as an expired certificate or
+ hostname mismatch), the Subversion command-line client will
+ ask you whether you want to trust the server certificate
+ anyway:</para>
+
+ <informalexample>
+ <screen>
$ svn list https://host.example.com/repos/project
Error validating server certificate for 'https://host.example.com:443':
@@ -2303,94 +2324,98 @@
(R)eject, accept (t)emporarily or accept (p)ermanently?
</screen>
- </informalexample>
-
- <para>This dialogue should look familiar; it's essentially the
- same question you've probably seen coming from your web
- browser (which is just another HTTP client like Subversion).
- If you choose the <literal>(p)</literal>ermanent option, the
server certificate
- will be cached in your private runtime
- <filename>auth/</filename> area in just the same way your
- username and password are cached (see <xref
- linkend="svn.serverconfig.netmodel.credcache"/>). If cached,
- Subversion will automatically trust this certificate
- in future negotiations.</para>
-
- <para>Your runtime <filename>servers</filename> file also gives
- you the ability to make your Subversion client automatically
- trust specific CAs, either globally or on a per-host basis.
- Simply set the <literal>ssl-authority-files</literal>
- variable to a semicolon-separated list of PEM-encoded CA
- certificates:</para>
-
- <informalexample>
- <screen>
+ </informalexample>
+
+ <para>This dialogue is essentially the same question you may
+ have seen coming from your web browser (which is just
+ another HTTP client like Subversion). If you choose the
+ <literal>(p)</literal>ermanent option, Subversion will
+ cache the server certificate in your private runtime
+ <filename>auth/</filename> area, just as your username and
+ password are cached (see <xref
+ linkend="svn.serverconfig.netmodel.credcache"/>), and will
+ automatically trust the certificate in the future.</para>
+
+ <para>Your runtime <filename>servers</filename> file also gives
+ you the ability to make your Subversion client automatically
+ trust specific CAs, either globally or on a per-host basis.
+ Simply set the <literal>ssl-authority-files</literal>
+ variable to a semicolon-separated list of PEM-encoded CA
+ certificates:</para>
+
+ <informalexample>
+ <programlisting>
[global]
ssl-authority-files = /path/to/CAcert1.pem;/path/to/CAcert2.pem
-</screen>
- </informalexample>
-
- <para>Many OpenSSL installations also have a predefined set
- of <quote>default</quote> CAs that are nearly universally
- trusted. To make the Subversion client automatically trust
- these standard authorities, set the
- <literal>ssl-trust-default-ca</literal> variable to
- <literal>true</literal>.</para>
-
- <para>When talking to Apache, a Subversion client might also
- receive a challenge for a client certificate. Apache is
- asking the client to identify itself: is the client really
- who it says it is? If all goes correctly, the Subversion
- client sends back a private certificate signed by a CA that
- Apache trusts. A client certificate is usually stored on
- disk in encrypted format, protected by a local password.
- When Subversion receives this challenge, it will ask you for
- a path to the certificate and the password that
- protects it:</para>
-
- <informalexample>
- <screen>
+</programlisting>
+ </informalexample>
+
+ <para>Many OpenSSL installations also have a predefined set
+ of <quote>default</quote> CAs that are nearly universally
+ trusted. To make the Subversion client automatically trust
+ these standard authorities, set the
+ <literal>ssl-trust-default-ca</literal> variable to
+ <literal>true</literal>.</para>
+
+ </sect4>
+
+ <sect4 id="svn.serverconfig.httpd.ssl.client.clientcert">
+ <title>Client certificate challenge</title>
+
+ <para>If the client receives a challenge for a certificate,
+ the server is asking the client to prove its identity.
+ The client must send back a certificate signed by a CA
+ that the server trusts, along with a <firstterm>challenge
+ response</firstterm> which proves that the client owns the
+ private key associated with the certificate. The private
+ key and certificate are usually stored in an encrypted
+ format on disk, protected by a passphrase. When Subversion
+ receives this challenge, it will ask you for the path to the
+ encrypted file and the passphrase that protects it:</para>
+
+ <informalexample>
+ <screen>
$ svn list https://host.example.com/repos/project
Authentication realm: https://host.example.com:443
Client certificate filename: /path/to/my/cert.p12
Passphrase for '/path/to/my/cert.p12': ********
-…
</screen>
- </informalexample>
-
- <para>Notice that the client certificate is a
- <quote>p12</quote> file. To use a client certificate with
- Subversion, it must be in PKCS#12 format, which is a
- portable standard. Most web browsers are already able to
- import and export certificates in that format. Another
- option is to use the OpenSSL command-line tools to convert
- existing certificates into PKCS#12.</para>
-
- <para>Again, the runtime <filename>servers</filename> file
- allows you to automate this challenge on a per-host basis.
- Either or both pieces of information can be described in
- runtime variables:</para>
-
- <informalexample>
- <screen>
+ </informalexample>
+
+ <para>Notice that the client credentials are stored in a
+ <literal>.p12</literal> file. To use a client certificate
+ with Subversion, it must be in PKCS#12 format, which is a
+ portable standard. Most web browsers are able to import
+ and export certificates in that format. Another option
+ is to use the OpenSSL command-line tools to convert
+ existing certificates into PKCS#12.</para>
+
+ <para>The runtime <filename>servers</filename> file also
+ allows you to automate this challenge on a per-host basis.
+ If you set the <literal>ssl-client-cert-file</literal>
+ and <literal>ssl-client-cert-password</literal> variables,
+ Subversion can automatically respond to a client
+ certificate challenge without prompting you:</para>
+
+ <informalexample>
+ <programlisting>
[groups]
examplehost = host.example.com
[examplehost]
ssl-client-cert-file = /path/to/my/cert.p12
ssl-client-cert-password = somepassword
-</screen>
- </informalexample>
-
- <para>Once you've set the
- <literal>ssl-client-cert-file</literal> and
- <literal>ssl-client-cert-password</literal> variables, the
- Subversion client can automatically respond to a client
- certificate challenge without prompting
- you.<footnote><para>More security-conscious folk might not
- want to store the client certificate password in the runtime
- <filename>servers</filename> file.</para></footnote></para>
+</programlisting>
+ </informalexample>
+
+ <para>More security-conscious folk might want to exclude
+ <literal>ssl-client-cert-password</literal> to avoid
+ storing the passphrase in the clear on disk.</para>
+
+ </sect4>
+
+ </sect3>
</sect2>
More information about the svnbook-dev
mailing list