Date: Thu, 10 Apr 2014 18:05:33 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44520 - head/en_US.ISO8859-1/books/handbook/security Message-ID: <201404101805.s3AI5XFJ061345@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: dru Date: Thu Apr 10 18:05:32 2014 New Revision: 44520 URL: http://svnweb.freebsd.org/changeset/doc/44520 Log: Editorial review of first 1/2 of OpenSSH chapter. Sponsored by: iXsystems Modified: head/en_US.ISO8859-1/books/handbook/security/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/security/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/security/chapter.xml Thu Apr 10 16:57:57 2014 (r44519) +++ head/en_US.ISO8859-1/books/handbook/security/chapter.xml Thu Apr 10 18:05:32 2014 (r44520) @@ -2437,8 +2437,8 @@ racoon_enable="yes"</programlisting> </indexterm> <para><application>OpenSSH</application> is a set of network - connectivity tools used to access remote machines securely. - Additionally, TCP/IP connections can be tunneled/forwarded + connectivity tools used to provide secure access to remote machines. + Additionally, <acronym>TCP/IP</acronym> connections can be tunneled or forwarded securely through <acronym>SSH</acronym> connections. <application>OpenSSH</application> encrypts all traffic to effectively eliminate eavesdropping, connection hijacking, and @@ -2456,6 +2456,11 @@ racoon_enable="yes"</programlisting> authentication and encryption methods to prevent this from happening.</para> + <para>This section describes how to use the built-in client + utilities to securely access other systems and securely transfer + files from a &os; system. It then describes how to configure a + <acronym>SSH</acronym> server on a &os; system.</para> + <sect2> <title>Using the SSH Client Utilities</title> @@ -2464,34 +2469,39 @@ racoon_enable="yes"</programlisting> <secondary>client</secondary> </indexterm> - <para>To use &man.ssh.1; to connect to a system running - &man.sshd.8;, specify the username and host to log - into:</para> + <para>To log into a <acronym>SSH</acronym> server, use + <command>ssh</command> and specify a username that exists on + that server and the <acronym>IP</acronym> address or hostname + of the server. If this is the first time a connection has + been made to the specified server, the user will be prompted + to first verify the server's fingerprint:</para> <screen>&prompt.root; <userinput>ssh <replaceable>user@example.com</replaceable></userinput> -Host key not found from the list of known hosts. +The authenticity of host 'example.com (10.0.0.1)' can't be established. +ECDSA key fingerprint is 25:cc:73:b5:b3:96:75:3d:56:19:49:d2:5c:1f:91:3b. Are you sure you want to continue connecting (yes/no)? <userinput>yes</userinput> -Host 'example.com' added to the list of known hosts. -user@example.com's password: <userinput>*******</userinput></screen> +Permanently added 'example.com' (ECDSA) to the list of known hosts. +Password for user@example.com: <userinput><replaceable>user_password</replaceable></userinput></screen> <para><acronym>SSH</acronym> utilizes a key fingerprint system to verify the authenticity of the server when the client - connects. The user is prompted to type - <literal>yes</literal> when connecting for the first time. + connects. When the user accepts the key's fingerprint by typing + <literal>yes</literal> when connecting for the first time, a + copy of the key is saved to + <filename>.ssh/known_hosts</filename> in the user's home directory. Future attempts to login are verified against the saved - fingerprint key and the &man.ssh.1; client will display an - alert if the saved fingerprint differs from the received - fingerprint on future login attempts. The fingerprints are - saved in <filename>~/.ssh/known_hosts</filename>.</para> - - <para>By default, recent versions of &man.sshd.8; only accept - <acronym>SSH</acronym> v2 connections. The client will use - version 2 if possible and 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 <option>-2</option> for version - 1 or version 2, respectively. The version 1 compatibility is - maintained in the client for backwards compatibility with - older versions.</para> + key and <command>ssh</command> will display an + alert if the server's key does not match the saved key. If + this occurs, the user should first verify + why the key has changed before continuing with the + connection.</para> + + <para>By default, recent versions of <application>OpenSSH</application> only accept + <acronym>SSH</acronym>v2 connections. By default, the client will use + version 2 if possible and will fall back to version 1 if the + server does not support version 2. To + force <command>ssh</command> to only use the specified protocol, include + <option>-1</option> or <option>-2</option>.</para> <indexterm> <primary>OpenSSH</primary> @@ -2501,128 +2511,122 @@ user@example.com's password: <userinput> <primary>&man.scp.1;</primary> </indexterm> - <para>Use &man.scp.1; to copy a file to or from a remote machine - in a secure fashion.</para> + <para>Use &man.scp.1; to securely copy a file to or from a remote machine. + This example copies <filename>COPYRIGHT</filename> on the + remote system to a file of the same name in the current + directory of the local system:</para> <screen>&prompt.root; <userinput>scp <replaceable>user@example.com:/COPYRIGHT COPYRIGHT</replaceable></userinput> -user@example.com's password: <userinput>*******</userinput> +Password for user@example.com: <userinput><replaceable>*******</replaceable></userinput> COPYRIGHT 100% |*****************************| 4735 00:00 &prompt.root;</screen> - <para>Since the fingerprint was already saved for this host in - the previous example, it is verified when using &man.scp.1; - here.</para> - - <para>The arguments passed to &man.scp.1; are similar to - &man.cp.1;, with the file or files to copy in the first - argument, and the destination in the second. Since the file - is fetched over the network, through an - <acronym>SSH</acronym>, connection, one or more of the file + <para>Since the fingerprint was already verified for this host, + the server's key is automatically checked before prompting for + the user's password.</para> + + <para>The arguments passed to <command>scp</command> are similar to + <command>cp</command>. The file or files to copy is the first + argument and the destination to copy to is the second. Since the file + is fetched over the network, one or more of the file arguments takes the form <option>user@host:<path_to_remote_file></option>.</para> <sect3 xml:id="security-ssh-keygen"> <title>Key-based Authentication</title> - <para>Instead of using passwords, &man.ssh-keygen.1; can be - used to generate <acronym>DSA</acronym> or - <acronym>RSA</acronym> keys to authenticate a user:</para> + <para>Instead of using passwords, a client can be configured + to connect to the remote machine + using keys instead of + passwords. To generate <acronym>DSA</acronym> or + <acronym>RSA</acronym> authentication keys, use + <command>ssh-keygen</command>. To generate a + public and private key pair, specify the type of key and + follow the prompts. It is recommended to protect the keys + with a memorable, but hard to guess passphrase.</para> <screen>&prompt.user; <userinput>ssh-keygen -t <replaceable>dsa</replaceable></userinput> Generating public/private dsa key pair. Enter file in which to save the key (/home/user/.ssh/id_dsa): Created directory '/home/user/.ssh'. -Enter passphrase (empty for no passphrase): -Enter same passphrase again: +Enter passphrase (empty for no passphrase): <replaceable>type some passphrase here which can contain spaces</replaceable> +Enter same passphrase again: <replaceable>type some passphrase here which can contain spaces</replaceable> Your identification has been saved in /home/user/.ssh/id_dsa. Your public key has been saved in /home/user/.ssh/id_dsa.pub. The key fingerprint is: bb:48:db:f2:93:57:80:b6:aa:bc:f5:d5:ba:8f:79:17 user@host.example.com</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/id_dsa</filename> or - <filename>~/.ssh/id_rsa</filename>, whereas the public key - is stored in <filename>~/.ssh/id_dsa.pub</filename> or - <filename>~/.ssh/id_rsa.pub</filename>, respectively for the - <acronym>DSA</acronym> and <acronym>RSA</acronym> key types. - The public key must be placed in + <para>Depending upon the specified protocol, the private key is stored + in <filename>~/.ssh/id_dsa</filename> (or + <filename>~/.ssh/id_rsa</filename>), and the public key + is stored in <filename>~/.ssh/id_dsa.pub</filename> (or + <filename>~/.ssh/id_rsa.pub</filename>). + The <emphasis>public</emphasis> key must be first copied to <filename>~/.ssh/authorized_keys</filename> on the remote - machine for both <acronym>RSA</acronym> or - <acronym>DSA</acronym> keys in order for the setup to + machine in order for key-based authentication to work.</para> - <para>This setup allows connections to the remote machine - based upon <acronym>SSH</acronym> keys instead of - passwords.</para> - <warning> <para>Many users believe that keys are secure by design and will use a key without a passphrase. This is - <emphasis>dangerous</emphasis> behavior and the method an - administrator may use to verify keys have a passphrase is - to view the key manually. If the private key file - contains the word <literal>ENCRYPTED</literal> the key - owner is using a passphrase. While it may still be a weak - passphrase, at least if the system is compromised, access - to other sites will still require some level of password - guessing. In addition, to better secure end users, the + <emphasis>dangerous</emphasis> behavior. An + administrator can verify that a key pair is protected by a passphrase + by viewing the private key manually. If the private key file + contains the word <literal>ENCRYPTED</literal>, the key + owner is using a passphrase. In addition, to better secure end users, <literal>from</literal> may be placed in the public key file. For example, adding - <literal>from="192.168.10.5</literal> in the front of + <literal>from="192.168.10.5"</literal> in the front of <literal>ssh-rsa</literal> or <literal>rsa-dsa</literal> prefix will only allow that specific user to login from - that host <acronym>IP</acronym>.</para> + that <acronym>IP</acronym> address.</para> </warning> - <warning> <para>The various options and files can be different according to the <application>OpenSSH</application> version. To avoid problems, consult &man.ssh-keygen.1;.</para> - </warning> - <para>If a passphrase is used in &man.ssh-keygen.1;, the user - will be prompted for the passphrase each time in order to - use the private key. To load <acronym>SSH</acronym> keys - into memory for use, without needing to type the passphrase + <para>If a passphrase is used, the user + will be prompted for the passphrase each time a connection + is made to the server. To load <acronym>SSH</acronym> keys + into memory, without needing to type the passphrase each time, use &man.ssh-agent.1; and &man.ssh-add.1;.</para> - <para>Authentication is handled by &man.ssh-agent.1;, using + <para>Authentication is handled by <command>ssh-agent</command>, using the private key(s) that are loaded into it. Then, - &man.ssh-agent.1; should be used to launch another - application. At the most basic level, it could spawn a + <command>ssh-agent</command> should be used to launch another + application such as a shell or a window manager.</para> - <para>To use &man.ssh-agent.1; in a shell, start it with a + <para>To use <command>ssh-agent</command> in a shell, start it with a shell as an argument. Next, add the identity by running - &man.ssh-add.1; and providing it the passphrase for the + <command>ssh-add</command> 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 + will be able to <command>ssh</command> 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: +Enter passphrase for /home/user/.ssh/id_dsa: <replaceable>type passphrase here</replaceable> Identity added: /home/user/.ssh/id_dsa (/home/user/.ssh/id_dsa) &prompt.user;</screen> - <para>To use &man.ssh-agent.1; in - <application>&xorg;</application>, a call to - &man.ssh-agent.1; needs to be placed in + <para>To use <command>ssh-agent</command> in + <application>&xorg;</application>, add an entry for it in <filename>~/.xinitrc</filename>. This provides the - &man.ssh-agent.1; services to all programs launched in + <command>ssh-agent</command> services to all programs launched in <application>&xorg;</application>. An example <filename>~/.xinitrc</filename> might look like this:</para> <programlisting>exec ssh-agent <replaceable>startxfce4</replaceable></programlisting> - <para>This launches &man.ssh-agent.1;, which in turn launches + <para>This launches <command>ssh-agent</command>, which in turn launches <application>XFCE</application>, every time <application>&xorg;</application> starts. Once <application>&xorg;</application> has been restarted so that - the changes can take effect, run &man.ssh-add.1; to load all + the changes can take effect, run <command>ssh-add</command> to load all of the <acronym>SSH</acronym> keys.</para> </sect3>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404101805.s3AI5XFJ061345>