Use kfutil to bulk create PEM bindings

Created: Updated:

This article will review the procedures required to create multiple PEM file certificate stores in the Command platform. This solution will leverage a CSV file that contains the certificate store details like hostname, store path, and binding details to be managed by Command.

Prerequisites

This document requires:

  • Keyfactor Command
  • A Linux or Windows machine that is running the universal orchestrator
  • The remote-file-orchestrator extension installed and registered with the universal orchestrator
  • A machine where kfutil is installed
  • The user running kfutil has the appropriate rights in Keyfactor Command to issue Keyfactor API and management functions (or an appropriate token, etc.)

Target machine prerequisites

There are some items to consider, depending on the managed target’s environment. If the universal orchestrator logs into the target machine as the PEM store owner, no further configuration is required. If the universal orchestrator logs into the target machine as a different account, then that account must have the permissions described below.

Least privilege configuration

Typically, the target machines for PEM stores are located on Linux-type operating systems. Additionally, the store owner is not the same as the user used by the universal orchestrator to log in. Finally, there may be multiple stores located on the target machine with multiple owners.

The good news is that the remote-file-orchestrator can easily handle these use cases. The following items are required to support the above use cases.

  • The universal orchestrator must log in to the target machine as a sudoer user.
  • The universal orchestrator login user must have sudoer NOPASSWD privileges.
  • The login can be limited to specific commands on the target machine, which is best practice.
  • The universal orchestrator should use a working directory to perform operations on the PEM stores.

What follows is only required if this special use case needs to be configured. This must be done on every machine where there are certificate stores that need management using this use case.

Give universal orchestrator user sudoer privileges

  1. Log in to the target machine as a user with sudo permissions.

  2. Run the following command to find the location of the commands required to manage a PEM.

    which echo find cp ls chown tee rm install

    The result looks similar to the following:

    /usr/bin/echo
/usr/bin/find
/usr/bin/cp
/usr/bin/ls
/usr/bin/chown
/usr/bin/tee
/usr/bin/rm
/usr/bin/install

  3. Next run the following command.

    sudo visudo -f /etc/sudoers.d/<username>

  4. Add the following line into the file.

    <username> ALL=(ALL) NOPASSWD: <comma_separated_list_of_commands>

    Example for the keyfactor user and the result above:

    sudo visudo -f /etc/sudoers.d/keyfactor

keyfactor ALL=(ALL) NOPASSWD: /usr/bin/echo, /usr/bin/find, /usr/bin/cp, /usr/bin/ls, /usr/bin/chown, /usr/bin/tee, /usr/bin/rm, /usr/bin/install
  5. Log out of the machine as the sudo user.

Create a working directory for the universal orchestrator user

  1. Log in to the machine as the universal orchestrator user.

  2. Create a working directory for the orchestrator.

    mkdir ~/working-directory

Extension configuration prerequisites

Do this only if you are using the least privileged configuration from above. Otherwise, skip to the Create store type step.
  1. Log in to the universal orchestrator machine as a user with sudo permissions.

  2. Edit the configuration file for the remote-file-orchestrator.

    sudo vi <path-to-remote-file-orchestrator>/config.json

    Normally, the path to the universal orchestrator extension is located here:
    /opt/keyfactor/orchestrator/extensions/remote-file-orchestrator/.

  3. Change the following lines in the configuration file.

    • UseSudo → change from "N" to "Y"
    • SeparateUploadFilePath → change from "" to "/home/<username>/working-directory"

    For example, if the universal orchestrator is logging in as keyfactor, the file would look something like the following:

    {
  "UseSudo": "Y",
  "DefaultSudoImpersonatedUser": "",
  "CreateStoreIfMissing": "N",
  "UseNegotiate": "N",
  "SeparateUploadFilePath": "/home/keyfactor/working-directory",
  "FileTransferProtocol": "SCP",
  "DefaultLinuxPermissionsOnStoreCreation": "600",
  "DefaultOwnerOnStoreCreation": "",
  "SSHPort":  ""
}

Create store type

The first step is to define the store type of the remote file PEM store.

Step 1: Determine if store type exists

  1. Log in to the kfutil machine.

  2. Determine if the RFPEM already exists by running the following kfutil command:

    kfutil store-types list | jq -r '.[].Name'
  3. Look for the RFPEM output. If RFPEM exists, skip the Define store types steps.

Step 2: Define store types

  1. Log in to the kfutil machine.

  2. Create the remote file PEM store type.

    kfutil store-types create
  3. When prompted with Choose an option:, select RFPEM.

Procedure

To bulk configure multiple PEM stores, we utilize a CSV file. The kfutil program requires a specific set of columns to create the certificate stores in Keyfactor Command. These columns vary based on store types.

Step 1: Create CSV template

We can use the kfutil program to generate this template.

kfutil stores import generate-template --store-type-name=RFPEM

The output should look like the following:

Template file for store type with id 103 written to RFPEM_bulk_import_template.csv

Step 2: Populate the CSV

Populate the CSV with data about the stores you need to access:

Parameter Description Example
AgentId The GUID of the orchestrator that will manage the certificate store. This can be found in Keyfactor Command > Orchestrator > Management and double clicking the orchestrator. The Id field is the GUID to enter here. 91dd52a9-8449-4535-a191-b9b6acf1d2b6
ClientMachine The IP address or DNS of the server hosting the certificate store. 10.10.3.4
ContainerId The Keyfactor assigned GUID for the container in which to populate the certificate or <blank> for no container  
CreateIfMissing When set to true, the file is created on the system if it doesn’t exist. When set to false, an error code is sent back to Command stating the file does not exist. true
ServerUseSsl When connecting to the remote system containing the JKS file/store, true enables an SSL connection and false does not. For SSH connections, use false false
ServerUsername

One of the following usernames to use when logging into a remote system:

  • A username
  • A valid PAM key if the username is stored in a KF Command configured PAM integration
  • <blank> if accessing a local file and not a remote file
 uo-login
ServerPassword

One of the following to use when logging into the remote system:

  • A password associated with the ServerUsername
  • An SSH private key to use instead of a password
  • A valid PAM key if the password is stored in a PAM provider Keyfactor Command has been configured to use
  • <blank> if accessing a local file and not a remote file
 S@cret-P@ssword
SudoImpersonatingUser A valid user ID to impersonate using sudo on the destination Linux server. Example: 'impersonatedUserID'. Overrides DefaultSudoImpersonatedUser config.json setting.  
StorePath The full path and file name, including file extension if one exists, where the certificate store file is located. For Linux orchestrated servers, StorePath will begin with a forward slash (i.e. /folder/path/storename.ext). For Windows orchestrated servers, it should begin with a drive letter (i.e. c:\folder\path\storename.ext). /etc/nginx/trust_store.pem
SeparatePrivateKeyFilePath <blank> or the full path and filename, including the file extension where the private key file is located.  
IgnorePrivateKeyOnInventory

true or false

true = do not look for the private key when an inventory job is performed. NOTE: this setting prevents any management jobs from operating on the store.

false = look for the associated private key when the inventory job is performed. The key can be located inside of the store or in a separate file designated by the SeparatePrivateKeyFilePath above

  
Password

The PEM private key encryption password or <BLANK> if none.

A JSON structure containing:
{
"SecretValue": "MySecretPassword",
"SecretTypeGuid": "123e4567-e89b-12d3-a456-426614174000",
"InstanceId": "my-instance-id"
}

SecretTypeGuid and InstanceId are optional and not used of the entry is just a password.

SecretTypeGuid and InstanceId are typically used when retrieving data from an HSM or the like.

 {
"SecretValue": "MySecretPassword"
}
IsTrustStore true = the store can contain multiple, unrelated certificates without any private key entries.
false = for a single certificate or certificate chain. May or may not contain a private key.		  
IncludesChain

true = the store contains multiple certificates representing the full chain of trust from leaf to root.

false = the store only contains a single leaf certificate.

 60
LinuxFilePermissionsOnStoreCreation A three-digit octet value [000-777] for the Linux file permissions on the certificate store when created. Example: '600' or '755'. Overrides DefaultLinuxPermissionOnStoreCreation config.json setting. 644
LinuxFileOwnerOnStoreCreation A valid username to set for the store owner and store group. www-data
InventorySchedule.Weekly.Time <blank> or Datetime value of when to execute an inventory job on this store  
InventorySchedule.Interval.Minutes <blank> or an integer value of the number of Minutes between inventory jobs on this store 60
InventorySchedule.Immediate When true a one-time inventory job is scheduled at store creation. When false the one-time job is not created.  
InventorySchedule.Daily.Time <blank> or a Timestamp value for when to run the inventory job  
InventorySchedule.Weekly.Days <blank>  

Then save the CSV file and transfer it to the machine you have kfutil installed on. Be sure to save this without UTF-8 formatting, as kfutil cannot process UTF-8 files.

Do NOT use UTF-8 formatting for the CSV. If you do, you will get an error.

Step 3: Run the bulk upload

Run the kfutil program with the following commands to upload the contents of the CSV as certificate stores.

kfutil stores import csv --file <csv_filename> --store-type-name RFPEM

The output should look like the following:

2 records processed.
2 certificate stores successfully created.
Import results written to Book1_results.csv

Verify the results by opening the result CSV file.

cat Book1_results.csv

Step 4: Verify the results

If additional verification is required, use the Keyfactor Command Portal.

  1. Access Orchestrators > Management.
  2. Select the orchestrator that corresponds to the request above.
  3. Select View Certificate Stores.
  4. A list of certificate stores the orchestrator can manage will appear. The following image shows navigating to the certificate stores that the orchestrator will manage.

    image-20250507-214839.png

     

Related articles

Comments

Please sign in to leave a comment.

Back to top