Finish updating the OpenSSH section and add information on how to use ssh-agent(1).

svn path=/head/; revision=25030

en_US.ISO8859-1/books/handbook/security/chapter.sgml

@@ -4236,8 +4236,10 @@ ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D
         <secondary>enabling</secondary>
       </indexterm>
 
-      <para>Be sure to make the following addition to your 
+      <para>The <application>sshd</application> daemon is enabled by
-        <filename>rc.conf</filename> file:</para>
+        default on &os; 4.X and is enabled or not during the
+        installation by the user of &os; 5.X.  To see if it is
+        enabled, check the <filename>rc.conf</filename> file for:</para>
       <screen>sshd_enable="YES"</screen>
       <para>This will load &man.sshd.8;, the daemon program for <application>OpenSSH</application>,
 	the next time your system initializes.  Alternatively, you can
@@ -4274,14 +4276,14 @@ user@example.com's password: <userinput>*******</userinput></screen>
 	<filename>~/.ssh/known_hosts2</filename> for SSH v2
 	fingerprints.</para>
 
-      <para>By default, <application>OpenSSH</application> servers are configured to only accept
+      <para>By default, recent versions of the
-	SSH v2 connections.  The client, however, can choose
+        <application>OpenSSH</application> servers only accept SSH v2
-	between version 1 and 2.  Version 2 is known to be more robust and
+        connections.  The client will use version 2 if possible and
-	secure than its predecessor.</para>
+        will fall back to version 1.  The client can also be forced to
-
+        use one or the other by passing it the <option>-1</option> or
-      <para>The &man.ssh.1; command can be forced to use either protocol
+        <option>-2</option> for version 1 or version 2, respectively.
-	by passing it the <option>-1</option> or <option>-2</option> argument
+        The version 1 compatability is maintained in the client for
-	for v1 and v2, respectively.</para>
+        backwards compatability with older versions.</para>
     </sect2>
     
     <sect2>
@@ -4335,61 +4337,93 @@ COPYRIGHT            100% |*****************************|  4735
 	options can provide more levels of configuration.</para>
     </sect2>
 
-    <sect2>
+    <sect2 id="security-ssh-keygen">
       <title>ssh-keygen</title>
 
       <para>Instead of using passwords, &man.ssh-keygen.1; can
-        be used to generate RSA keys to authenticate a user:</para>
+        be used to generate DSA or RSA keys to authenticate a user:</para>
 
-      <screen>&prompt.user; <userinput>ssh-keygen -t <replaceable>rsa1</replaceable></userinput>
+      <screen>&prompt.user; <userinput>ssh-keygen -t <replaceable>dsa</replaceable></userinput>
-Initializing random number generator...
+Generating public/private dsa key pair.
-Generating p:  .++ (distance 66)
+Enter file in which to save the key (/home/user/.ssh/id_dsa):
-Generating q:  ..............................++ (distance 498)
+Created directory '/home/user/.ssh'.
-Computing the keys...
+Enter passphrase (empty for no passphrase):
-Key generation complete.
+Enter same passphrase again:
-Enter file in which to save the key (/home/user/.ssh/identity):
+Your identification has been saved in /home/user/.ssh/id_dsa.
-Enter passphrase:
+Your public key has been saved in /home/user/.ssh/id_dsa.pub.
-Enter the same passphrase again:
+The key fingerprint is:
-Your identification has been saved in /home/user/.ssh/identity.
+bb:48:db:f2:93:57:80:b6:aa:bc:f5:d5:ba:8f:79:17 user@host.example.com
-...</screen>
+</screen>
 
       <para>&man.ssh-keygen.1; will create a public and private
         key pair for use in authentication.  The private key is stored in
-        <filename>~/.ssh/identity</filename>, whereas the public key is
+        <filename>~/.ssh/id_dsa</filename> or
-        stored in <filename>~/.ssh/identity.pub</filename>.  The public
+        <filename>~/.ssh/id_rsa</filename>, whereas the public key is
-        key must be placed in <filename>~/.ssh/authorized_keys</filename>
+        stored in <filename>~/.ssh/id_dsa.pub</filename> or
-        of the remote machine in order for the setup to work.</para>
+        <filename>~/.ssh/id_rsa.pub</filename>, respectively for DSA and
+        RSA key types.  The public key must be placed in
+        <filename>~/.ssh/authorized_keys</filename> of the remote
+        machine in order for the setup to work.  Similarly, RSA version
+        1 public keys should be placed in
+        <filename>~/.ssh/authorized_keys</filename>.</para>
 
       <para>This will allow connection to the remote machine based upon
-        RSA authentication instead of passwords.</para>
+        SSH keys instead of passwords.</para>
-
-      <note><para>The <option>-t rsa1</option> option will create RSA
-	keys for use by SSH protocol version 1.  If you want to use
-	RSA keys with the SSH protocol version 2, you have to use the
-	command <command>ssh-keygen -t rsa</command>.</para></note>
 
       <para>If a passphrase is used in &man.ssh-keygen.1;, the user
-        will be prompted for a password each time in order to use the private
+        will be prompted for a password each time in order to use the
-        key.</para>
+        private key.  &man.ssh-agent.1; can alleviate the strain of
-
+        repeatedly entering long passphrases, and is explored in the
-      <para>A SSH protocol version 2 DSA key can be created for the same purpose by using
+        <xref linkend="security-ssh-agent"> section below.</para>
-	the <command>ssh-keygen -t dsa</command> command.
-	This will
-	create a public/private DSA key for use in SSH protocol version 2 sessions only.
-	The public key is stored in <filename>~/.ssh/id_dsa.pub</filename>,
-	while the private key is in <filename>~/.ssh/id_dsa</filename>.</para>
-
-      <para>DSA public keys are also placed in
-	<filename>~/.ssh/authorized_keys</filename> on the remote
-	machine.</para>
-
-      <para>&man.ssh-agent.1; and &man.ssh-add.1; are 
-        utilities used in managing multiple passworded private keys.</para>
 
       <warning><para>The various options and files can be different
-	according to the <application>OpenSSH</application> version you have on your system, to
+        according to the <application>OpenSSH</application> version
-	avoid problems you should consult the &man.ssh-keygen.1;
+        you have on your system; to avoid problems you should consult
-	manual page.</para></warning>
+        the &man.ssh-keygen.1; manual page.</para></warning>
+    </sect2>
+
+    <sect2 id="security-ssh-agent">
+      <title>ssh-agent and ssh-add</title>
+
+      <para>The &man.ssh-agent.1; and &man.ssh-add.1; utilities provide
+        methods for <application>SSH</application> keys to be loaded
+        into memory for use, without needing to type the passphrase
+        each time.</para>
+
+      <para>The &man.ssh-agent.1 utility will handle the authentication
+        using the private key(s) that are loaded into it.
+        &man.ssh-agent.1; should be used to launch another application.
+        At the most basic level, it could spawn a shell or at a more
+        advanced level, a window manager.<para>
+
+      <para>To use &man.ssh-agent.1; in a shell, first it will need to
+        be spawned with a shell as an argument.  Secondly, the
+        identity needs to be added by running &man.ssh-add.1; and
+        providing it the passphrase for the private key.  Once these
+        steps have been completed the user will be able to &man.ssh.1;
+        to any host that has the corresponding public key installed.
+        For example:</para>
+
+      <screen>&prompt.user; ssh-agent <replaceable>csh</replaceable>
+&prompt.user; ssh-add
+Enter passphrase for /home/user/.ssh/id_dsa:
+Identity added: /home/user/.ssh/id_dsa (/home/user/.ssh/id_dsa)
+&prompt.user;</screen>
+
+      <para>To use &man.ssh-agent.1; in X11, a call to
+        &man.ssh-agent.1; will need to be placed in
+        <filename>~/.xinitrc</filename>.  This will provide the
+        &man.ssh-agent.1; services to all programs launched in X11.
+        An example <filename>~/.xinitrc</filename> file might look
+        like this:</para>
+
+      <programlisting>exec ssh-agent <replaceable>startxfce4</replaceable></programlisting>
+
+      <para>This would launch &man.ssh-agent.1;, which would in turn
+        launch <application>XFCE</application>, every time X11 starts.
+        Then once that is done and X11 has been restarted so that the
+        changes can take effect, simply run &man.ssh-add.1; to load
+        all of your SSH keys.</para>
     </sect2>
 
     <sect2 id="security-ssh-tunneling">