README.ssh

This README file explains how to use base::ssh.

base::ssh can be used to enable and configure SSH for a system, with or without 
Duo.

base::ssh is a parameterized class.  If you include or require it without any 
parametes, here is what happens:

* The appropriate SSH server package is installed.
* A base::iptables::rule (named "ssh") is installed to allow port 22 
  connections from a number of subnets.
* Use the system's default PAM authentication process.
* A default SSH server config is installed (see below for details).
* A default SSH client config is installed (see below for details).
* root's authorized_keys files are deleted, so that nobody can slip in to the 
  system as root using pubkey authentication.
* A filter-syslog entry is installed to filter out less-useful SSH log entries.

This class is meant to be subclassed, especially so that you can replace 
Base::Iptables::Rule['ssh'] with your own 'source' list.  The source list that 
comes pre-configured is...

* 10.32.0.0/14
* 10.36.0.0/15
* 10.39.0.0/16
* 10.48.0.0/17
* 171.64.0.0/14
* 172.16.0.0/12
* 192.168.0.0/16
* 204.63.224.0/21

Remember that you may have an upstream firewall that is further restricting 
access to port 22.

For the SSH server configuration, many things can be customized by overriding 
various parameters to base::ssh::config::sshd.  Most parameters are booleans or 
integers.  If you don't customize anything, then the following configuration is 
made (customizeable parameters are called out):

* Listen on port 22 ('listen_ports' parameter, a comma-separated string).
* Listen on all addresses ('listen_addresses', a comma-separated string).
* Disable SSHv1.
* Only use RSA host keys.
* Ed25519 host keys are not used ('ed25519', a boolean).
* Increase the login timeout to 5 minutes.
* Limit authentication attempts to 5 ('max_tries', an integer).
* On RHEL-type systems, expicitly enable privilege separation.
* Disable the old Rhosts and RSA forms of authentication.
* Disable public-key authentication ('pubkey', a boolean).
* Disable host-based authentication ('hostbased', boolean).
* Allow challenge-response authentication, using PAM.
* Do not allow empty passwords, except for root (meant for use with GSSAPI).
* Allow GSSAPI authentication.  On new-enough systems, keep the remote Kerberos
  credentials cache refreshed, if possible.
* Don't allow password-based root logins ('rootloginwithpswd', boolean).
* Allow X forwarding, with a display offset of 10.
* Use TCP keep-alive.
* Enable sftp.

For the default SSH client configuration, GSSAPI is enabled, and on RHEL 
6+ GSSAPI key-exchange and GSSAPI DNS trust are enabled.  That's it.

base::ssh can also be configured to require Duo as a second authentication 
factor.  To enable this, set the "pam_duo" parameter to true.  When you do 
that, the following changes are made:

* On Debian wheezy, a backported OpenSSH is installed.
* In the SSH server configuration, require keyboard-interactive PAM-based 
  authentication (which triggers Duo) after GSSAPI or password authentication 
  is complete.
* Change the PAM configuration to use Duo.

Finally, there are a few other classes that you can use, for some extra 
functionality:

* If you don't care about failed login attempts, then include 
  base::ssh::ignore_fail to have login failures removed from your filtered 
  syslog output.

* If you also are OK with allowing SSH from anywhere, then include 
  base::ssh::global.

* If you want to allow pubkey-based authentications, then instead of doing the 
  override yourself you can just include base::ssh::pubkey.  That gets you the 
  additional benefit of adding successful pubkey authentications to 
  filter-syslog.

* If you have a system exposed to the Internet, you might want to include 
  base::ssh::defense, but BE SURE TO TEST IT!  This uses the "recent" iptables 
  module to start dropping SSH packets from a source if that source has made
  "limit" connection attempts in the last "secs" seconds.  If this happens, a 
  message is logged to syslog, and the SSH connection SYN packet is dropped.  
  "secs" and "limit" are parameters, defaulting to "300" and "3" 
  (respectively).  Using this class also overrides the SSH server config, 
  limting the number of authentication attempts to 2 per connection.