[Contents] [Index]

About This Document>>     Introduction to SSH Secure Shell >>     Configuring SSH Secure Shell >>     Authentication >>         Server Authentication>>         User Authentication>>             Password Authentication             Public-Key Authentication             Host-Based Authentication             Certificate Authentication             Kerberos Authentication             Pluggable Authentication Module (PAM)             SecurID         Keyboard-Interactive Authentication >>     Log Messages >>     Using SSH Secure Shell >>     Tool Syntax>>     Technical Specifications >>

Public-Key Authentication

Per-user configuration information and encryption keys are by default stored in the .ssh2 subdirectory of each user's home directory.

In the following instructions, Remote is the SSH Secure Shell server machine into which you are trying to connect, and Local is the machine running an SSH Secure Shell client.

Keys Generated with ssh-keygen2

In order to set up user public-key authentication, do a manual setup according to the following instructions.

The following terms will be used in this example: Remote is the SSH Secure Shell server into which you are trying to connect. RemoteUser is the user name on the server into which you would like to login. Local is the machine running a SSH Secure Shell client. LocalUser is the user name on the client machine that should be allowed to login to Remote as RemoteUser.

1. To make sure that public-key authentication is enabled, the AllowedAuthentications field in both the /etc/ssh2/sshd2_config file on Remote and in the /etc/ssh2/ssh2_config file on Local should contain the word publickey:

   AllowedAuthentications   publickey 
   

   Other authentication methods can be listed in the configuration file as well.

2. Create a key pair by executing ssh-keygen2 on Local.

   Local> ssh-keygen2
   Generating 2048-bit dsa key pair
      1 oOo.oOo.o
   Key generated.
   2048-bit dsa, user@Local, Wed Mar 22 2002 00:13:43 +0200
   Passphrase : 
   Again :
   Private key saved to  /home/user/.ssh2/id_dsa_2048_a
   Public key saved to   /home/user/.ssh2/id_dsa_2048_a.pub
   

   Ssh-keygen2 will now ask for a passphrase for the new key. Enter a sufficiently long (20 characters or so) sequence of any characters (spaces are OK). Ssh-keygen2 creates a .ssh2 directory in your home directory (if it is not already present), and stores your new authentication key pair in two separate files. One of the keys is your private key which must never be made available to anyone but yourself. The private key can only be used together with the passphrase. In the example above, the private key file is id_dsa_2048_a. The other file id_dsa_2048_a.pub is your public key, which can be distributed to other computers. Note: Beginning with version 3.0, SSH Secure Shell includes support for RSA keys. They can be generated by specifying the -t flag with ssh-keygen2.

   Local> ssh-keygen2 -t rsa    
   Generating 2048-bit rsa key pair
      2 oOo.ooOo.oOo
   Key generated.
   2048-bit rsa, user@Local, Wed May 02 2002 14:15:41 +0300
   Passphrase : 
   Again      : 
   Private key saved to /home/user/.ssh2/id_rsa_2048_a
   Public key saved to /home/user/.ssh2/id_rsa_2048_a.pub
   

3. Create an identification file in your ~/.ssh2 directory on Local.

   Local> cd ~/.ssh2
   Local> echo "IdKey id_dsa_2048_a" > identification
   

   You now have an identification file which consists of one line that denotes the file containing your identification (your private key). For special applications, you can create multiple identifications by executing ssh-keygen2 again. This is, however, not usually needed.
4. Copy your public key (id_dsa_2048_a.pub) to your ~/.ssh2 directory on Remote.
5. Create an authorization file in your ~/.ssh2 directory on Remote. Add the following line to the authorization file:

   Key     id_dsa_2048_a.pub
   

   This directs the SSH Secure Shell server to use id_dsa_2048_a.pub as a valid public key when authorizing your login. If you want to login to Remote from other hosts, create a key pair on the hosts (steps 1 and 2) and repeat steps 3, 4, and 5 on Remote. (Remember to specify a different file name for each key pair.)
6. Now you should be able to login to Remote from Local using SSH Secure Shell. Try to login:

   Local>ssh Remote
   Passphrase for key "/home/user/.ssh2/id_dsa_1024_a
   with comment "2048-bit dsa, created by user@Local 
   Wed Mar 22 2002 00:13:43 +0200":
   

   After you have entered the passphrase of your private key, a Secure Shell connection will be established.

Keys Generated with ssh-keygen1

Beginning with version 3.0, SSH Secure Shell enables the usage of keys generated with ssh-keygen1. However, the keys must be converted from the ssh1 format to ssh2 format.

$ ssh-keygen2 -1 <keyname>.pub 
Successfully converted public key to <keyname>.pub_ssh2
$ ssh-keygen2 -1 <keyname>     
Passphrase : 
Successfully converted private key to <keyname>_ssh2

PGP Keys

SSH Secure Shell only supports the OpenPGP standard and the PGP programs conforming to it. GnuPG is used in the following instructions. If you use PGP, the only difference is that the file extension is pgp instead of GnuPGP's gpg.

1. To make sure that user public-key authentication is enabled, the AllowedAuthentications field both in the /etc/ssh2/sshd2_config file on Remote and the /etc/ssh2/ssh2_config file on Local should contain the word publickey:

   AllowedAuthentications   publickey
   

   Other authentication methods can be listed in the configuration file as well.
2. Copy your private key ring (secring.gpg) to the ~/.ssh2 directory on Local.
3. Create an identification file in your ~/.ssh2 directory on Local if you do not already have one. Add the following lines to the identification file:

   PgpSecretKeyFile    <filename of the user's private key ring>
   IdPgpKeyName        <name of the OpenPGP key in PgpSecretKeyFile>
   IdPgpKeyFingerprint <fingerprint of OpenPGP key in PgpSecretKeyFile>
   IdPgpKeyId          <id of the OpenPGP key in PgpSecretKeyFile>
   

4. Copy your public-key ring (pubring.gpg) to the ~/.ssh2 directory on Remote

   scp2 pubring.gpg user@remote_host:.ssh2
   

5. Create an authorization file in your ~/.ssh2 directory on Remote. Add the following lines to the authorization file:

   PgpPublicKeyFile   <filename of the user's public-key ring>
   PgpKeyName         <name of the OpenPGP key>
   PgpKeyFingerprint  <fingerprint the OpenPGP key>
   PgpKeyId           <id of the OpenPGP key>
   

6. Now you should be able to login to Remote from Local using Secure Shell. Try to login:

   Local>ssh Remote
   Passphrase for pgp key "user (comment) <user@Local>":
   

   After you have entered the passphrase of your PGP key, a Secure Shell connection will be established.

Optional Additional Configuration Settings

The following configuration steps are optional:

• It is possible to use different settings depending on which key is used in public-key authentication. Your authorization file could, for example, contain the following:

  Key master.pub
  Key maid.pub
  Options allow-from=".*\.trusted\.org"
  Key butler.pub
  Options deny-from=".*\.evilcrackers\.org",deny-from="phoney.org",no-pty
  

  When someone now logins using the master key, the connection is not limited in any way by the authorization file. However, if the maid key is used, only connections from certain hosts will be allowed. And if the butler key is used, connections are denied from certain hosts, and additionally the allocation of tty is prevented. Note: The options keyword is available only in SSH Secure Shell version 3.0 and later. In the previous versions, the only key-specific keyword is command. More information on options (and command) keywords is available in the ssh2 man pages.
• The per-user configuration directory can be changed by setting the UserConfigDirectory keyword in the sshd2_config file and on the client settings.