Configuring SSL for SAP Host Agent on IBM i

In the following procedure we assume that you are using the default naming for the server PSE. If you want to override the default .pse name, you can use the following value in the profile file of SAP Host Agent (host_profile):

ssl/server_pse= <Path to Server PSE>

You can find the host_profile file in $DIR_EXECUTABLE, where $DIR_EXECUTABLE the path to the directory where the executables saphostcontrol and saphostexec of SAP Host Agent are located: /usr/sap/hostctrl/exe

Prerequisites

You must be logged on as a user profile with special authorities *SECADM and *ALLOBJ, for example as user profile QSECOFR.

Procedure

Prepare the Personal Security Environment (PSE) for the server:
The server PSE contains the server certificate, which is presented to the client when establishing the SSL connection, and the names and public keys of the trusted certificates. Trusted certificates can be either certificates issued by a Certification Authority (CA) or individually trusted certificates.

Proceed as follows:
1. You must temporarily enable the login for user SAPADM. To change the user profile, enter the following command:
  CHGUSRPRF USRPRF(SAPADM) INLMNU(MAIN) LMTCPB(*NO)
2. Create a directory /usr/sap/hostctrl/exe/sec using the following command:
  CRTDIR DIR('/usr/sap/hostctrl/exe/sec') DTAAUT(*EXCLUDE) OBJAUT(*NONE)
  
  Note
  Alternatively, you can also use another directory, but then you must specify the location of the PSE file using the parameter ssl/server_pse as described above. In the following steps we always refer to the sec directory for the sake of simplicity.
  
  End of the note.
3. Change the owner and primary group of the PSE directory and set the appropriate authorities using the following command:
  QSYS/CHGOWN OBJ('/usr/sap/hostctrl/exe/sec') NEWOWN(SAPADM)
  
  QSYS/CHGPGP OBJ('/usr/sap/hostctrl/exe/sec') NEWPGP(R3GROUP) DTAAUT(*RWX)
4. Now log on as user SAPADM and execute the command CALL PGM(QP2TERM) before entering the commands of the following steps.
5. Set up the shared library search path (LIBPATH) and SECUDIR environment variables, and change to the exe directory of SAP Host Agent.
  The required commands are as follows:
  
  export LIBPATH=/usr/sap/hostctrl/exe
  
  export SECUDIR=/usr/sap/hostctrl/exe/sec
  
  cd /usr/sap/hostctrl/exe
  
  Recommendation
  Set up SECUDIR as an absolute path in order to avoid trouble with the sapgenpse tool.
  
  End of the recommendation.
6. Create the server PSE, the server certificate therein, and the Certificate Signing Request (CSR) using the following command:.
  ./sapgenpse gen_pse -p SAPSSLS.pse -x <PASSWORD> -r <PKCS#10 requestfile> <DISTINGUISHED NAME>
  
  This command creates the PSE file /usr/sap/hostctrl/exe/sec/SAPSSLS.pse (the name is fixed), which can be used to authenticate the host described by <DISTINGUISHED NAME> for incoming SSL connections. Access to the PSE file is protected with password <PASSWORD>.
  
  The CSR is written into the stream file <PKCS#10 requestfile>. You can ignore the warning sapgenpse WARNING: Environment variable "USER" not defined!
  
  Example
  ./sapgenpse gen_pse -p SAPSSLS.pse -x pass -r /tmp/myhost-csr.p10 "CN=myhost.wdf.sap.corp, O=SAP AG, C=DE"
  
  This command creates the PSE file /usr/sap/hostctrl/exe/sec/SAPSSLS.pse, which can be used to authenticate myhost.wdf.sap.corp for incoming SSL connections. Access to the PSE file is protected with the password pass. The CSR is written into the stream file /tmp/myhost-csr.p10.
  
  End of the example.
7. Grant SAP Host Agent access to the server PSE using the following command:
  ./sapgenpse seclogin -p SAPSSLS.pse -x <PASSWORD> -O sapadm
  
  Example
  ./sapgenpse seclogin -p SAPSSLS.pse -x pass -O sapadm
  
  End of the example.
8. Get the certificate as follows:
  1. Transfer the stream file containing the CSR (certificate signing request) to a PC and send it to the Certification Authority (CA) you are using.
  2. The CA replies to the PKCS#10 requestfile with a “CA-response-file” which contains the signed certificate — between the ---- BEGIN CERTIFICATE ---- and ---- END CERTIFICATE ---- lines. Paste everything between these two lines — including the lines — into a text file. Transfer this text file to a stream file on your IBM i.
    
    Example
    The text file could be named myhost.p7b and transferred to the stream file /tmp/myhost.p7b. We use this file name in the following examples.
    
    End of the example.
9. Import the signed certificate into the server PSE using the following command:
  ./sapgenpse import_own_cert -p SAPSSLS.pse -x <PASSWORD> -c <CA-response-file>
  
  Example
  ./sapgenpse import_own_cert -p SAPSSLS.pse -x pass -c /tmp/myhost.p7b
  
  End of the example.
10. Verify the server certificate chain using the following command:
  ./sapgenpse get_my_name -p SAPSSLS.pse -x <PASSWORD> -v
  
  Example
  ./sapgenpse get_my_name -p SAPSSLS.pse -x pass -v
  
  End of the example.
11. To reset the changes to user profile SAPADM that you have made in step 1.a), leave program QP2TERM with function key F3 and enter the following command: CHGUSRPRF USRPRF(SAPADM) INLMNU(*SIGNOFF) LMTCPB(*YES)
12. Log on as a user profile with special authorities *SECADM and *ALLOBJ, for example as user profile QSECOFR and execute the command CALL PGM(QP2TERM) before entering the command following which restarts SAP Host Agent:
  /usr/sap/hostctrl/exe/saphostexec -restart
Prepare the client PSE.
The client PSE contains the client certificate, which is sent to SAP Host Agent when the SSL connection is established, and the names and public keys of the trusted certificates from CA.

The configuration steps are client-specific, that is why we only describe them in a generic way. Follow the instructions in the specific client documentation.

Examples for possible clients are the SAP Management Console (SAP MC), the Diagnostics Agent in SAP Solution Manager, or the SAP NetWeaver Landscape Virtualization Management (LVM) software (formerly known as Adaptive Computing Controller (ACC)).

Result

Recommendation

If you successfully applied the procedure described above, SAP Host Agent also serves port 1129 for SSL communication.

End of the recommendation.