TCP/IP for z/VM 530 SSL Server
Certificate With Key Export Support

The instructions that follow describe how to:

• upgrade the IBM GSKit and SSL server RPMs within the SSL server Linux guest
• export a server certificate with its private key, and import it into a z/VM 540 SSL server key database.

Note:
These instructions pertain to only the z/VM 530 Linux-based SSL server implementation, after having applied the PTF for APAR PK75661.

The z/VM RPM files for various Linux distributions (supplied via the PK75661 PTF), as well as appropriate Linux file names for these files, are listed here:

1. Establish (or, re-establish) network connectivity for the 530 SSL server guest from which certificates are to be exported.

   The steps necessary to do this are described in the applicable "install" file provided with the SSL RPM package that is in use (for example, as described by the (SSL Server) Managing Network Connectivity page).

   Once this process is complete and the subject SSL server has been initialized to an inactive (but network-connected) state, it will be possible to use ftp to transfer the APAR-supplied RPM files to the selected destination.

2. Login as the root user on the selected Linux system, using either the Linux guest 3270 console or a VT100 telnet connection.

3. Use the cd command to change the current directory to that where the existing RPM files are being maintained. For example:

     cd /root
   

4. Backup (copy) the existing SSL server database files. For this example, the text ".pre75661" is used to aid in identifying the backed-up files, should these be required at a later time.

     cp -p  /opt/vmssl/certdb/Database.kdb  Database.kdb.pre75661
     cp -p  /opt/vmssl/certdb/Database.sth  Database.sth.pre75661
     cp -p  /opt/vmssl/certdb/Database.rdb  Database.rdb.pre75661
     cp -p  /opt/vmssl/certdb/Database.crl  Database.crl.pre75661
   

5. Initiate an FTP session to the z/VM host where the needed RPMBIN package files reside:

     ftp vm_host_ip_address
   

6. Login using an appropriate user ID (dependent upon how TCP/IP for z/VM 530 has been installed) and then change the working directory to the appropriate resource. For more information about which user ID to use, check the Configuration Information and Requirements for z/VM 530 page.
   1. For an installation that uses TCP/IP service minidisks:

        user sslserv
        pass pass_word
        cd sslserv.493
      

   2. For an installation in that uses TCP/IP service SFS directories:

        user 5vmtcp30
        pass pass_word
        cd vmsys:5vmtcp30.tcpip.binary
      

7. Establish Binary transfer mode and retrieve the appropriate RPMBIN files:

     bin
     get VM_IBMgskit_name.rpmbin Linux_IBMgskit_name.rpm
     get VM_SSLpackage_name.rpmbin Linux_SSLpackage_name.rpm
   

8. End the FTP session, after the files have been successfully transferred.

After having transferred the necessary RPM package files, you can uninstall the current RPM files, and install each new package using the Linux rpm command, as described in the next section.

1. Verify that the transferred RPM files are installable packages, by issuing the rpm -i commands that follow. Each command will display general information about the specified package:

     rpm -qpi Linux_IBMgskit_name.rpm
     rpm -qpi Linux_SSLpackage_name.rpm
   

   Assuming each command displayed the proper information, continue with the removal of the existing RPM package.

2. Uninstall the currently installed SSL server and IBM GSKit RPM packages.

   Note:
   The SSL server package must be uninstalled before the IBM GSKit package.

   To uninstall the SSL server package:

   1. Confirm the name of the installed SSL server RPM file. Issue the command:

        rpm -qa | grep vmssl
      

      A result similar to the following result should be displayed:

        vmssld-2.6.9-2.2
      

   2. Uninstall the SSL server RPM, using the full, installed name as just determined, via the rpm -e command:

        rpm -e vmssld-2.6.9-2.2
      

   To uninstall the IBM GSKit package:

   1. Confirm the name of the installed IBM GSKit RPM file. Issue the command:

        rpm -q gsk7bas64-7.0-3.13.s390x
      

      A result similar to the following result should be displayed:

        gsk7bas64-7.0-3.13
      

   2. Uninstall the IBM GSKit RPM, using the full, installed name as just determined, via the rpm -e command:

        rpm -e gsk7bas64-7.0-3.13
      

3. Install the new IBM GSKit RPM and SSL server packages.

   Note:
   The IBM GSKit package must be installed before the SSL server package.

     rpm -ivh Linux_IBMgskit_name.rpm
     rpm -ivh Linux_SSLpackage_name.rpm
   

4. Restore the SSL server database files that were saved by the rpm command, as part of the uninstall of the prior-level SSL server RPM:

     cp -p  /opt/vmssl/certdb/Database.kdb.rpmsave  /opt/vmssl/certdb/Database.kdb
     cp -p  /opt/vmssl/certdb/Database.sth.rpmsave  /opt/vmssl/certdb/Database.sth
     cp -p  /opt/vmssl/certdb/Database.rdb.rpmsave  /opt/vmssl/certdb/Database.rdb
     cp -p  /opt/vmssl/certdb/Database.crl.rpmsave  /opt/vmssl/certdb/Database.crl
   

   Note:
   If the PK75661-level is installed more than once, or problems were encountered during the install of this RPM, restore the various database files from those that were manually backed up:

     cp -p  Database.kdb.pre75661  /opt/vmssl/certdb/Database.kdb
     cp -p  Database.sth.pre75661  /opt/vmssl/certdb/Database.sth
     cp -p  Database.rdb.pre75661  /opt/vmssl/certdb/Database.rdb
     cp -p  Database.crl.pre75661  /opt/vmssl/certdb/Database.crl
   

With the updated IBM GSKit and SSL server RPM files now in place, the target Linux guest then can be (re)configured to provide secure connection support and accommodate SSLADMIN command processing. To do this, you must deactivate Linux networking support (for example, as described by the (SSL Server) Managing Network Connectivity page), which at the same time activates automatic startup of the vmssl daemon.

• To export a certificate with its private key, you will need to provide a password of your choosing when the SSLADMIN EXPORT command is used.

• Ensure that appropriate measures are used to protect this password, and that it is not inadvertently retained (such as in a console log file). In addition, it is advised that no SSL server or SSLADMIN command tracing be employed when these export steps are performed, as the certificate password can appear within the data produced by these trace mechanisms.

1. Log on as TCPMAINT.

2. Ensure no tracing is active within the SSL server.

     ssladmin notrace
   

3. Ensure console spooling is not active for this user ID's virtual machine.

     cp spool cons close stop
   

4. Issue the "EXPORT CERTIFICATE WITHKEY" command for the certificate that is to be extracted from the database. For example, to export the certificate CERTWKEY, use the command:

     ssladmin export certwkey a certificate CERTWKEY withkey My-Cert Pass Word
   

   A response similar to the following should be produced:

     DTCSSL2404I Certificate saved in file CERTWKEY P12 A
     Ready;
   

   Notes:
   • The password you provide is case sensitive, and can be comprised of multiple tokens (with intervening blanks being significant). Leading and trailing blanks are not significant -- these are removed from the provided value prior to use.

   • Expired certificates with keys can be exported. However, it might not be possible to import such certificates into a different host key database.

5. Repeat the "EXPORT CERTIFICATE WITHKEY" command as needed, to export additional certificates with private keys. At your discretion, use the same or a different password for each exported certificate.

6. Send or transfer the P12 file(s) to the user ID that has been designated for management of the z/VM 540 SSL server key database (for example, GSKADMIN).

7. Log on the aforementioned key database management user ID.

8. Store the P12 file in an appropriate Byte File System (BFS) directory (for example, /etc/gskadm):

     openvm putbfs certwkey p12 a /etc/gskadm/certwkey.p12 (bfsline none
   

9. Invoke the gskkyman utility, and select the following options:
   • Database Menu

     2. Open a Database.
     <Supply the appropriate database name and its password>

   • Key Management Menu

     8. Import a certificate with key.

     Enter import file name (press ENTER to return to menu):
     /etc/gskadm/certwkey.p12 <enter>

     Enter import file password (press ENTER to return to menu):
     MyPassWord <enter>

     Enter label (press ENTER to return to menu):
     CERTWKEY <enter>

     Notes:

     • Ensure the label you specify is an appropriate TLS label (at most eight characters and all upper case).
     • Repeat the import process as needed, to import additional certificates with keys.
10. The selected certificate(s) now should be stored in the certificate database. Update the appropriate application configuration files (such as PROFILE TCPIP or SRVRFTP CONFIG) to use the new TLSLABEL value.

11. Start (or restart) the appropriate servers, so your changes can become effective. Alternately, use appropriate commands (such as SSLADMIN REFRESH and OBEYFILE) to effect dynamic changes to servers that are running and must remain so.

12. Log off the TCPMAINT and key database management user IDs.

• Upon the completion of these procedures, the certificate-with-key password no longer should be required. However, if you elect to maintain this password in some manner, use appropriate measures to ensure it is adequately protected.

• Be certain that any console or other files that contain your certificate-with-key password(s) are properly discarded or erased.