IBM Support

Cryptographic Services for Password Management in Navigator and Db2 Mirror



IBM i Cryptographic services are used for encryption key management in Navigator for i and Db2 Mirror GUI interfaces. Users can store both user passwords and the certificates used for secure (TLS) connections to end-point IBM i nodes, in an encrypted file. MasterKey 1 is being used to secure keys and must be loaded and set correctly.


The IBM Navigator for i GUI interface and the IBM Db2 Mirror GUI interface have a requirement for strong encryption. Users can store user profile passwords for authentication to IBM i endpoint nodes encrypted in a user preference resource file.*  For users that are connecting from the GUI interface to the IBM i endpoint nodes by using a secure connection (TLS encryption), the certificates are stored in the Web Truststore, and they are encrypted.  
To insure that the required data is stored in a safe and secure manner, Cryptographic Services are being leveraged.  Note:  MasterKey 1 must be set to use Cryptographic Services.
Navigator and Db2 Mirror GUI interfaces both use masterKey 1 to secure sensitive data
Cryptographic Services provides 8 MasterKeys that can be leveraged. The Web interfaces (Navigator and Db2 Mirror) are using only MasterKey 1.  If MasterKey 1 is set, it is used. If it is not set, the GUI prompts the user for a pass phrase in order to set the Key 1.
Note: Only an 'Administrator' a user with *ALLOBJ and *SECADM special authority can set the key.
An administrator can either use the GUI or CL commands to set MasterKey 1 within Cryptographic Services. 
    These files can be protected by Cryptographic services:
    1. Web Truststore for Db2 Mirror GUI, IBM Navigator for i and future applications in /QIBM/UserData/OS/WebTrustStore/WebTrustStore.  The key for the trust keystore needs to be generated.  That key is stored in a keystore secured by key 1.
    2. The file to store system information for a user. Note: only the passwords are encrypted and ONLY if the save-to-file authentication option is chosen by the user:
    • /qibm/userdata/os400/navigator/preferences/<encoded_username>/*.json
    • /qibm/userdata/qdb2mir/mrdb/gui/preferences/<encoded_username>/*.
    • The passwords are saved and encrypted only if users choose the save-to-file authentication method. For other authentication methods, there are no passwords saved in these files.  The key to encrypted passwords is generated for each user, and the key is stored in a keystore file secured by key 1.  
    Usage Notes
    If a masterKey is changed, there are two scenarios where the keys could be lost:
    1. If the current version is changed more than twice before translation; keys are lost in the keystore files.  For a single update, a translation can be done automatically to the keystore files.  
    2. If a user clears the masterKeys that are already used by the Navigator or Db2 Mirror GUI, the keys in the keystore files are lost.
    If the MasterKey is lost, the passwords saved in files and the certificates saved in the Web Truststore are not readable. When the MasterKey is lost, the user needs to re-create the passwords and certificates. 

    New panel in Connection Properties - Cryptographic Services
    Used to load and set masterKey 1
    Connection Properties - Cryptographic Services tab - Used to load and set master key 1

    Note: If MasterKey 1 is cleared or reset twice (without translating keystores encrypted by this key outside Navigator GUI), encrypted data for the password or web truststore is lost. It is lost because the configuration cannot be decrypted. MasterKey 1 might be used for other products and monitored by some exit programs, so the load and set operations might fail.  If issues occur, check masterKey exit points.
    The same truststore is shared between Db2 Mirror and Navigator for i.  They use the same masterKey.  Currently, only MasterKey 1 can be used for both.
    There are plans for the future for full support of cryptographic services within the Navigator for i.

    When masterKey is NOT loaded and set on the GUI system, a NAV_200001 warning is given.  Users are still allowed to both add new systems and access IBM i end-point nodes.  The user is required to enter the correct password to authenticate to the end-point node.  If a secure connection is being used, the user needs to accept the certificate (again) to establish the secure connection.  A warning is shown for the specific interface until an Administrator signs on and establishes or updates MasterKey 1. 
    Warning for cryptographic services master key 1 not set - This warning will continue to show the the specific interface until an Administrator has signed on and established or updated Master key 1.

    When a 'Administrator' tries to update any truststore or password-related functions, the masterKey 1 status is retrieved. If it is not loaded and set correctly, the following dialog box is shown. The user can provide a pass phrase in order to load and set masterKey 1.  Click "Close" button to not load and set key 1.
    Note: this dialog is only shown for an Administrator (user with *ALLOBJ and *SECADM special authority) 
    When a 'Administrator' tries to update any truststore or password-related functions, the master key 1 status is retrieved. If it is not loaded and set correctly, the following dialog box is shown

    If the  masterKey 1 is not set, any certificates that are added or accepted will be lost after users logout and re-login.  When the masterKey is not set, passwords are not saved even if authentication method three (save-to-file authentication) is selected. When the passwords and certificates are not saved, the user is asked to specify passwords and reaccept the certificates as required. 

    *Note:  This is an option.  Users can alternatively choose to always specify the user name and password where no password details are stored.

    [{"Type":"MASTER","Line of Business":{"code":"LOB57","label":"Power"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SWG60","label":"IBM i"},"ARM Category":[{"code":"a8m0z0000000CH1AAM","label":"IBM Navigator for i"}],"Platform":[{"code":"PF012","label":"IBM i"}],"Version":"7.3.0;7.4.0;and future releases"}]

    Document Information

    Modified date:
    06 June 2022