13.3. Managing System Passwords

As explained in Section 2.3.10, “Passwords and Watchdog (nuxwdog)”, Certificate System uses passwords bind to servers or to unlock tokens when the server starts.
The password.conf file stores system passwords in plain text. However, some administrators prefer to remove the password file entirely to allow nuxwdog to prompt for manual entry of each password initially and store for auto-restart in case of an unplanned shutdown.
When a Certificate System instance starts, the subsystem automatically checks for the password.conf file. If the file exists, then it uses those passwords to connect to other services, such as the internal LDAP database. If that file does not exist, then the watchdog daemon prompts for all of the passwords required by the PKI server to start.

Note

If the password.conf file is present, the subsystem assumes that all the required passwords are present and properly formatted in clear text. If any passwords are missing or wrongly formatted, then the system fails to start correctly.
The required passwords are listed in the cms.passwordlist parameter in the CS.cfg file:
cms.passwordlist=internaldb,replicationdb,CA LDAP Publishing
cms.password.ignore.publishing.failure=true

Note

The cms.password.ignore.publishing.failure parameter allows a CA subsystem to start up successfully even if it has a failed connection to one of its LDAP publishing directories.
For the CA, KRA, OCSP, and TKS subsystems, the default expected passwords are:
  • internal for the NSS database
  • internaldb for the internal LDAP database
  • replicationdb for the replication password
  • Any passwords to access external LDAP databases for publishing (CA only)

    Note

    If a publisher is configured after the password.conf file is removed, nothing is written to the password.conf file. Unless nuxwdog is configured, the server will not have access to the prompts for the new publishing password the next time that the instance restarts.
  • Any external hardware token passwords
For the TPS, this prompts for three passwords:
  • internal for the NSS database
  • tokendbpass for the internal LDAP database
  • Any external hardware token passwords
This section describes the two mechanisms provided for Certificate System to retrieve these passwords:
  • password.conf file (the default)
  • nuxwdog (watchdog)

13.3.1. Configuring the password.conf File

Note

This section is here for reference only. Correct and secure operation must involve using the nuxwdog watchdog. Please refer to Section 13.3.2, “Using the Certificate System Watchdog Service” to enable nuxwdog, as it is required for full compliance.
By default, passwords are stored in a plain text file, password.conf, in the subsystem conf/ directory. Therefore, it is possible to modify them simply through a text editor.
The list of passwords stored in this file includes the following:
  • The bind password used by the Certificate System instance to access and update the internal database.
  • The password to the HSM
  • The bind password used by the Certificate System instance to access the authentication directory, in case of CMC Shared Token.
  • The bind password used by the subsystem to access and update the LDAP publishing directory; this is required only if the Certificate System instance is configured for publishing certificates and CRLs to an LDAP-compliant directory.
  • the bind password used by the subsystem to access its replication database.
  • For a TPS instance, the bind password used to access and update the token database.
The password.conf file also contains the token passwords needed to open the private keys of the subsystem.
The name and location password file to use for the subsystem is configured in the CS.cfg file:
passwordFile=/var/lib/pki/instance_name/conf/password.conf
The internal password store and replication database have randomly-generated PINs which were set when the subsystem was installed and configured; the internal LDAP database password was defined by the administrator when the instance was configured.
The password entries in the password.conf file are in the following format:
name=password
For example:
internal=413691159497
In cases where an HSM token is required, use the following format:
hardware-name=password
For example:
hardware-NHSM6000=MyHSM$S8cret
Example content of a password.conf file:
internal=376577078151
internaldb=secret12
replicationdb=1535106826
hardware-NHSM6000=MyHSM$S8cret

13.3.2. Using the Certificate System Watchdog Service

In Certificate System, the watchdog service is used to start services which require passwords to access the security database in order to start. In case there is a requirement not to store the unencrypted passwords on the system, the watchdog service:
  • prompts for the relevant passwords during server startup and caches them.
  • uses cached passwords in case of a failure when the server is automatically restarted due to a crash.

13.3.2.1. Enabling the Watchdog Service

To enable the watchdog service:
  1. If you also want to use the Shared Secret feature on this host, enable the Shared Secret feature as described in Section 13.8.3, “Enabling the CMC Shared Secret Feature”.
  2. Backup the server.xml and password.conf files from the /var/lib/pki/instance_name/conf/ directory. For example:
    # cp -p /var/lib/pki/instance_name/conf/server.xml /root/
    # cp -p /var/lib/pki/instance_name/conf/password.conf /root/
  3. Stop and disable the Certificate System instance's service:
    # systemctl stop pki-tomcatd@instance_name.service
    # systemctl disable pki-tomcatd@instance_name.service
  4. If you use a Hardware Security Module (HSM), enable the watchdog service to prompt for the password of the hardware token:
    1. Display the name of the hardware token:
      # egrep "^hardware-" /var/lib/pki/instance_name/conf/password.conf
      hardware-HSM_token_name=password
      The highlighted string in the previous example is the hardware token name.
    2. Add the cms.tokenList parameter to the /var/lib/pki/instance_name/conf/ca/CS.cfg file and set it to the name of the hardware token. For example:
      cms.tokenList=HMS_token_name
  5. Enable the watchdog configuration for the instance:
    # pki-server instance-nuxwdog-enable instance_name
    Alternatively, enable the watchdog for all instances:
    # pki-server nuxwdog-enable
    For further details, see the pki-server-nuxwdog(8) man page.
  6. By default, nuxwdog starts the server as the user configured in the TOMCAT_USER variable in the /etc/sysconfig/pki-tomcat file. Optionally, to modify the user and group:
    1. Copy the watchdog systemd unit file of the instance to the /etc/systemd/system/ directory:
      # cp -p /usr/lib/systemd/system/instance_name-nuxwdog@.service /etc/systemd/system/

      Note

      Unit files in the /etc/systemd/system/ directory have a higher priority and are not replaced during updates.
    2. Add the following entries to the [Service] section in the /etc/pki/instance_name/nuxwdog.conf file:
      User new_user_name
    3. Reload the systemd configuration:
      # systemctl daemon-reload
  7. Enable the Certificate System service that uses the watchdog:
    # systemctl enable pki-tomcatd-nuxwdog@instance_name.service
  8. To start the Certificate System instance, run the following command and enter the prompted passwords:
    # systemctl start pki-tomcatd-nuxwdog@instance_name.service

13.3.2.2. Starting and Stopping Certificate System with the Watchdog Enabled

For information how to manage a Certificate System instance refer to Section 2.2.3, “Execution Management (systemctl)”.

13.3.2.3. Verifying That the Certificate System Watchdog Service is Enabled

To verify that the watchdog service is enabled:
  1. Verify that the pki-tomcatd-nuxwdog service is enabled:
    # systemctl is-enabled pki-tomcatd-nuxwdog@instance_name.service
    enabled
  2. Verify that the pki-tomcatd service is disabled:
    # systemctl is-disabled pki-tomcatd@instance_name.service
    disabled
  3. In the /etc/pki/instance_name/server.xml file:
    1. verify that the passwordFile parameter refers to the CS.cfg file. For example:
      passwordFile="/var/lib/pki/instance_name/ca/CS.cfg"
    2. verify that the passwordClass parameter is set to com.netscape.cms.tomcat.NuxwdogPasswordStore:
      passwordClass="com.netscape.cms.tomcat.NuxwdogPasswordStore"

13.3.2.4. Disabling the Watchdog Service

To disable the watchdog service:
  1. Stop and disable the Certificate System instance's service that uses the watchdog:
    # systemctl stop pki-tomcatd-nuxwdog@instance_name.service
    # systemctl disable pki-tomcatd-nuxwdog@instance_name.service
  2. Enable the regular service without watch dog for the instance:
    # pki-server instance-nuxwdog-disable instance_name
  3. Disable the watchdog configuration for the instance:
    # systemctl enable pki-tomcatd@instance_name.service
    For further details, see the pki-server-nuxwdog(8) man page.
  4. Restore the password.conf file to its original location. For example:
    # cp /root/password.conf.bak /var/lib/pki/instance_name/conf/password.conf
  5. Start the Certificate System instance:
    # systemctl start pki-tomcatd@instance_name.service