Configuring the IBM i ssh, sftp, and scp clients to use public-key authentication

Troubleshooting

Problem

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

Symptom

Cause

Environment

Diagnosing The Problem

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 IBM i PASE environment has a limitation for 8 characters or less.
There is an eight-character limitation on the user profiles that can access the IBM i through SSHD.
The eight-character limitation is also placed on any group profile that the user might be a member of.
If any of the other members in a group profile have more than eight characters in their user name,
access to the system will be denied. In order to get around the eight-character limitation, you
can either create system wide environment variable.
Unless you add:
ADDENVVAR ENVVAR(PASE_USRGRP_LIMITED) VALUE('N') LEVEL(*SYS)
The remote host is configured to accept and process inbound ssh connections.

Important Note: The user 'someuser' provided in the following examples 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 IBM i:

Sign onto the IBM i with a user profile that has sufficient authority to create a Batch SSH, SFTP, or SCP user profile:

CRTUSRPRF USRPRF(someuser) HOMEDIR('/home/someuser')

Create a home directory for the Batch SSH, SFTP, or SCP user profile:

MKDIR DIR('/home/someuser')

Set the owner of the Batch SSH, SFTP, or SCP user's home directory to the Batch SSH, SFTP, or SCP user profile:

CHGOWN OBJ('/home/someuser') NEWOWN(SOMEUSER)

4. Sign onto a new PC5250 session as the Batch SSH, SFTP, or SCP user profile.

5. On the IBM i command line, run the CALL QP2TERM command to enter the PASE environment.

From within the PASE or Qshell environment, type the following commands:

Note: Licensed program product 5770SS1 Option 30 (Qshell) is required to run the given commands in the Qshell environment.

a. Set permissions on the Batch SSH, SFTP, or SCP user's home directory.

```
chmod 755 /home/someuser
```

b. Create a rsa, ecdsa or ed25519 key pair that has no passphrase associated with it. Use the provided commands to create a rsa, ecdsa or ed25519 key pair:

```
ssh-keygen -t rsa -N ""
```

```
ssh-keygen -t ecdsa -N ""
```
```
ssh-keygen -t ed25519 -N ""
```

Note: During key generation, OpenSSH checks to see if there is a .ssh folder underneath the Batch SSH, SFTP, or SCP user's home directory. If one does not exist, the folder will be created in the Batch SSH, SFTP, or SCP 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_ed25519.pub or id_ecdsa.pub. The private key will be the one without the extension; for example, id_ed25519 or id_ecdsa.

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 sign on to the SSH server where the corresponding public key has been copied. Use IFS authorities to limit access to the private key to only the appropriate OpenSSH user.

c. Close the PASE or Qshell terminal session. Use the F3 key to exit the terminal session.

Send the public key that was generated in Step 6b 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 IBM i Navigator, and right-click and select "Download" to save the file to your PC.

b. FTP the public key using 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 email attachment.

NOTE: Some SSH servers require the key to be in SecSH or Tectia format. (That is often the case if the SSH Server is running in Microsoft Windows) If that is the case, and the SSH server administrator is unable to convert the key to the correct format themselves, you can follow technote https://www.ibm.com/support/pages/generating-openssh-public-key-and-converting-it-tectia-or-secsh-format, in particular from Step 5.
For example, to convert the id_rsa.pub key generated in step 6b to SecSH or Tectia format, you would run the following commands from within the users .ssh directory containing the keypair and then send the converted public key

ssh-keygen -e -f id_rsa.pub > id_rsa_win.pub
chmod 644 id_rsa_win.pub

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.      
ECDSA key fingerprint is SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

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 you are truly logged in to the SSH server. The hostname command will return the name of the system on which you are actually logged in to.

c. Close the SSH connection:

Type exit and press the Enter key to disconnect the SSH connection.

9. Once Public-key authentication has been successfully configured, the OPenSSH clients (ssh, sftp, or scp) can login to a remote SSH server without using a password. 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.

[{"Type":"MASTER","Line of Business":{"code":"LOB68","label":"Power HW"},"Business Unit":{"code":"BU070","label":"IBM Infrastructure"},"Product":{"code":"SWG60","label":"IBM i"},"ARM Category":[{"code":"a8m0z0000000CKoAAM","label":"Communications-\u003ESFTP and SSH or Secure Shell"}],"ARM Case Number":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"All Versions"}]

Historical Number

538212497

Product Synonym

OpenSSH; 5733SC1

Was this topic helpful?

Document Information

Modified date:
07 November 2025

UID

nas8N1012710

Tips