Automatic credential rotation options

Trust Protection Foundation provides the ability to rotate important system credentials using user-provided scripts via a command line interface (CLI). This means if you have an external system that rotates these credentials, you can write a script that will automatically change the connection information for Trust Protection Foundation automatically.

Credentials you can script for rotation:

• HSM connection pin
• Trust Protection Foundation database connection password
• Identity provider. For more information, see Updating an identity provider connection password.

To reset the HSM connection pin using the command line

Each Trust Protection Foundation server keeps its own copy of the HSM PIN in the registry, and the HSM connectors in the configuration database hold the copy that Trust Protection Foundation presents when it logs in to the HSM. Starting in 25.3.6, -hsmpin updates both, so run it on every server in the cluster after you change the partition PIN.

Before you start, you need the user name and password of a local master administrator: a local identity that holds All Privileges on the root. -hsmpin requires these credentials. The Trust Protection Foundation services do not need to be running.

1. Change the PIN on the HSM partition.

   Do this first. Trust Protection Foundation tests the new PIN against the HSM before it stores anything, so a PIN that the HSM has not accepted yet fails with response code 403 and nothing changes. The HSM must be reachable from the server.

   IMPORTANT  Every refused PIN counts toward the HSM's login lockout. Confirm the new PIN before you run the command, and confirm it again before any retry.

2. On the Trust Protection Foundation server, open an elevated command prompt and browse to the Venafi\Platform directory.

   If you installed Trust Protection Foundation in the default directory, you would browse to the following location:

   c:\Program Files\Venafi\Platform

3. Run the configuration utility (TppConfiguration.exe) with the -hsmpin switch, and enter the PIN and the master administrator password when you are prompted for them. For example:

   TppConfiguration.exe -hsmpin -username:<local master administrator>

   Leave the PIN off the switch, as shown here, and the command prompts for it with Please enter the new HSM pin: and then asks you to type it a second time to confirm it. Typing the PIN at the prompt keeps it out of your command history and out of any script. An empty PIN is refused, and so is a PIN typed with a key that is not a character, such as an arrow or Delete; correct mistakes with Backspace.

   To supply the PIN inline instead, use -hsmpin:<new PIN>. An unattended run must do this and add -password, because the prompts are unavailable when input or output is redirected. A redirected run that omits the PIN stops with ERROR: -hsmpin needs the pin, given as '-hsmpin:<pin>', when input or output is redirected and returns response code 1.

   NOTE  This utility is not designed to move your Venafi server from one database to another. It is intended only for changing credentials and scripting credential changes.

4. Confirm that the command returns response code 0.

   At response code 0, the command prints one of the following lines, and writes the same text to the Windows Application log under the source Trust Protection Foundation MMC Snap-In:

   • TppConfiguration: Encryption driver pin brought up to date on N driver(s); M already held it (event 90)

   • TppConfiguration: Encryption driver pin was already up to date on M driver(s) (event 91)

   • TppConfiguration: No PKCS#11 encryption driver exists in the configuration database, so the only copy of the pin to update on this server was its registry copy, which the bootstrap uses. (event 93)

   Every successful run then ends with TppConfiguration: Services on this server must be restarted for the new pin to take effect; in a cluster, run this command on every other server as well (event 92). The next two steps restart those services.

   If the command returns 403, nothing changed, and the HSM refused the PIN. If it returns 404, the server's own copy of the PIN was stored but the HSM connectors were not updated: correct the problem the command reports, then run the command again. Re-running is safe, because connectors that already hold the new PIN are left alone.

5. Restart the Trust Protection Foundation Windows services.
6. Restart the Trust Protection Foundation IIS Application Pools, or perform an IIS Reset.

7. Repeat steps 2 through 6 on every other server in the cluster.

   Each server keeps its own copy of the PIN, so every server needs the command. The HSM connectors are shared, so the servers you run after the first one report the connectors as already up to date.

-hsmpin updates an HSM connector only when all three of the following match the server you run it on. Disabled connectors are included, because a connector that is enabled again logs in with the PIN it holds.

• The connector loads the same PKCS#11 library path.

• The connector uses the same account type. A connector that does not set one counts as Crypto Officer.

• The connector's token label and serial resolve to the same token.

Connectors that do not match are skipped, and the command does not name them. To find them, compare each PKCS#11 encryption driver against the three criteria above.

A connector that records only a slot number has no token label to match yet. It is given one the next time the Trust Protection Foundation services start, so start the services and then run -hsmpin again. A connector on a different PKCS#11 library path or account type belongs to a different token or a different set of servers: run -hsmpin on a server whose configuration matches that connector.

If no connector at all matches, the command returns response code 404, having already stored the server's own copy of the PIN, and reports which token and library path it looked for:

For more information on using the command line to perform actions in Trust Protection Foundation, see Configure the platform using a script through the command line.

To reset the Trust Protection Foundation database owner account connection password using the command line

1. On the Trust Protection Foundation server, open a command prompt and browse to the Venafi\Platform directory.

   If you installed Trust Protection Foundation in the default directory, you would browse to the following location:

   c:\Program Files\Venafi\Platform

2. Run the configuration utility (TppConfiguration.exe) with the -dboconfig switch. The format is:

   TppConfiguration.exe "-dboconfig:<cfg>"

   For example:

   TppConfiguration.exe -dboconfig:"Data Source=192.168.1.1,1433;Initial Catalog=databasename;User ID=dbOwnerUser;Password=S0me\"thing-Complex!"

   To obtain your current SQL configuration string, see Obtaining the SQL database connection string.

3. Restart the Trust Protection Foundation Windows services.
4. Restart the Trust Protection Foundation IIS Application Pools, or perform an IIS Reset.

To reset the Trust Protection Foundation operational database account connection password using the command line

1. On the Trust Protection Foundation server, open a command prompt and browse to the Venafi\Platform directory.

   If you installed Trust Protection Foundation in the default directory, you would browse to the following location:

   c:\Program Files\Venafi\Platform

2. Run the configuration utility (TppConfiguration.exe) with the -sqlconfig switch. The format is:

   TppConfiguration.exe "-sqlconfig:<cfg>"

   For example:

   TppConfiguration.exe -sqlconfig:"Data Source=192.168.1.1,1433;Initial Catalog=databasename;User ID=dbOperationUser;Password=S0me\"thing-Complex!"

   To obtain your current SQL configuration string, see Obtaining the SQL database connection string.

3. Restart the Trust Protection Foundation Windows services.
4. Restart the Trust Protection Foundation IIS Application Pools, or perform an IIS Reset.

For more information about the TPPConfiguration utility, see Using the TppConfiguration command line tool.