svn commit: r40872 - head/en_US.ISO8859-1/books/handbook/mirrors

[Warren Block]

Author: wblock
Date: Sat Feb  2 22:49:03 2013
New Revision: 40872
URL: http://svnweb.freebsd.org/changeset/doc/40872

Log:
  Add information on preferred protocols and HTTPS fingerprint verification
  to the Subversion Mirror Sites section.
  
  Reviewed by:	simon (slightly earlier version)

Modified:
  head/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml

Modified: head/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml	Sat Feb  2 14:52:15 2013	(r40871)
+++ head/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml	Sat Feb  2 22:49:03 2013	(r40872)
@@ -669,7 +669,7 @@
 	present but was not created by <command>svn</command>,
 	remember to rename or delete it before the checkout.</para>
 
-      <screen>&prompt.root; <userinput>svn checkout https://svn0.us-west.FreeBSD.org/ports/head /usr/ports</userinput></screen>
+      <screen>&prompt.root; <userinput>svn checkout <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>/ports/head /usr/ports</userinput></screen>
 
       <para>Because the initial checkout has to download the full
 	branch of the remote repository, it can take a while.  Please
@@ -716,7 +716,7 @@
   </sect1>
 
   <sect1 id="svn-mirrors">
-    <title><application>Subversion</application> Sites</title>
+    <title><application>Subversion</application> Mirror Sites</title>
 
     <indexterm>
       <primary>Subversion Repository</primary>
@@ -791,6 +791,42 @@
 	</tbody>
       </tgroup>
     </informaltable>
+
+    <para><acronym>HTTPS</acronym> is the preferred protocol,
+      providing protection against another computer pretending to be
+      the &os; mirror (commonly known as a <quote>man in the
+	middle</quote> attack) or otherwise trying to send bad content
+      to the end user.</para>
+
+    <para>On the first connection to an <acronym>HTTPS</acronym>
+      mirror, the user will be asked to verify the server
+      <emphasis>fingerprint</emphasis>:</para>
+
+    <screen>Error validating server certificate for 'https://svn0.us-west.freebsd.org:443':
+ - The certificate is not issued by a trusted authority. Use the
+   fingerprint to validate the certificate manually!
+Certificate information:
+ - Hostname: svnmir.ysv.FreeBSD.org
+ - Valid: from Fri, 24 Aug 2012 22:04:04 GMT until Sat, 24 Aug 2013 22:04:04 GMT
+ - Issuer: clusteradm, FreeBSD.org, CA, US
+ - Fingerprint: 79:35:8f:ca:6d:34:d9:30:44:d1:00:af:33:4d:e6:11:44:4d:15:ec
+(R)eject, accept (t)emporarily or accept (p)ermanently?</screen>
+
+    <para>Compare the fingerprint shown to those listed in the table
+      above.  If the fingerprint matches, the server security
+      certificate can be accepted temporarily or permanently.  A
+      temporary certificate will expire after a single session with
+      the server, and the verification step will be repeated on the
+      next connection.  Accepting the certificate permanently will
+      store the authentication credentials in
+      <filename role="directory">~/.subversion/auth/</filename> and
+      the user will not be asked to verify the fingerprint again until
+      the certificate expires.</para>
+
+    <para>If <acronym>HTTPS</acronym> cannot be used due to firewall
+      or other problems, <literal>SVN</literal> is the next choice,
+      with slightly faster transfers.  When neither can be used, use
+      <acronym>HTTP</acronym>.</para>
   </sect1>
 
   <sect1 id="cvsup">