SFTP on IBMi

Setup IBMi to allow other systems to access its IFS folder using SFTP for secure file transfers

Introduction

SFTP (Secure File Transfer Protocol) enables secure file transfers between systems. This guide will walk you through configuring your IBMi system as an SFTP host, allowing other systems (such as your laptop) to securely request and transfer files.

We are going to setup our laptop as the SFTP client (which will request files) and IBMi as the SFTP host (which will store and provide the files). In this scenario, your laptop will initiate connections to download or upload files.

What makes SFTP secure?

SFTP enhances security by replacing traditional password-based authentication with public/private key pairs:

• Public Key: Stored on the IBMi host, it verifies the client's identity
• Private Key: Kept securely on the client (your laptop), it proves your identity to the server
• Encryption: All transferred data is encrypted during transmission

This approach is significantly more secure than regular FTP because:

• No passwords are transmitted over the network
• The private key never leaves your client machine
• Even if someone intercepts your connection, they cannot read the encrypted data

Setup Process Overview

To setup IBMi as the SFTP host, we need to:

• Generate Keys - Create the cryptographic key pair
• Share the Private Key to the Client - Securely transfer the private key to your client system
• Setup IBMi as Host - Configure IBMi to accept SFTP connections
  • Full access Method - Grants access to the entire IFS file system
  • Restricted Access Method - Limits access to specific directories only
• Test the Connection - Verify the setup works properly
• References - Additional resources

Generate Keys

• Login to your IBMi with a profile that has authority to create and manage user profiles. Preferably QSECOFR, as this profile has the necessary authority to create and modify system security settings.

• Enter the command below to enter the PASE Environment. PASE (Portable Application Solutions Environment) provides a Unix-like environment within IBMi that allows you to run Unix commands:
  • Call QP2TERM

• Start by creating the keypairs by entering the command below. This uses the ssh-keygen utility to generate an RSA key pair (a widely-used encryption algorithm for secure communications):
  • ssh-keygen -t RSA

During this process, you will be prompted with several questions. Each option affects how your keys will function:

Prompt	Response	Explanation
Enter file in which to save the key	hit enter	Accepts the default location (~/.ssh/id_rsa), which is the standard location for SSH keys in PASE. This makes them easier to find and use later.
Enter passphrase (empty for no passphrase)	hit enter	A passphrase adds an extra layer of security by requiring it each time the private key is used. For automation purposes, we're leaving it blank, but in high-security environments, you might want to add one.
Enter the same passphrase again	hit enter	Confirms the empty passphrase.

After completion, two files will be created:

• id_rsa - This is your private key and should be kept secure
• id_rsa.pub - This is your public key that will be shared with the IBMi host

Share the Private Key to the Client

• Use VS Code, ACS, or WinSCP to download the file id_rsa to your laptop. These tools provide secure file transfer capabilities to safely move your private key.

• Place the downloaded key in C:\Users\<username>\.ssh folder on your Windows laptop. This is the standard location where SSH clients look for private keys. If there is no .ssh folder in your laptop, then please create one!

• For better organization and clarity, you may want to rename the file to something meaningful. In this example, we'll rename it to goldenkey. This helps identify the key's purpose, especially if you manage multiple SSH keys.

• Important: Ensure the private key file permissions are set to be readable only by you. While Windows doesn't enforce this as strictly as Unix systems, it's a good security practice.

Setup IBMi as Host

When configuring SFTP access, you need to create a dedicated user profile for this purpose. This separation is a security best practice that isolates SFTP activities from your regular user accounts.

We'll be creating a separate IBMi user profile with limited security access specifically for SFTP file transfers. Anyone connecting to the IBMi using this profile will have the same level of access to the file system. Therefore, it's important to carefully consider what level of access to grant.

Full Access

Restricted Access

The newly created user profile will function like any other user profile in IBMi. By default, it will have access to all files in the IFS root folder, including critical configuration files and system directories. This approach is simpler to set up but introduces greater security risk. Only use this method in trusted environments where broad access is necessary. If you accept these security considerations, follow the Full Access Method.

The newly created user profile will have access only to specific directories that you explicitly allow. This method follows the principle of least privilege - granting only the minimum necessary access. This approach is strongly recommended if you're allowing third-party vendors or external users to access your IBMi's files. While it requires additional configuration steps, it significantly enhances security. If you prefer this more secure approach, follow the Restricted Access Method.

Full access Method

• Login to your IBMi with a profile that has authority to create and manage user profiles (preferably QSECOFR).

• Enter the below command to enter the PASE Environment. This provides access to Unix-style commands necessary for the following steps:
  • Call QP2TERM

• We will create a separate user profile dedicated to SFTP access. The INLMNU(*SIGNOFF) parameter ensures that if someone attempts to use this profile for interactive login, they will be immediately signed off. This is an important security measure that prevents the SFTP user from being used for regular system access:
  • system "CRTUSRPRF USRPRF(SFTPUSR1) INLMNU(*SIGNOFF)"

• Create a HOME directory on the IBMi to store the user's SSH-related files. This directory will serve as the landing point when SFTP users connect to the system:
  • mkdir /home/sftpusr1

• Create a .SSH directory within the user's home directory. This directory will store the authentication files needed for secure connections:
  • mkdir /home/sftpusr1/.ssh

• Set permissions on the user's home directory. The value 755 means:
  • Owner (sftpusr1) has read, write, and execute permissions (7)
  • Group has read and execute permissions (5)
  • Others have read and execute permissions (5)
  • This allows navigation into the directory while maintaining appropriate security:
  • chmod 755 /home/sftpusr1

• Set permissions on the user's .ssh directory. The value 700 means:
  • Owner has read, write, and execute permissions (7)
  • Group has no permissions (0)
  • Others have no permissions (0)
  • This restricts access to authentication files to only the owner:
  • chmod 700 /home/sftpusr1/.ssh

• Change ownership of the home directory to the SSH user. This ensures the SFTP user has proper access to its home directory:
  • chown sftpusr1 /home/sftpusr1

• Change ownership of the .SSH directory to the SSH user. This ensures the SFTP user has proper access to its authentication files:
  • chown sftpusr1 /home/sftpusr1/.ssh

• Update the Home directory setting in the user profile. This tells the IBMi operating system where the user's home directory is located:
  • system "CHGUSRPRF USRPRF(sftpusr1) HOMEDIR('/home/sftpusr1')"

• Rename the public key id_rsa.pub to authorized_keys and place it in the .ssh directory of the SFTP user. The "authorized_keys" file is a standard SSH convention - it contains a list of public keys that are allowed to authenticate to this account:
  • mv /home/$USER/.ssh/id_rsa.pub /home/sftpusr1/.ssh/authorized_keys

• Change ownership of the authorized_keys file to the SSH user so they can access it:
  • chown sftpusr1 /home/sftpusr1/.ssh/authorized_keys

• Set permissions on the authorized_keys file. The value 600 means:
  • Owner has read and write permissions (6)
  • Group has no permissions (0)
  • Others have no permissions (0)
  • This prevents other users from viewing or modifying the authorized keys:
  • chmod 600 /home/sftpusr1/.ssh/authorized_keys

• Create a dummy file for testing the file transfer. This will help verify that our SFTP connection works properly:
  • touch /home/sftpusr1/new.file

Restricted Access Method

This method uses a "chroot" environment to restrict the SFTP user to a specific directory tree, preventing access to other parts of the system. This is a more secure approach that follows the principle of least privilege.

• Login to your IBMi with a profile that has authority to create and manage user profiles.

• Enter command Call QP2TERM to enter the PASE Environment, which provides Unix-like command capabilities

• Create a separate user profile for SFTP access with interactive login disabled:
  • system "CRTUSRPRF USRPRF(SFTPUSR1) INLMNU(*SIGNOFF)"

• Create a separate Root folder for the user SFTPUSR1 using IBM's provided script. This script sets up a "chroot jail" - a restricted directory environment that prevents the user from accessing files outside their designated area. The location of the script varies by IBMi version:

  If you're running V7R2 & above:

  /QOpenSys/QIBM/ProdData/SC1/OpenSSH/sbin/chroot_setup_script.sh sftpusr1

  Note:

  If you're running on V6R1, the chroot_setup_script.sh will be present in: /QOpenSys/QIBM/ProdData/SC1/OpenSSH/openssh-3.8.1p1/

  If you're running V7R1, the chroot_setup_script.sh will be present in: /QOpenSys/QIBM/ProdData/SC1/OpenSSH/openssh-4.7p1

• Change the LOCALE parameter in the user profile to *NONE. This prevents potential issues with character set conversions in the chroot environment:
  • system "CHGUSRPRF USRPRF(SFTPUSR1) LOCALE(*NONE)"

• Start the SSH Daemon using a QSECOFR user profile. This is crucial for the chroot functionality to work properly:

  • /QOpenSys/usr/sbin/sshd

  Important Note: The SSH daemon must be started with the QSECOFR user profile to properly activate the chroot function. Starting the SSH daemon with a profile that merely has QSECOFR authority will not activate the chroot function. A user profile with a User ID (UID) of (0) is required. The QSECOFR user profile on IBMi is shipped with a UID of (0) by default.

• Check whether a HOME directory already exists for SFTPUSR1 in the chroot environment. The command below tests for the directory's existence and displays "dir_exists" if it's found:

  • test -d /QOpenSys/QIBM/UserData/SC1/OpenSSH/chroot/home/sftpusr1 && echo dir_exists

  • If you get the response "dir_exists", then proceed to the next step. Otherwise, create the directory with:

  • mkdir /QOpenSys/QIBM/UserData/SC1/OpenSSH/chroot/home/sftpusr1

• Create a .SSH directory within the user's home directory in the chroot environment:
  • mkdir /QOpenSys/QIBM/UserData/SC1/OpenSSH/chroot/home/sftpusr1/.ssh

• Set permissions on the user's home directory. The value 755 grants read and execute access to everyone but write access only to the owner:
  • chmod 755 /QOpenSys/QIBM/UserData/SC1/OpenSSH/chroot/home/sftpusr1

• Set permissions on the user's .ssh directory. The value 700 restricts all access to the owner only:
  • chmod 700 /QOpenSys/QIBM/UserData/SC1/OpenSSH/chroot/home/sftpusr1/.ssh

• Change ownership of the home directory to the SSH user:
  • chown sftpusr1 /QOpenSys/QIBM/UserData/SC1/OpenSSH/chroot/home/sftpusr1

• Change ownership of the .SSH directory to the SSH user:
  • chown sftpusr1 /QOpenSys/QIBM/UserData/SC1/OpenSSH/chroot/home/sftpusr1/.ssh

• Rename and move the public key to the authorized_keys file in the chroot environment:
  • mv /home/$USER/.ssh/id_rsa.pub /QOpenSys/QIBM/UserData/SC1/OpenSSH/chroot/home/sftpusr1/.ssh/authorized_keys

• Change ownership of the authorized_keys file to the SSH user:
  • chown SFTPUSR1 /QOpenSys/QIBM/UserData/SC1/OpenSSH/chroot/home/sftpusr1/.ssh/authorized_keys

• Set permissions on the authorized_keys file to restrict access to the owner only:
  • chmod 600 /QOpenSys/QIBM/UserData/SC1/OpenSSH/chroot/home/sftpusr1/.ssh/authorized_keys

• Create a dummy file for testing the transfer:
  • touch /QOpenSys/QIBM/UserData/SC1/OpenSSH/chroot/home/sftpusr1/new.file

That's it! We've successfully setup the IBMi as an SFTP host. Now we need to verify our configuration works properly by testing the connection.

Test the Connection

Now that the server is configured, we'll test the connection from a client machine (your laptop) to verify everything is working correctly.

• Go to the client machine (laptop) and open the terminal or command prompt.

• Enter the command below to initiate an SFTP connection. This command uses your private key to authenticate with the IBMi server:
  • sftp -i "C:\Users\RavisankarPandian\.ssh\goldenkey" sftpusr1@129.40.94.17
  • Important: Replace the path with your actual username and the location of your private key
  • Important: Replace the IP address (129.40.94.17) with your IBMi's actual IP address

• If the connection is successful, you'll see an sftp prompt. Now, let's change the current directory on your local machine to the Downloads folder. This determines where downloaded files will be saved:
  • lcd Downloads

• Let's download the test file we created earlier from the IBMi to your laptop:
  • get new.file
  • If successful, you'll see a confirmation message showing the file was transferred

• Let's also try uploading a file from your laptop to the IBMi. This tests two-way file transfers:
  • put nick.jpg
  • If successful, you'll see a confirmation message showing the file was transferred

• Once you've verified both upload and download functionality, you can close the connection:
  • bye

Successful completion of these steps confirms that your SFTP configuration is working properly. The IBMi is now set up to securely accept file transfers using public key authentication.

References

For further information and advanced usage, consult these resources:

1. Using Python to automate SFTP operations - Helpful for automating regular file transfers
2. Automate SFTP using expect - For non-interactive automation of SFTP
3. SSH Configuration - Official IBM documentation on SSH configuration
4. Example Batch SFTP Script - For scheduled or batch file transfers
5. Batch SFTP with password-based authentication - Alternative authentication method (less secure than key-based)