oreilly.comSafari Books Online.Conferences.


O'Reilly Book Excerpts: SSH, The Secure Shell: The Definitive Guide

SSH Public-Key Authentication

Related Reading

SSH, The Secure Shell: The Definitive Guide
By Daniel J. Barrett, Richard E. Silverman

by Daniel J. Barrett and Richard E. Silverman

Editor's Note: Public-key authentication allows you to connect to a remote server without sending your password over the Internet. Public-key authentication uses two keys, a private key that only you have--it should be kept in a secure place and protected with a password. And the public key, which is placed on the server you wish to gain access to, usually by the system administrator when your account is set up.

To set up public-key authentication in your account on an SSH server machine, you create an authorization file, typically called authorized_keys (SSH1, OpenSSH/1), authorized_keys2 (OpenSSH/2), or authorization (SSH2), and list the keys that provide access to your account. Well, we've been keeping a secret. Your authorization file can contain not only keys but also other keywords or options to control the SSH server in powerful ways.

As we demonstrate how to modify your authorization file, remember that the file is consulted by the SSH server only at authentication time. Therefore, if you change your authorization file, only new connections will use the new information. Any existing connections are already authenticated and won't be affected by the change.

Also remember that an incoming connection request won't reach your authorization file if the SSH server rejects it for other reasons, namely, failing to satisfy the serverwide configuration. If a change to your authorization file doesn't seem to be having an effect, make sure it doesn't conflict with a (more powerful) serverwide configuration setting.

SSH1 Authorization Files

Your SSH1 authorized_keys file, generally found in ~/.ssh/authorized_keys, is a secure doorway into your account via the SSH-1 protocol. Each line of the file contains a public key and means the following: "I give permission for SSH-1 clients to access my account, in a particular way, using this key as authentication." Notice the words "in a particular way." Until now, public keys have provided unlimited access to an account. Now we'll see the rest of the story.

Each line of authorized_keys contains up to three items in order, some optional and some required:

  • A set of options (optional, surprise, surprise).

  • The public key (required). This appears in three parts:

  • The number of bits in the key, typically a small integer such as 1024

  • The exponent of the key: an integer

  • The modulus of the key: a very large integer, typically several hundred digits long

  • A descriptive comment (optional). This can be any text, such as "Bob's public key" or "My home PC using SecureCRT 3.1."

Public keys and comments are generated by ssh-keygen in .pub files, you may recall, and you typically insert them into authorized_keys by copying. Options, however, are usually typed into authorized_keys with a text editor.

An option may take two forms. It may be a keyword, such as:

# SSH1, OpenSSH: Turn off port forwarding

or it may be a keyword followed by an equals sign and a value, such as:

# SSH1, OpenSSH: Set idle timeout to five minutes

Multiple options may be given together, separated by commas, with no whitespace between the options:

# SSH1, OpenSSH

If you mistakenly include whitespace:

# THIS IS ILLEGAL: whitespace between the options
no-port-forwarding, idle-timeout=5m 

your connection by this key won't work properly. If you connect with debugging turned on (ssh1 -v), you will see a "syntax error" message from the SSH server.

Many SSH users aren't aware of options or neglect to use them. This is a pity because options provide extra security and convenience. The more you know about the clients that access your account, the more options you can use to control that access.

SSH2 Authorization Files

An SSH2 authorization file, typically found in ~/.ssh2/authorization, has a different format from its SSH1 ancestor. Instead of public keys, it contains keywords and values, much like other SSH configuration files we've seen. Each line of the file contains one keyword followed by its value. The most commonly used keywords are Key and Command.

Public keys are indicated using the Key keyword. Key is followed by whitespace, and then the name of a file containing a public key. Relative filenames refer to files in ~/.ssh2. For example:

# SSH2 only

means that an SSH-2 public key is contained in ~/.ssh2/ Your authorization file must contain at least one Key line for public-key authentication to occur.

Each Key line may optionally be followed immediately by a Command keyword and its value. Command specifies a forced command, i.e., a command to be executed whenever the key immediately above is used for access. We discuss forced commands later in great detail. (See Ch. 8: Forced Commands.) For now, all you need to know is this: a forced command begins with the keyword Command, is followed by whitespace, and ends with a shell command line. For example:

# SSH2 only
Command "/bin/echo All logins are disabled" 

Remember that a Command line by itself is an error. The following examples are illegal:

# THIS IS ILLEGAL: no Key line
Command "/bin/echo This line is bad." 
# THIS IS ILLEGAL: no Key line precedes the second Command
Command "/bin/echo All logins are disabled"
Command "/bin/echo This line is bad." 

SSH2 PGP key authentication

SSH2 Version 2.0.13 introduced support for PGP authentication. Your authorization file may also include PgpPublicKeyFile, PgpKeyName, PgpKey Fingerprint, and PgpKeyId lines. A Command line may follow PgpKeyName, PgpKeyFingerprint, or PgpKeyId, just as it may follow Key:

# SSH2 only
PgpKeyName my-key
Command "/bin/echo PGP authentication was detected" 

OpenSSH Authorization Files

For SSH-1 protocol connections, OpenSSH/1 uses the same authorized_keys file as SSH1. All configuration that's possible with SSH1 is available within OpenSSH/1.

For SSH-2 connections, OpenSSH/2 takes a new approach unlike SSH2's: a new authorization file, ~/.ssh/authorized_keys2, with a format similar to that of authorized_keys. Each line may contain:

  • Key authorization options (optional)

  • The string "ssh-dss" (required)

  • The DSA public key, represented as a long string (required)

  • A descriptive comment (optional)

Here's an example with the long public key abbreviated:

host= ssh-dss AAAAB3NzaC1kc3MA... My OpenSSH key 

With this information, we should be able to generate an SSH key pair and place the public key on the machine we wish to use. This should provide basic, but secure authentication to a remote server without sending any passwords over the Internet.

Daniel J. Barrett has been immersed in Internet technology since 1985. Currently, he is working as a software engineer. He is the author of O'Reilly's Linux Pocket Guide, and the coauthor of two more O'Reilly books: Linux Security Cookbook, and SSH, The Secure Shell: The Definitive Guide.

Richard E. Silverman first touched a computer as a college junior in 1986, when he logged into a DEC-20, typed "MM" to send some mail, and was promptly lost to the world.

Return to

Sponsored by: