11.3. Managing System Passwords

The Certificate System stores passwords used to bind to servers or to unlock tokens when the server starts in a plain text file, password.conf.
Passwords for the internal database and other database-related passwords for optional features are stored in a plain text file, password.conf, in the subsystem conf/ directory. The passwords stored within it are used to bind to the various Certificate System services. Since the password.conf file is in clear text, 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 bind password used by the Certificate System instance to access and remove PINs from the authentication directory, if the Certificate System is configured to remove PINs from the authentication directory.
  • The bind password used by the subsystem to access and update the LDAP directory; this is required only if the Certificate System instance is configured for publishing certificates and CRLs to an LDAP-compliant directory.
  • 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.

11.3.1. Configuring the password.conf File

The name and location password file to use for the subsystem is configured in the CS.cfg file:
passwordFile=/var/lib/instance_name/conf/password.conf
By default, the passwords to access the instance's internal password store (internal, also called its NSS certificate database), its internal LDAP directory (internaldb), and its replication database. The internal password store and replication database have randomly-generated PINs which were set when the subsystem was configured; the internal LDAP database password was defined by the administrator when the instance was configured.
internal=376577078151
internaldb=secret12
replicationdb=1535106826
The password.conf file stores system passwords in plaintext, and some administrators prefer to enter system passwords manually and to remove the password file entirely.
Each subsystem is started by the nuxwdog daemon. 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, like the internal LDAP database. If that file does not exist, then the watchdog daemon prompts for all of the passwords required by the subsystem.

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 prompts for that password.
The passwords that are required 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

TIP

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, DRM, 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. The server simply 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

11.3.2. Requiring System Password Prompts

The password.conf file stores system passwords in plaintext, and some administrators prefer to enter system passwords manually and to remove the password file entirely.
Each subsystem is started by the nuxwdog daemon. 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, like the internal LDAP database. If that file does not exist, then the watchdog daemon prompts for all of the passwords required by the subsystem.

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 will not start.
The passwords that are required 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

TIP

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, DRM, OCSP, and TKS subsystems, the 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. The server simply 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
All of the passwords which will be prompted for when the subsystem instance starts are listed in the cms.passwordlist in the CS.cfg file for the instance.

11.3.2.1. Configuring New Instances to Prompt for Passwords

To configure subsystem password prompts for a new CA, DRM, OCSP, or TKS instance, simply remove the password.conf file in the /var/lib/instance_name/conf directory.
For the TPS:
  1. Remove the password.conf file.
  2. Edit the nss.conf file to change the NSSPassPhraseDialog from the password file to builtin.
     ... original ...
    NSSPassPhraseDialog  defer:/var/lib/pki-tps/conf/password.conf
    
     ... updates ...
    # commenting out this line to enable password prompts
    # NSSPassPhraseDialog  defer:/var/lib/pki-tps/conf/password.conf
    
    # adding this line to enable password prompts
    NSSPassPhraseDialog  builtin

11.3.2.2. Configuring Existing CA, DRM, TKS, and OCSP Instances to Prompt for Passwords

Existing subsystem instances can be configured to prompt for passwords rather than using password.conf. This requires a few additional steps to set up.
  1. Make sure all of the Certificate System packages have been installed and updated.
  2. Stop the instance.
    service instance_name stop
  3. Back up the instance. For example:
    cp -R /var/lib/pki-ca-old /var/lib/pki-ca-old.bkup
  4. Add the cms.passwordlist parameter to the instance's CS.cfg file.
    vim /var/lib/instance_name/conf/CS.cfg
    
    cms.passwordlist=internaldb,replicationdb
    If publishing has been enabled, then make sure the LDAP publishing password is listed. For example:
    cms.passwordlist=internaldb,replicationdb,CA LDAP Publishing
    cms.password.ignore.publishing.failure=true

    TIP

    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.
  5. Create a new dtomcat5 file for the instance.
    1. Copy the current file in /usr/share/pki/type/conf. For example:
      /usr/share/pki/ca/conf/dtomcat5 /tmp/dtomcat5-pki-old
    2. Edit the copied dtomcat5-name file to supply the subsystem information. For example:
      sed -i 's/\[PKI_SUBSYSTEM_TYPE\]/ca/g' /tmp/dtomcat5-pki-old
      sed -i 's/\[PKI_INSTANCE_PATH\]/\/var\/lib\/pki-old/g' /tmp/dtomcat5-pki-old
      sed -i 's/\[PKI_INSTANCE_ID\]/pki-old/g' /tmp/dtomcat5-pki-old
    3. Copy the file into the /usr/bin directory.
      cp /tmp/dtomcat5-pki-old /usr/bin
    4. Set the proper file owner and permissions for the file.
      chown pkiuser: /usr/bin/dtomcat5-pki-old
      chmod 770 /usr/bin/dtomcat5-pki-old
    5. Remove the temporary file.
      rm -rf /tmp/dtomcat5-pki-old
  6. Create a new HTTP init.d file for the instance.
    1. Copy the current httpd file in /usr/share/pki/type/etc/init.d. For example:
      cp /usr/share/pki/ca/etc/init.d/httpd /tmp/pki-ca-old
    2. Edit the copied httpd (such as /tmp/pki-ca-old) to supply the subsystem information. For example:
      sed -i 's/\[PKI_SUBSYSTEM_TYPE\]/ca/g' /tmp/pki-ca-old
      sed -i 's/\[PKI_INSTANCE_PATH\]/\/var\/lib\/pki-ca-old/g' /tmp/pki-ca-old
      sed -i 's/\[PKI_INSTANCE_ID\]/pki-old/g' /tmp/pki-ca-old
      sed -i 's/\[PKI_FLAVOR\]/pki/g' /tmp/pki-ca-old
      sed -i 's/\[PKI_USER\]/pkiuser/g' /tmp/pki-ca-old
      sed -i 's/\[PKI_GROUP\]/pkiuser/g' /tmp/pki-ca-old
      sed -i 's/\[PKI_SERVER_XML_CONF\]/\/var\/lib\/pki-ca-old\/conf\/server.xml/g' /tmp/pki-ca-old
    3. Copy the file into the /etc/init.d/ directory.
      cp /tmp/pki-ca-old /etc/init.d
    4. Set the proper file owner and permissions for the file.
      chown pkiuser: /etc/init.d/pki-ca-old
      chmod 770 /etc/init.d/pki-ca-old
    5. Remove the temporary file.
      crm -rf /tmp/pki-ca-old
  7. Edit the server.xml file. For each configured connector, add the configFile attribute:
    configFile="/var/lib/instance_name/conf/CS.cfg"
    The CA, DRM, TKS, and OCSP subsystems have three connectors each. A quick way to edit the file is to add the configFile attribute after every passwordFile attribute.
  8. Note the contents of the password.conf file, and then delete it.
    rm -rf /var/lib/instance_name/conf/password.conf

11.3.2.3. Configuring Existing TPS Instances to Prompt for Passwords

IMPORTANT

If the TPS is configured to prompt for passwords and the incorrect password is given, then the TPS still starts, unlike the other subsystems which will prompt again for the password. This means that the incorrect password error is not caught and communicated to the administrator.
If the incorrect password is given to the prompt for the token database, then all token operations will fail. However, the TPS will start correctly and will appear to run correctly; the problem exhibits in token operations.
If TPS commands or operations are failing inexplicably, then try restarting the TPS and re-entering the token database password.
  1. Make sure all of the Certificate System packages have been installed and updated.
  2. Stop the instance. For example:
    service pki-tps stop
  3. Back up the instance. For example:
    cp -R /var/lib/pki-tps-old /var/lib/pki-tps-old.bkup
  4. Update the perl.conf file.
    1. Copy the template perl.conf file.
      cp /usr/share/pki/tps/conf/perl.conf /tmp/perl.conf
    2. Edit the temporary perl.conf file to point to the appropriate Apache instance.
      sed -i 's/\[FORTITUDE_LIB_DIR\]/\/etc\/httpd/g' /tmp/perl.conf
      sed -i 's/\[FORTITUDE_APACHE\]/Apache2/g' /tmp/perl.conf
      sed -i 's/\[SERVER_ROOT\]/\/var\/lib\/pki-tps-old/g' /tmp/perl.conf
    3. Copy the temporary file into the TPS's conf/ directory.
      cp /tmp/perl.conf /var/lib/pki-tps-old/conf
    4. Set the proper file owner and permissions for the file.
      chown pkiuser: /var/lib/pki-tps-old/conf
      chmod 660 /var/lib/pki-tps-old/conf
    5. Remove the temporary file.
      rm /tmp/perl.conf
    6. Edit the nss.conf file to change the NSSPassPhraseDialog from the password file to builtin.
       ... original ...
      NSSPassPhraseDialog  defer:/var/lib/pki-tps/conf/password.conf
      
       ... updates ...
      # commenting out this line to enable password prompts
      # NSSPassPhraseDialog  defer:/var/lib/pki-tps/conf/password.conf
      
      # adding this line to enable password prompts
      NSSPassPhraseDialog  builtin
  5. Replace the security officer CGI scripts. There are different procedures to use, depending on whether the scripts have been customized.
    If the CGI scripts have not been customized, then do the following:
    1. Create a temporary directory and copy the CGI scripts into it.
      mkdir /tmp/sow
      cp /usr/share/pki/tps/cgi-bin/sow/*.cgi /tmp/sow
    2. Create a temporary directory and copy the CGI scripts into it.
    3. Edit the CGI files, using the appropriate server root for the TPS instance. For example:
      pushd /tmp/sow
      for i in `ls *.cgi`; do
      sed -i 's/\[SERVER_ROOT\]/\/var\/lib\/pki-tps-old/g' $i
      done
      cp -f *.cgi /var/lib/pki-tps-old/cgi-bin/sow
      popd
    4. Remove the temporary directory.
      rm -f /tmp/sow
    5. Set the proper file owner and permissions for the files.
      chown pkiuser: /var/lib/pki-tps-old/cgi-bin/sow/*.cgi
      chmod 755 /var/lib/pki-tps-old/cgi-bin/sow/*.cgi
  6. If the security officer scripts have been customized, then the files need to be updated so that they properly run under mod_perl::PerlRun instead of mod_cgi.
    The primary change is to replace any relative file paths with full paths. For example, replace this line:
    require "./cfg.pl"
    With:
    require "/var/lib/pki-tps/cgi-bin/sow/cfg.pl"
    Other changes may be needed to eliminate warnings in the error_log.
  7. Create a new HTTP init.d file for the instance. THe easiest way to do this is to create a temporary TPS instance, copy its init.d file, and then edit it to point to the original instance.
    1. Run pkicreate to create a TPS instance.
    2. Copy the new instance's init.d file.
      cp /etc/init.d/pki-temp-tps /tmp/pki-tps-old
    3. Replace the new instance name with the original TPS instance name. For example:
      sed -i 's/pki-temp-tps/pki-tps-old/g' /tmp/pki-tps-old
    4. Copy the file into the /etc/init.d/ directory.
      cp /tmp/pki-tps-old /etc/init.d
    5. Set the proper file owner and permissions for the file.
      chown pkiuser: /etc/init.d/pki-tps-old
      chmod 770 /etc/init.d/pki-tps-old
    6. Remove the temporary file.
      rm -rf /tmp/pki-tps-old
    7. Use pkiremove to remove the temporary TPS instance.
  8. Note the contents of the password.conf file, and then delete it.
    rm -rf /var/lib/instance_name/conf/password.conf

11.3.3. Changing System Passwords

Subsystem passwords are used by the subsystem instance to connect to a necessary service, like its internal database. These passwords are set in the service, so for them to change, they are changed on the external service. Then, any password changes need to be carried back to the Certificate System subsystem configuration.
The way that subsystem passwords can be changed depends on the type of password:
  • The internal password can be changed using the certutil command to update the NSS security database or in the subsystem's administrative interface, such as the console.
  • LDAP-related passwords, such as internaldb and tokendbpass for the internal database, can be changed in the LDAP server directly (using the Directory Server console or tools like ldapmodify).
  • LDAP publishing passwords are changed in the LDAP server, but that change means that the password must be updated in the Certificate System CA configuration. The publishing password is reset in the CA console; this automatically updates the password.conf file, if it exists.
  • Hardware token passwords can be changed on the hardware token itself, using its native tools.
The passwords must then be manually updated in the password.conf file or in the subsystem console. If the password file has been removed, then the new passwords can simply be entered when prompted at server startup.