SSH Key Generation
==================

.. toctree::
   :maxdepth: 1
   :caption: Contents:

.. role:: underline
    :class: underline
    

About
-----

You need to follow the instructions below only if you need to generate a new SSH key-pair.

Linux and macOS
---------------

.. warning:: Here we recommend the generation and use of ECDSA key-pair instead of RSA one.

Open a terminal and type:

.. code:: console

 ssh-keygen -t ecdsa -b 521 -f ~/.ssh/id_ecdsa

.. note:: You will be required to enter a password for protecting the secret/private key information. Supply a strong password, which you do not use as a login password. If you forget that password, you cannot use the private key again (unless you have a copy encrypted with a password you still remember)!

Upon success, the private key will be stored alone (in encrypted form) inside the file:

.. code:: console

 ~/.ssh/id_ecdsa

and the public key will be available in:

.. code:: console

 ~/.ssh/id_ecdsa.pub

.. warning:: **Never send or disclose the content of ~/.ssh/id_ecdsa.** During the onboarding process, you need to send/share only the content of ~/.ssh/id_ecdsa.pub. Create a copy of that file and keep in a safe place. Store the password for decrypting the key into some reliable password storage/manager.

If you need to share the public key, just type:

.. code:: console

 cat ~/.ssh/id_ecdsa.pub

and copy the content displayed on the terminal.


Windows
-------

The best way you can generate OpenSSH key-pair on Windows is by using PuTTYgen. PuTTYgen is a tool included in the standard installation of PuTTY. To install PuTTY find and download the installer at:

https://www.putty.org/

.. warning:: Always run the most recent version of PuTTY tools.

To run PuTTYgen go to the seach bar of Windows, type there "puttygen" (1) and click on the application icon (2):

.. image:: _images/puttygen_01.png

Then select "ECDSA" (1), "nist-521" from the menu (2), and press button "Generate" (3):

.. image:: _images/puttygen_02.png

Move the mouse over the blank area until the progress bar reaches the right end:

.. image:: _images/puttygen_03.png

Once the key generation is successfully completed, you have to specify some comment to the key (1), but do not include there any blank spaces or special symbols, then supply twice a strong password for protecting the private key from disclosure (2), and to press the button "Save private key" (3):

.. image:: _images/puttygen_04.png

.. note:: Supply a strong password, which you do not use as a login password. If you forget that password, you cannot use the private key (unless you have a copy encrypted with a password you still remember)!

Specify the location and file name containing the private key:

.. image:: _images/puttygen_05.png

.. warning:: **Never send or disclose the content of the file containing the private key.** Create a copy of that file and keep in a safe place. Store the password for decrypting the key into some reliable password storage/manager.

Getting help
------------

See :doc:`help`