From owner-svn-doc-all@FreeBSD.ORG Thu Apr 10 18:05:33 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id B2CB6305; Thu, 10 Apr 2014 18:05:33 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 84ADD115E; Thu, 10 Apr 2014 18:05:33 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s3AI5Xnw061346; Thu, 10 Apr 2014 18:05:33 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s3AI5XFJ061345; Thu, 10 Apr 2014 18:05:33 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201404101805.s3AI5XFJ061345@svn.freebsd.org> From: Dru Lavigne Date: Thu, 10 Apr 2014 18:05:33 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 10 Apr 2014 18:05:33 -0000 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" OpenSSH 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, TCP/IP connections can be tunneled or forwarded securely through SSH connections. OpenSSH encrypts all traffic to effectively eliminate eavesdropping, connection hijacking, and @@ -2456,6 +2456,11 @@ racoon_enable="yes" authentication and encryption methods to prevent this from happening. + 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 + SSH server on a &os; system. + Using the SSH Client Utilities @@ -2464,34 +2469,39 @@ racoon_enable="yes" client - To use &man.ssh.1; to connect to a system running - &man.sshd.8;, specify the username and host to log - into: + To log into a SSH server, use + ssh and specify a username that exists on + that server and the IP 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: &prompt.root; ssh user@example.com -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)? yes -Host 'example.com' added to the list of known hosts. -user@example.com's password: ******* +Permanently added 'example.com' (ECDSA) to the list of known hosts. +Password for user@example.com: user_password SSH utilizes a key fingerprint system to verify the authenticity of the server when the client - connects. The user is prompted to type - yes when connecting for the first time. + connects. When the user accepts the key's fingerprint by typing + yes when connecting for the first time, a + copy of the key is saved to + .ssh/known_hosts 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 ~/.ssh/known_hosts. - - By default, recent versions of &man.sshd.8; only accept - SSH 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 or for version - 1 or version 2, respectively. The version 1 compatibility is - maintained in the client for backwards compatibility with - older versions. + key and ssh 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. + + By default, recent versions of OpenSSH only accept + SSHv2 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 ssh to only use the specified protocol, include + or . OpenSSH @@ -2501,128 +2511,122 @@ user@example.com's password: &man.scp.1; - Use &man.scp.1; to copy a file to or from a remote machine - in a secure fashion. + Use &man.scp.1; to securely copy a file to or from a remote machine. + This example copies COPYRIGHT on the + remote system to a file of the same name in the current + directory of the local system: &prompt.root; scp user@example.com:/COPYRIGHT COPYRIGHT -user@example.com's password: ******* +Password for user@example.com: ******* COPYRIGHT 100% |*****************************| 4735 00:00 &prompt.root; - Since the fingerprint was already saved for this host in - the previous example, it is verified when using &man.scp.1; - here. - - 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 - SSH, connection, one or more of the file + Since the fingerprint was already verified for this host, + the server's key is automatically checked before prompting for + the user's password. + + The arguments passed to scp are similar to + cp. 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 . Key-based Authentication - Instead of using passwords, &man.ssh-keygen.1; can be - used to generate DSA or - RSA keys to authenticate a user: + Instead of using passwords, a client can be configured + to connect to the remote machine + using keys instead of + passwords. To generate DSA or + RSA authentication keys, use + ssh-keygen. 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. &prompt.user; ssh-keygen -t dsa 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): type some passphrase here which can contain spaces +Enter same passphrase again: type some passphrase here which can contain spaces 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 - &man.ssh-keygen.1; will create a public and private key - pair for use in authentication. The private key is stored - in ~/.ssh/id_dsa or - ~/.ssh/id_rsa, whereas the public key - is stored in ~/.ssh/id_dsa.pub or - ~/.ssh/id_rsa.pub, respectively for the - DSA and RSA key types. - The public key must be placed in + Depending upon the specified protocol, the private key is stored + in ~/.ssh/id_dsa (or + ~/.ssh/id_rsa), and the public key + is stored in ~/.ssh/id_dsa.pub (or + ~/.ssh/id_rsa.pub). + The public key must be first copied to ~/.ssh/authorized_keys on the remote - machine for both RSA or - DSA keys in order for the setup to + machine in order for key-based authentication to work. - This setup allows connections to the remote machine - based upon SSH keys instead of - passwords. - Many users believe that keys are secure by design and will use a key without a passphrase. This is - dangerous 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 ENCRYPTED 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 + dangerous 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 ENCRYPTED, the key + owner is using a passphrase. In addition, to better secure end users, from may be placed in the public key file. For example, adding - from="192.168.10.5 in the front of + from="192.168.10.5" in the front of ssh-rsa or rsa-dsa prefix will only allow that specific user to login from - that host IP. + that IP address. - The various options and files can be different according to the OpenSSH version. To avoid problems, consult &man.ssh-keygen.1;. - - 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 SSH keys - into memory for use, without needing to type the passphrase + If a passphrase is used, the user + will be prompted for the passphrase each time a connection + is made to the server. To load SSH keys + into memory, without needing to type the passphrase each time, use &man.ssh-agent.1; and &man.ssh-add.1;. - Authentication is handled by &man.ssh-agent.1;, using + Authentication is handled by ssh-agent, 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 + ssh-agent should be used to launch another + application such as a shell or a window manager. - To use &man.ssh-agent.1; in a shell, start it with a + To use ssh-agent 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 + ssh-add 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 ssh to any host that has the corresponding public key installed. For example: &prompt.user; ssh-agent csh &prompt.user; ssh-add -Enter passphrase for /home/user/.ssh/id_dsa: +Enter passphrase for /home/user/.ssh/id_dsa: type passphrase here Identity added: /home/user/.ssh/id_dsa (/home/user/.ssh/id_dsa) &prompt.user; - To use &man.ssh-agent.1; in - &xorg;, a call to - &man.ssh-agent.1; needs to be placed in + To use ssh-agent in + &xorg;, add an entry for it in ~/.xinitrc. This provides the - &man.ssh-agent.1; services to all programs launched in + ssh-agent services to all programs launched in &xorg;. An example ~/.xinitrc might look like this: exec ssh-agent startxfce4 - This launches &man.ssh-agent.1;, which in turn launches + This launches ssh-agent, which in turn launches XFCE, every time &xorg; starts. Once &xorg; has been restarted so that - the changes can take effect, run &man.ssh-add.1; to load all + the changes can take effect, run ssh-add to load all of the SSH keys.