########
SSH Keys
########

.. note:: This article is provided as a courtesy to our customers. SSH is a network service included with most Linux distributions. If you have specific questions or problems with SSH or using key based authentication please contact your OS vendor. 

**SSH is not provided by, nor is it part of any Atomicorp product and therefore is not supported by Atomicorp**

--------------

Discussion
==========

The Secure Shell Service, or SSH for short, is a replacement service for the telnet and rsh services. These two services 
while in widespread use across all UNIX variants, industrial control systems, VMS systems and even Windows based systems 
provide no meaningful security to prevent an attacker from either hijacking sessions with these services, or simply 
stealing credentials as they are sent to the server. The SSH protocol was developed to rememdy the short comings in these
protocols by providing both session encryption and integrity protections to ensure that an attacker could not hijack an 
SSH session, or steal credentials sent over the protocol.

As a modern protocol, SSH also supports a number of different mechanisms for authentication mechanisms of increasing 
strength. One of the most popular strong authentication systems in SSH is key based authentication. This allows a user 
to associate a cryptographic key with their account, which requires the user to prove they have custody of the key. Keys 
can also have passwords applied to them, and when this is used this provides for a two factor mechanism of authentication:

   1. What you have (the key)
   2. What you know (the password for the key)
   
Unlike password only based authentication, where you simply have to know the password, this added factor makes password 
guessing attacks impossible against the users account on the server (if and only if password authentication is disabled, 
if password authentication is not disabled then password guessing attacks are still possible).

---------------

How to Disable SSH Password Authentication with AP 
===================================================

**Step 1: Define Admin User(s)**

   See the ADMIN_USERS configuration setting of AP. 
   
   .. note:: If an Admin User is not defined, by default AP will not allow any SSH configurations to be made and will also try to prevent other applications from changing these settings as well. This is an important failsafe to prevent users from accidentally disabling password authentication without a working account with working SSH keys. We do not recommend you disable this. Defining an Admin User is a good thing to do.
   
   .. note:: as explained at the link above, if the Admin Users account either does not exist, or SSH keys are not configured correct (as explained at the URL above), AP will not allow password authentication to be disabled. This means the SSH keys may not work for that user, which will of course prevent that user from being able to log in.
   
   
**Step 2: Disable Password Authentication**

   See the SSH_PASSWORD_AUTH configuration setting of AP. 
   
   .. note:: As explained above, if an Admin User is not defined, by default AP will not allow any SSH configuration changes to be made. 
   
   
--------------

How to Create and Install Keys
==============================

   **Linux**
   
      * To use key based authentication with SSH you will need to generate a key and you will need to protect the key. 
	  
      .. note:: Do not generate your key on the server. You should only generate your key on your workstation, laptop, etc. and then protect the key with both a strong password, and we also recommend you use drive based encryption to ensure the key can not be stolen from your hard drive should you lose physical custody of the drive.
	  
      **Step 1:** Become the use you want to log into the server as by running the following command:
	  
         .. code-block:: console
		 
            su - <yourusername>
			
         .. note:: We do not recommend you do this as root. 
		 
      **Step 2:** Generate a strong key by running the following command:
	  
         .. code-block:: console 
		 
            ssh-keygen -b 4096
			
         This could take a long time, so please be patient. 
		 
         The software will then ask where you want to store the key pair, we recommend going with the defaults. 
		 
         The software will then ask you to put a password on the key. **ALWAYS put a password on your SSH keys.** Otherwise, if they are stolen, anyone will be able to log into your server without any password required. Pick a strong passphrase for your key. We recommend you use a sentence you will remember. For example "In 2014 I Will Take a Walk Every Day!"
		 
         .. note:: The strength of cryptographic algorithms is an ongoing science and as weaknesses are found in algorithms the risk of continuing to use them should be careful analyzed, and new keys using new and proven stronger algorithms may need to be generated. We also recommend you replace your keys periodically, this helps to ensure if they are stolen that they will be no use to an attacker.
		 
      **Step 3:** Copy your **public** key to the server:
	  
         Your public key is stored in a file that ends with .pub. By default this will be named **id_rsa.pub**
		 
         * Login into your server by running the following command:
		 
            .. code-block:: console
			
               ssh -l yourusername servername
			   
         * Create the .ssh directory and change it's permissions by running the following commands:
		 
            .. code-block:: console
			
               mkdir .ssh 
               chmod og-rwx ~/.ssh
			   
         * Create the authorized_keys file and change it's permissions by running the following commands:
		 
            .. code-block:: console
			
               touch ~/.ssh/authorized_keys
               chmod og-rwx ~/.ssh/authorized_keys			   

         * Log out of your sever by running the following command:
		 
            .. code-block:: console
			
               exit
			   
         * Copy your SSH **public** key to the remote server by running the following command:
		 
            .. code-block:: console
			
               scp ~/.ssh/id_rsa.pub yourusername@yourserver:.ssh/authorized_keys
			   
         * Test the login by running the following command:
		 
            .. code-block:: console 
			
               ssh yourusername@yourserver
			   
   **Windows**
   
      * Please see the video tutorials `here`_ for more information about setting up SSH on a Windows client. 
	  
      .. _here: https://www.atomicorp.com/Tutorials/
