IBM Support

Configuring the IBM i SSH, SFTP, and SCP Clients to Use Public-Key Authentication

Technote (troubleshooting)


Problem(Abstract)

This document provides the steps necessary to configure Public-key authentication on the IBM i SSH clients to gain access to SSH servers.

Resolving the problem

Public-key authentication allows the IBM i SSH, SFTP, and SCP clients to gain access to remote hosts without having to provide a password. The SFTP and SCP clients on the IBM i require Public-key authentication to gain access to SSH servers. Password authentication is not allowed with these two clients. The IBM i SSH client can use either Public-key authentication or Password authentication to gain access to SSH servers.

Prerequisites

5733SC1 IBM Portable Utilities for i5/OS *BASE & Option 1

57XXSS1 Option 33 (Portable Application Solutions Environment)

Assumptions

This document assumes the following:

  • The IBMi is running at V5R4 or higher of the operating system.
  • A user profile consisting of 8 characters or less to store the SSH related objects needed to communicate with remote SSH servers.
  • The remote host has been configured to accept and process inbound SSH connections.
Important Note: The user someuser provided in the examples below is not the name of an actual IBM i profile. The commands that contain someuser as part of the syntax should be replaced with the profile name that has been created to make outbound SSH connections.

Do the following to configure Public-key authentication on the IBMi:
1. Sign on a system that is running V5R4 or higher with the user profile designated for SSH-related functions.
2. On the operating system command line, run the CALL QP2TERM command to enter the PASE environment.
3. From within the PASE or Qshell environment, type the following commands:

Note: Licensed Program Product 57XXSS1 Option 30 (Qshell) is required to run the commands below in the Qshell environment.

a. Create a HOME directory on the IBMi to store the user's SSH-related objects.
    mkdir /home/someuser

b. Set permissions on the user's home directory.
    chmod 755 /home/someuser

c. Create a DSA or RSA key pair that has no passphrase associated with it. Use the commands below to create either a DSA or RSA key pair.
    ssh-keygen -t dsa -N ""

ssh-keygen -t rsa -N ""

Note: During key generation, SSH will check to see if there is a .ssh folder underneath the user's home directory. If one does not exist, the folder will be created in the user's home directory and the public/private key pair will be stored in it. The public key will have a .pub extension; for example, id_dsa.pub or id_rsa.pub. The private key will be the one without the extension; for example, id_dsa or id_rsa.

Caution: The private keys generated by the SSH-keygen utility should be kept private. It is very important to protect the private key from unauthorized individuals. Anyone that can gain access to a user's private key has the potential to signon to the SSH server were the corresponding public key has been copied. Use IFS authorities to limit access to the private key to only the appropriate SSH user.

d. Close the PASE or Qshell terminal session. Use the F3 key to exit the terminal session.
4. Change the home directory parameter in the user's profile to point to the IFS path of the home directory created in Step 3a.

CHGUSRPRF USRPRF(someuser) HOMEDIR('/home/someuser')
5. Sign off and sign back on up with the SSH profile to allow the changes made to the HOMEDIR parameter to take effect. Note: Everytime a user enters the PASE or Qshell environment, they will be placed into the IFS path specified in the HOMEDIR parameter in the user's profile.
6. Send the public key that was generated in Step 3c to the SSH server administrator. The two most common methods for moving the public key to a PC are listed below:

a. Drill down to the IFS path /home/someuser/.ssh in iSeries Navigator, and use the drag and drop method to copy the public key into a folder on the PC.

b. FTP the public key in binary mode into a folder on the PC.

Once the public key has been moved to the PC, you can send it to the SSH server administrator as an e-mail attachment.
7. Once the SSH server administrator has placed the public key into the appropriate location on the remote side, you can test the connection to see if Public-key authentication works.

a. On the operating system command line, run the CALL QP2TERM command to enter the PASE environment.

b. From within the PASE environment, execute the follow command:
    ssh -T serveruid@somehost

Note: Replace serveruid with the name of the user profile that the SSH server administrator provided you with to gain access to the remote host. Replace somehost with either the IP address or host name of the remote system that you want to establish a connection with.

If this is the first time you have connected to the remote host using SSH, you will receive a message similar to the one below:

The authenticity of host 'somehost (x.x.x.x)' can't be established.
    . key fingerprint is RSA.                                              
    Are you sure you want to continue connecting (yes/no)?    

Type yes and press the Enter key to add the server's public host key into the known_hosts file in the .ssh folder in the user's home directory. If Public-key authentication is successful, you will not be prompted for a password.

If the remote host provides shell access, use the hostname command to verify that your truly logged into the SSH server. The hostname command will return the name of the system on which you are actually logged into.

c. Close the SSH connection:

Type exit and press the Enter key to disconnect the SSH connection.
8. Once Public-key authentication has been successfully configured, the SFTP and SCP clients can be used to transfer files securely between the IBMi and the remote SSH server. Listed below is the syntax that can be used to initiate SFTP connections to remote systems:

sftp serveruid@somehost

Note: Replace serveruid with the name of the user profile that the SSH server administrator provided you with to gain access to the remote host. Replace somehost with either the IP address or host name of the remote system that you want to establish a connection with.


Cross reference information
Segment Product Component Platform Version Edition
Operating System IBM i 7.2
Operating System IBM i 7.1
Operating System IBM i 6.1

Historical Number

538212497

Document information

More support for: IBM i
Communications-TCP

Software version: 5.4.0, 5.4.5, 6.1.0, 6.1.1, 7.1, 7.1.0, 7.2

Operating system(s): IBM i

Reference #: N1012710

Modified date: 07 August 2013