2 keygen

What Is ?

is a tool for creating new authentication key pairs for SSH. Such key pairs are used for automating logins, single sign-on, and for authenticating hosts.

SSH Keys and Public Key Authentication

The SSH protocol uses public key cryptography for authenticating hosts and users. The authentication keys, called SSH keys, are created using the program.

SSH introduced public key authentication as a more secure alternative to the older authentication. It improved security by avoiding the need to have password stored in files, and eliminated the possibility of a compromised server stealing the user's password.

However, SSH keys are authentication credentials just like passwords. Thus, they must be managed somewhat analogously to user names and passwords. They should have a proper termination process so that keys are removed when no longer needed.

Creating an SSH Key Pair for User Authentication

The simplest way to generate a key pair is to run without arguments. In this case, it will prompt for the file in which to store keys. Here's an example:

First, the tool asked where to save the file. SSH keys for user authentication are usually stored in the user's directory under the home directory. However, in enterprise environments, the location is often different. The default key file name depends on the algorithm, in this case when using the default RSA algorithm. It could also be, for example, or .

Then it asks to enter a passphrase. The passphrase is used for encrypting the key, so that it cannot be used even if someone obtains the private key file. The passphrase should be cryptographically strong. Our online random password generator is one possible tool for generating strong passphrases.

Choosing an Algorithm and Key Size

SSH supports several public key algorithms for authentication keys. These include:

• - an old algorithm based on the difficulty of factoring large numbers. A key size of at least 2048 bits is recommended for RSA; 4096 bits is better. RSA is getting old and significant advances are being made in factoring. Choosing a different algorithm may be advisable. It is quite possible the RSA algorithm will become practically breakable in the foreseeable future. All SSH clients support this algorithm.

• - an old US government Digital Signature Algorithm. It is based on the difficulty of computing discrete logarithms. A key size of 1024 would normally be used with it. DSA in its original form is no longer recommended.

• - a new Digital Signature Algorithm standarized by the US government, using elliptic curves. This is probably a good algorithm for current applications. Only three key sizes are supported: 256, 384, and 521 (sic!) bits. We would recommend always using it with 521 bits, since the keys are still small and probably more secure than the smaller keys (even though they should be safe as well). Most SSH clients now support this algorithm.

• - this is a new algorithm added in OpenSSH. Support for it in clients is not yet universal. Thus its use in general purpose applications may not yet be advisable.

The algorithm is selected using the option and key size using the option. The following commands illustrate:

Specifying the File Name

Normally, the tool prompts for the file in which to store the key. However, it can also be specified on the command line using the option.

Copying the Public Key to the Server

To use public key authentication, the public key must be copied to a server and installed in an authorized_keys file. This can be conveniently done using the ssh-copy-id tool. Like this:

Once the public key has been configured on the server, the server will allow any connecting user that has the private key to log in. During the login process, the client proves possession of the private key by digitally signing the key exchange.

Adding the Key to SSH Agent

is a program that can hold a user's private key, so that the private key passphrase only needs to be supplied once. A connection to the agent can also be forwarded when logging into a server, allowing SSH commands on the server to use the agent running on the user's desktop.

For more information on using and configuring the SSH agent, see the ssh-agent page.

Creating Host Keys

The tool is also used for creating host authentication keys. Host keys are stored in the directory.

Host keys are just ordinary SSH key pairs. Each host can have one host key for each algorithm. The host keys are almost always stored in the following files:

The host keys are usually automatically generated when an SSH server is installed. They can be regenerated at any time. However, if host keys are changed, clients may warn about changed keys. Changed keys are also reported when someone tries to perform a man-in-the-middle attack. Thus it is not advisable to train your users to blindly accept them. Changing the keys is thus either best done using an SSH key management tool that also changes them on clients, or using certificates.

Using X.509 Certificates for Host Authentication

OpenSSH does not support X.509 certificates. Tectia SSH does support them. X.509 certificates are widely used in larger organizations for making it easy to change host keys on a period basis while avoiding unnecessary warnings from clients. They also allow using strict host key checking, which means that the clients will outright refuse a connection if the host key has changed.

Using OpenSSH's Proprietary Certificates

OpenSSH has its own proprietary certificate format, which can be used for signing host certificates or user certificates. For user authentication, the lack of highly secure certificate authorities combined with the inability to audit who can access a server by inspecting the server makes us recommend against using OpenSSH certificates for user authentication.

However, OpenSSH certificates can be very useful for server authentication and can achieve similar benefits as the standard X.509 certificates. However, they need their own infrastructure for certificate issuance. See more information on certificate authentication.

Key Management Requires Attention

It is easy to create and configure new SSH keys. In the default configuration, OpenSSH allows any user to configure new keys. The keys are permanent access credentials that remain valid even after the user's account has been deleted.

In organizations with more than a few dozen users, SSH keys easily accumulate on servers and service accounts over the years. We have seen enterprises with several million keys granting access to their production servers. It only takes one leaked, stolen, or misconfigured key to gain access.

In any larger organization, use of SSH key management solutions is almost necessary. SSH keys should also be moved to root-owned locations with proper provisioning and termination processes. For more information, see how to manage SSH keys. A widely used SSH key management tool for OpenSSH is Universal SSH Key Manager.

Practically all cybersecurity regulatory frameworks require managing who can access what. SSH keys grant access, and fall under this requirement. This, organizations under compliance mandates are required to implement proper management processes for the keys. NIST IR 7966 is a good starting point.

Make Sure There Is Enough Randomness

It is important to ensure there is enough unpredictable entropy in the system when SSH keys are generated. There have been incidents when thousands of devices on the Internet have shared the same host key when they were improperly configured to generate the key without proper randomness.

General Purpose Systems

On general purpose computers, randomness for SSH key generation is usually not a problem. It may be something of an issue when initially installing the SSH server and generating host keys, and only people building new Linux distributions or SSH installation packages generally need to worry about it.

Our recommendation is to collect randomness during the whole installation of the operating system, save that randomness in a random seed file. Then boot the system, collect some more randomness during the boot, mix in the saved randomness from the seed file, and only then generate the host keys. This maximizes the use of the available randomness. And make sure the random seed file is periodically updated, in particular make sure that it is updated after generating the SSH host keys.

Many modern general-purpose CPUs also have hardware random number generators. This helps a lot with this problem. The best practice is to collect some entropy in other ways, still keep it in a random seed file, and mix in some entropy from the hardware random number generator. This way, even if one of them is compromised somehow, the other source of randomness should keep the keys secure.

Embedded Devices and Internet of Things

Available entropy can be a real problem on small IoT devices that don't have much other activity on the system. They may just not have the mechanical randomness from disk drive mechanical movement timings, user-caused interrupts, or network traffic. Furthermore, embedded devices often run on low-end processors that may not have a hardware random number generator.

The availability of entropy is also critically important when such devices generate keys for HTTPS.

Our recommendation is that such devices should have a hardware random number generator. If the CPU does not have one, it should be built onto the motherboard. The cost is rather small.

Command and Option Summary

Here's a summary of commonly used options to the keygen tool:

-b “Bits” This option specifies the number of bits in the key. The regulations that govern the use case for SSH may require a specific key length to be used. In general, 2048 bits is considered to be sufficient for RSA keys.

-e “Export” This option allows reformatting of existing keys between the OpenSSH key file format and the format documented in RFC 4716, “SSH Public Key File Format”.

-p “Change the passphrase” This option allows changing the passphrase of a private key file with and , .

-t “Type” This option specifies the type of key to be created. Commonly used values are: - rsa for RSA keys - dsa for DSA keys - ecdsa for elliptic curve DSA keys

-i "Input" When ssh-keygen is required to access an existing key, this option designates the file.

-f "File" Specifies name of the file in which to store the created key.

-N "New" Provides a new passphrase for the key.

-P "Passphrase" Provides the (old) passphrase when reading a key.

-c "Comment" Changes the comment for a keyfile.

-p Change the passphrase of a private key file.

-q Silence ssh-keygen.

-v Verbose mode.

-l "Fingerprint" Print the fingerprint of the specified public key.

-B "Bubble babble" Shows a "bubble babble" (Tectia format) fingerprint of a keyfile.

-F Search for a specified hostname in a known_hosts file.

-R Remove all keys belonging to a hostname from a known_hosts file.

-y Read a private OpenSSH format file and print an OpenSSH public key to stdout.

This only listed the most commonly used options. For full usage, including the more exotic and special-purpose options, use the command.

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ssh-keygen&sektion=1&manpath=OpenBSD+3.4>

About SSH Keys

Secure Shell (better known as SSH) is a cryptographic network protocol which allows users to securely perform a number of network services over an unsecured network. SSH keys provide a more secure way of logging into a server with SSH than using a password alone. While a password can eventually be cracked with a brute force attack, SSH keys are nearly impossible to decipher by brute force alone.

Generating a key pair provides you with two long string of characters: a public and a private key. You can place the public key on any server, and then unlock it by connecting to it with a client that already has the private key. When the two match up, the system unlocks without the need for a password. You can increase security even more by protecting the private key with a passphrase.

Within some of the commands found in this tutorial, you will notice some highlighted values. These are variables, and you should substitute them with your own values.

Step One—Create the RSA Key Pair

The first step is to create the key pair on the client machine (there is a good chance that this will just be your computer):

Step Two—Store the Keys and Passphrase

Once you have entered the Gen Key command, you will get a few more questions:

You can press enter here, saving the file to the user home (in this case, my example user is called demo).

It’s up to you whether you want to use a passphrase. Entering a passphrase does have its benefits: the security of a key, no matter how encrypted, still depends on the fact that it is not visible to anyone else. Should a passphrase-protected private key fall into an unauthorized users possession, they will be unable to log in to its associated accounts until they figure out the passphrase, buying the hacked user some extra time. The only downside, of course, to having a passphrase, is then having to type it in each time you use the key pair.

The entire key generation process looks like this:

The public key is now located in . The private key (identification) is now located in .

Step Three—Copy the Public Key

Once the key pair is generated, it’s time to place the public key on the server that we want to use.

You can copy the public key into the new machine’s authorized_keys file with the ssh-copy-id command. Make sure to replace the example username and IP address below.

Note: If you are a Mac user, ssh-copy-id will not be installed on your machine. You can, however, install it using Homebrew:

Alternatively, you can paste in the keys using SSH:

No matter which command you chose, you may see something like:

This message helps us to make sure that we haven’t added extra keys that you weren’t expecting.

Now you can go ahead and log into your user profile and you will not be prompted for a password. However, if you set a passphrase when creating your SSH key, you will be asked to enter the passphrase at that time (and whenever else you log in in the future).

Optional Step Four—Disable the Password for Root Login

Once you have copied your SSH keys onto your server and ensured that you can log in with the SSH keys alone, you can go ahead and restrict the root login to only be permitted via SSH keys.

In order to do this, open up the SSH config file:

Within that file, find the line that includes and modify it to ensure that users can only connect with their SSH key:

Save and close the file when you are finished.

To put these changes into effect:

DigitalOcean Addendum

The DigitalOcean control panel allows you to add public keys to your new Droplets when they’re created. You can generate the SSH Key in a convenient location, such as the computer, and then upload the public key to the SSH key section.

Then, when you create a new Droplet, you can choose to include that public key on the server. No root password will be emailed to you and you can log in to your new server from your chosen client. If you created a passphrase, you will be prompted to enter that upon login.

<div class=“author”>By Etel Sverdlov</div>