The remote PEM / PKCS12 Orchestrator allows for the remote management of PEM and PKCS12 based certificate stores. Discovery, Inventory, and Management functions are supported. The orchestrator performs operations by issuing remote commands over SSH to Linux based systems and via WinRM to Windows based systems.
This repository contains a Windows Orchestrator AnyAgent, which is a plugin to the Keyfactor Windows Orchestrator. Within the Keyfactor Platform, Orchestrators are used to manage “certificate stores” — collections of certificates and roots of trust that are found within and used by various applications.
The Windows Orchestrator is part of the Keyfactor software distribution and is available via the Keyfactor customer portal. For general instructions on installing AnyAgents, see the “Keyfactor Command Orchestrator Installation and Configuration Guide” section of the Keyfactor documentation. For configuration details of this specific AnyAgent, see below in this readme.
Note that in Keyfactor Version 9, the Windows Orchestrator have been replaced by the Universal Orchestrator. While this AnyAgent continues to work with the Windows Orchestrator, and the Windows Orchestrator is supported alongside the Universal Orchestrator talking to Keyfactor version 9, AnyAgent plugins cannot be used with the Universal Orchestrator.
Remote PEM / PKCS12 is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket with your Keyfactor representative.
To report a problem or suggest a new feature, use the Issues tab. If you want to contribute actual bug fixes or proposed enhancements, use the Pull requests tab.
The PEM_PKCS12 Windows Orchestrator implements the following capabilities:
- Create - Create either a PEM or PKCS12 certificate store.
- Discovery - Discover all PEM or PKCS12 certificate stores in a set of paths based on optional list of file extensions and partial name matching.
- Inventory - Return all certificates for a defined certificate store.
- Management (Add) - Add a certificate to a defined certificate store.
- Management (Remove) - Remove a certificate from a defined certificate store.
The PEM_PKCS12 Windows Orchestrator supports the following types of certificate stores:
- PEM trust stores (multiple public (most likely CA) certificates with no private keys).
- PEM certificate stores containing one public certificate and one private key.
- PEM certificate stores containing one public certificate and an external private key stored in a separate file.
- PKCS12 certificate stores containing one certificate with a private key.
The version number of a the PEM_PKCS12 Windows Orchestrator can be verified by right clicking on the PEMStoreSSH.dll file in the Plugins installation folder, selecting Properties, and then clicking on the Details tab.
The PEM_PKCS12 Windows Orchestrator has been tested against Keyfactor Windows Orchestrator version 8.1.1 but should work against earlier or later versions of the Keyfactor Windows Orchestrator.
For Linux orchestrated servers:
- The PEM-PKCS12 AnyAgent makes use of a few common Linux commands. If the credentials you will be connecting with will need elevated access to run these commands, you must set the id up as a sudoer with no password necessary and set the config.json "UseSudo" value to "Y" (See Section 4 regarding the config.json file). The full list of these commands below:
- echo
- grep
- find
- touch
- who
- awk
- chown
- The PEM_PKCS12 AnyAgent makes use of SFTP to transfer files to and from the orchestrated server. SFTP will not make use of sudo, so all folders containing certificate stores will need to allow SFTP file transfer. If this is not possible, set the values in the config.json apprpriately to use an alternative upload/download folder that does have SFTP file transfer (See Section 4 regarding the config.json file).
For Windows orchestrated servers:
- Make sure that WinRM is set up on the orchestrated server and that the WinRM port is part of the certificate store path when setting up your certificate stores (See Section 3a below).
1. Create the New Certificate Store Type for the New PEM_PKCS12 Orchestrator
In Keyfactor Command create a new Certificate Store Type similar to the one below:
-
Name – Required. The display name of the new Certificate Store Type
-
Short Name – Required. MUST be "PEM-SSH"
-
Needs Server, Blueprint Allowed, Requires Store Password, Supports Entry Password – All checked/unchecked as shown
-
Supports Custom Alias – Required. Select Forbidden. Aliases are not used for PEM and PKCS12 stores.
-
Use PowerShell – Unchecked
-
Store PathType – Freeform (user will enter the location of the store)
-
Private Keys – Optional (a certificate in a PEM/PKCS12 Keystore may or may not contain a private key)
-
PFX Password Style – Select Custom.
-
Job Types – Discovery, Inventory, Add, and Remove are the 3 job types implemented by this Orchestrator
-
Parameters – Five custom parameters are used for this store type. They are:
-
Type (Name MUST be "type"):
- Separate Private Key File (Name MUST be "separatePrivateKey"): Only applicable for Type=PEM stores, select if the store will contain a private key but the private key will reside in an separate file somewhere else on the server
- Path to Private Key File (Name MUST be "pathToPrivateKey"): Only applicable for Type=PEM stores. If the PEM certificate store has a separate private key file, this is the FULL PATH and file name where the private key resides. File paths on Linux servers will always begin with a "/". Windows servers will always begin with the drive letter, colon, and backslash, such as "c:\".
- Contains Single Certificate (Name MUST be "isSingleCertificateStore"): Optional parameter, default value 'False'. If set to 'True' this certificate store will be managed with the assumption that only one certificate can exist in the store. All Management-Add jobs against this store will completely replace the contents of the store with the added certificate, assuming overwrite is set to 'True' for the job. If overwrite is not selected ('False'), the Management-Add job will complete with an error saying a certificate already exists. No alias/thumbprint matching will be done when adding/renewing a certificate when this value is set to 'True'.
- Linux File Permissions on Store Creation (Name MUST be "linuxFilePermissionsOnStoreCreation"): - Optional parameter. Overrides the optional config.json DefaultLinuxPermissionsOnStoreCreation setting (see section 4 below) for a specific certificate store. This value will set the file permissions (Linux only) of a new certificate store created via a Management-Create job. If this parameter is not added or added but not set, the permissions used will be derived from the DefaultLinuxPermissionsOnStoreCreation setting.
2. Register the PEM_PKCS12 Orchestrator with Keyfactor
Open the Keyfactor Windows Agent Configuration Wizard and perform the tasks as illustrated below:
- Click <Next>
- If you have configured the agent service previously, you should be able to skip to just click <Next>. Otherwise, enter the service account Username and Password you wish to run the Keyfactor Windows Agent Service under, click <Update Windows Service Account> and click <Next>.
- If you have configured the agent service previously, you should be able to skip to just re-enter the password to the service account the agent service will run under, click <Validate Keyfactor Connection> and then <Next>.
- Select the agent you are adding capabilities for (in this case, PEM SSH, and also select the specific capabilities (Discovery, Inventory and Management in this example). Click <Next>.
- For agent configuration purposes, this screen can be skipped by clicking <Next>.
- For each Orchestrator implementation, check Load assemblies containing extension modules from other location , browse to the location of the compiled Orchestrator dll, and click <Validate Capabilities>. Once all Orchestrators have been validated, click <Apply Configuration>.
- If the Keyfactor Agent Configuration Wizard configured everything correctly, you should see the dialog above.
3a. (Optional) Create a PEM_PKCS12 Certificate Store within Keyfactor Command
If you choose to manually create a PEM_PKCS12 store In Keyfactor Command rather than running a Discovery job to automatically find the store, you can navigate to Certificate Locations => Certificate Stores within Keyfactor Command to add the store. Below are the values that should be entered.
-
Category – Required. The PEM SSH type name must be selected.
-
Container – Optional. Select a container if utilized.
-
Client Machine & Credentials – Required. The server name or IP Address and login credentials for the server where the Certificate Store is located. The credentials for server login can be any of:
-
UserId/Password
-
UserId/SSH private key (entered in the password field)
-
PAM provider information to pass the UserId/Password or UserId/SSH private key credentials
When setting up a Windows server, the format of the machine name must be – http://ServerName:5985, where "5985" is the WinRM port number. 5985 is the standard, but if your organization uses a different port, use that. The Keyfactor Command service account will be used if the credentials are left blank. However, if you choose to not enter credentials and use the Keyfactor Command service account, it is required that the Change Credentials link still be clicked on and the resulting dialog closed by clicking OK.
-
-
Store Path – Required. The FULL PATH and file name of the PEM/PKCS12 store being managed. File paths on Linux servers will always begin with a "/". Windows servers will always begin with the drive letter, colon, and backslash, such as "c:\". Valid characters for Linux store paths include any alphanumeric character, space, forward slash, hyphen, underscore, and period. For Windows servers, the aforementioned characters as well as a colon and backslash.
-
Type – Select either PEM or PKCS12
-
Separate Private Key File – Check if the store has a separate private key file.
-
Path to Private Key File – If Separate Private Key File is checked, enter the FULL PATH to the private key file. File paths on Linux servers will always begin with a "/". Windows servers will always begin with the drive letter, colon, and backslash, such as "c:". Valid characters for Linux private key paths include any alphanumeric character, space, forward slash, hyphen, underscore, and period. For Windows servers, the aforementioned characters as well as a colon and backslash.
-
Orchestrator – Select the orchestrator you wish to use to manage this store
-
Store Password – Required. Set the store password or set no password after clicking the supplied button. If a store password is entered, this value will be used when encrypting private keys that get written to the certificate store during certificate add operations. Selecting "No Password" will cause an unencrypted private key to be saved during add operations.
-
Linux File Permissions on Store Creation - Optional (Linux only). Set the Linux file permissions you wish to be set when creating a new physical certificate store via checking Create Certificate Store above. This value must be 3 digits all betwwen 0-7.
-
Inventory Schedule – Set a schedule for running Inventory jobs or none, if you choose not to schedule Inventory at this time.
3b. (Optional) Schedule a PEM_PKCS12 Discovery Job
Rather than manually creating PEM_PKCS12 certificate stores, you can schedule a Discovery job to search an orchestrated server and find them.
First, in Keyfactor Command navigate to Certificate Locations => Certificate Stores. Select the Discover tab and then the Schedule button. Complete the dialog and click Done to schedule.
-
Category – Required. The PEM SSH type name must be selected.
-
Orchestrator – Select the orchestrator you wish to use to manage this store
-
Client Machine & Credentials – Required. The server name or IP Address and login credentials for the server where the Certificate Store is located. The credentials for server login can be any of:
-
UserId/Password
-
UserId/SSH private key (entered in the password field)
-
PAM provider information to pass the UserId/Password or UserId/SSH private key credentials
When setting up a Windows server, the format of the machine name must be – http://ServerName:5985, where "5985" is the WinRM port number. 5985 is the standard, but if your organization uses a different port, use that. The Keyfactor Command service account will be used if the credentials are left blank. However, if you choose to not enter credentials and use the Keyfactor Command service account, it is required that the Change Credentials link still be clicked on and the resulting dialog closed by clicking OK.
-
-
When – Required. The date and time when you would like this to execute.
-
Directories to search – Required. A comma delimited list of the FULL PATHs and file names where you would like to recursively search for PEM/PKCS12 stores. File paths on Linux servers will always begin with a "/". Windows servers will always begin with the drive letter, colon, and backslash, such as "c:\". Entering the string "fullscan" when Discovering against a Windows server will automatically do a recursive search on ALL local drives on the server.
-
Directories to ignore – Optional. A comma delimited list of the FULL PATHs that should be recursively ignored when searching for PEM/PKCS12 stores. Linux file paths will always begin with a "/". Windows servers will always begin with the drive letter, colon, and backslash, such as "c:\".
-
Extensions – Optional but suggested. A comma delimited list of the file extensions (no leading "." should be included) the job should search for. If not included, only files in the searched paths that have no file extension will be returned. If providing a list of extensions, using "noext" as one of the extensions will also return files with no file extension. For example, providing an Extensions list of "pem, noext" would return all file locations within the paths being searched with a file extension of "pem" and files with no extensions.
-
File name patterns to match – Optional. A comma delimited list of full or partial file names (NOT including extension) to match on. Use "*" as a wildcard for begins with or ends with. Example: entering "ab*, *cd*, *ef, ghij" will return all stores with names that begin with "ab" AND stores with names that contain "cd" AND stores with names ending in "ef" AND stores with the exact name of "ghij".
-
Follow SymLinks – NOT IMPLEMENTED. Leave unchecked.
-
Include PKCS12 Files – Leave unchecked to validate that each certificate store returned is of type = PEM. Checking this box will return all found certificate stores without validation. Leave this selection unchecked when attempting to Discover PKCS12 stores.
Once the Discovery job has completed, a list of PEM/PKCS12 store locations should show in the Certificate Stores Discovery tab in Keyfactor Command. Right click on a store and select Approve to bring up a dialog that will ask for the Keystore Password. Enter the store password, click Save, and the Certificate Store should now show up in the list of stores in the Certificate Stores tab.
From the Certificate Store list, edit the newly added store to enter the PEM_PKCS12 store type (PEM or PKCS12), whether the store has a separate private key file, and if necessary, the FULL PATH to that file. NOTE: You will not be able to successfully process an Inventory or Management job for this store until this has been completed.
4. Update Settings in config.json
The PEM_PKCS12 Orchestrator uses a JSON config file:
{
"UseSudo": "N",
"CreateStoreOnAddIfMissing": "N",
"UseSeparateUploadFilePath": "N",
"SeparateUploadFilePath": "/path/to/upload/folder/",
"UseNegotiateAuth": "N",
"UseSCP": "N",
"DefaultLinuxPermissionsOnStoreCreation": "600"
}
UseSudo - Y/N - Determines whether to prefix certain Linux command with "sudo". This can be very helpful in ensuring that the user id running commands ssh uses "least permissions necessary" to process each task. Setting this value to "Y" will prefix all Linux commands with "sudo" with the expectation that the command being executed on the orchestrated Linux server will look in the sudoers file to determine whether the logged in ID has elevated permissions for that specific command. For orchestrated Windows servers, this setting has no effect. Setting this value to "N" will result in "sudo" not being added to Linux commands.
CreateStoreOnAddIfMissing - Y/N - Determines if during a Management-Add job if a certificate store should be created if it does not already exist. If set to "N", the job will return an error with a message stating that the store does not exist.
UseSeparateUploadFilePath (Linux only) – When adding a certificate to a PEM or PKCS12 store, the PEM_PKCS12 Orchestrator must upload the certificate being deployed to the server where the certificate store resides. Setting this value to "Y" looks to the next setting, SeparateUploadFilePath, to determine where this file should be uploaded. Set this value to "N" to use the same path where the certificate store being managed resides.
SeparateUploadFilePath (Linux only) – Only used when UseSeparateUploadFilePath is set to "Y". Set this to the path you wish to use as the location to upload and later remove PEM/PKCS12 certificate store data before being moved to the final destination.
UseNegotiateAuth (Windows only) – Y/N - Determines if WinRM should use Negotiate (Y) when connecting to the remote server.
UseSCP (Optional, Linux only) - Y/N - Detemines if SCP (Y) or SFTP (N) should be used in uploading certificate files during Management-Add jobs.
DefaultLinuxPermissionsOnStoreCreation (Linux only) - Optional. Value must be 3 digits all between 0-7. The Linux file permissions that will be set on a new certificate store created via a Management Create job. This value will be used for all certificate stores managed by this orchestrator instance unless overridden by the optional "Linux File Permissions on Store Creation" custom parameter setting on a specific certificate store. If "Linux File Permissions on Store Creation" and DefaultLinuxPermissionsOnStoreCreation are not set, a default permission of 600 will be used.