diff --git a/CHANGELOG.md b/CHANGELOG.md index b4a8d915..ce9e0e70 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ +v2.6.0 +- Added ability for Linux installed universal orchestrator to manage stores as an "agent" (stores reside on same server as universal orchestrator) without the need to have SSH enabled. +- Added ability for Linux installed universal orchestrator to manage certificate stores on Windows servers by using SSH to communicate between the Linux UO server and the Windows machines hosting the certificate stores. +- Modified Discovery against Linux servers to use the -name option instead of -iname for the Linux shell "find" command, so Discovery will work for AIX servers. +- Upgraded several NuGet packages. + v2.5.0 - Add new optional custom field and config.json entries to supply a user id other than "root" for the user to "sudo into" when UseSudo = "Y". There is an optional config.json DefaultSudoImpersonatedUser that will be used at the orchestrator level, and an optional new store type custom field, SudoImpersonatedUser, that overrides the config.json setting for each certificate store. - Modified the optional sudo command prefix to remove the "-i" option which was creating a new shell for the impersonated id (always root up until this release). Without this option the profile for the logged in user and not the impersonated user will be used when running commands. diff --git a/README.md b/README.md index 132c8cf0..8fa8fae8 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ The Keyfactor Universal Orchestrator may be installed on either Windows or Linux |Supports Management Remove|✓ |✓ | |Supports Create Store|✓ |✓ | |Supports Discovery|✓ |✓ | -|Supports Renrollment| | | +|Supports Reenrollment| | | |Supports Inventory|✓ |✓ | @@ -102,34 +102,108 @@ This text would be entered in as the value for the __Server Password__, instead  ## Overview The Remote File Orchestrator Extension is a multi-purpose integration that can remotely manage a variety of file-based certificate stores and can easily be extended to manage others. The certificate store types that can be managed in the current version are: -- Java Keystores of type JKS -- PKCS12 files, including, but not limited to, Java keystores of type PKCS12 -- PEM formatted files -- DER formatted files -- IBM Key Database files (KDB) -- Oracle Wallet Pkcs12 files -While the Keyfactor Universal Orchestrator (UO) can be installed on either Windows or Linux; likewise, the Remote File Orchestrator Extension can be used to manage certificate stores residing on both Windows and Linux servers. The supported configurations of Universal Orchestrator hosts and managed orchestrated servers are shown below: +
+RFPkcs12 + +The RFPkcs12 store type can be used to manage any PKCS#12 compliant file format INCLUDING java keystores of type PKCS12. + +Use cases supported: +1. One-to-many trust entries - A trust entry is considered single certificate without a private key in a certificate store. Each trust entry is identified with a custom alias. +2. One-to-many key entries - One-to-many certificates with private keys and optionally the full certificate chain. Each certificate identified with a custom alias. +3. A mix of trust and key entries. + +
+ +
+RFJKS + +The RFJKS store type can be used to manage java keystores of type JKS. **PLEASE NOTE:** Java keystores of type PKCS12 **_cannot_** be managed by the RFJKS type. You **_must_** use RFPkcs12. + +Use cases supported: +1. One-to-many trust entries - A trust entry is considered single certificate without a private key in a certificate store. Each trust entry is identified with a custom alias. +2. One-to-many key entries - One-to-many certificates with private keys and optionally the full certificate chain. Each certificate identified with a custom alias. +3. A mix of trust and key entries. + +
+ +
+RFPEM + +The RFPEM store type can be used to manage PEM encoded files. + +Use cases supported: +1. Trust stores - A file with one-to-many certificates (no private keys, no certificate chains). +2. Single certificate stores with private key in the file. +3. Single certificate stores with certificate chain and private key in the file. +4. Single certificate stores with private key in an external file. +5. Single certificate stores with certificate chain in the file and private key in an external file + +NOTE: PEM stores may only have one private key (internal or external) associated with the store, as only one certificate/chain/private key combination can be stored in a PEM store supported by RFPEM. + +
+ +
+ +RFDER + +The RFDER store type can be used to manage DER encoded files. + +Use cases supported: +1. Single certificate stores with private key in an external file. +2. Single certificate stores with no private key. + +
+ +
+RFKDB + +The RFKDB store type can be used to manage IBM Key Database Files (KDB) files. The IBM utility, GSKCAPICMD, is used to read and write certificates from and to the target store and is therefore required to be installed on the server where each KDB certificate store being managed resides, and its location MUST be in the system $Path. + +Use cases supported: +1. One-to-many trust entries - A trust entry is considered single certificate without a private key in a certificate store. Each trust entry is identified with a custom alias. +2. One-to-many key entries - One-to-many certificates with private keys and optionally the full certificate chain. Each certificate identified with a custom alias. +3. A mix of trust and key entries. + +
+ +
+RFORA + +The RFORA store type can be used to manage Pkcs12 Oracle Wallets. Please note that while this should work for Pkcs12 Oracle Wallets installed on both Windows and Linux servers, this has only been tested on wallets installed on Windows. Please note, when entering the Store Path for an Oracle Wallet in Keyfactor Command, make sure to INCLUDE the eWallet.p12 file name that by convention is the name of the Pkcs12 wallet file that gets created. + +Use cases supported: +1. One-to-many trust entries - A trust entry is considered single certificate without a private key in a certificate store. Each trust entry is identified with a custom alias. +2. One-to-many key entries - One-to-many certificates with private keys and optionally the full certificate chain. Each certificate identified with a custom alias. +3. A mix of trust and key entries. + +
+ +The Keyfactor Univeral Orchestrator (UO) and RemoteFile Extension can be installed on either Windows or Linux operating systems as well as manage certificates residing on servers of both operating systems. A UO service managing certificates on remote servers is considered to be acting as an Orchestrator, while a UO service managing local certificates on the same server running the service is considered an Agent. When acting as an Orchestrator, connectivity from the orchestrator server hosting the RemoteFile extension to the orchestrated server hosting the certificate store(s) being managed is achieved via either an SSH (for Linux and possibly Windows orchestrated servers) or WinRM (for Windows orchestrated servers) connection. When acting as an agent, SSH/WinRM may still be used, OR the certificate store can be configured to bypass these and instead directly access the orchestrator server's file system. + +![](images/orchestrator-agent.png) + +Please review the [Prerequisites and Security Considerations](#prerequisites-and-security-considerations) and [Certificate Stores and Discovery Jobs](#certificate-stores-and-discovery-jobs) sections for more information on proper configuration and setup for these different architectures. The supported configurations of Universal Orchestrator hosts and managed orchestrated servers are detailed below: | | UO Installed on Windows | UO Installed on Linux | |-----|-----|------| -|Orchestrated Server on remote Windows server|✓ | | -|Orchestrated Server on remote Linux server|✓ |✓ | -|Orchestrated Server on same server as orchestrator service (Agent)|✓ |✓ | +|Orchestrated Server hosting certificate store(s) on remote Windows server|WinRM connection | SSH connection | +|Orchestrated Server hosting certificate store(s) on remote Linux server| SSH connection | SSH connection | +|Certificate store(s) on same server as orchestrator service (Agent)| WinRM connection or local file system | SSH connection or local file system | -This orchestrator extension makes use of an SSH connection to communicate remotely with certificate stores hosted on Linux servers and WinRM to communicate with certificate stores hosted on Windows servers. -  -  +  ## Versioning The version number of a the Remote File Orchestrator Extension can be verified by right clicking on the RemoteFile.dll file in the Extensions/RemoteFile installation folder, selecting Properties, and then clicking on the Details tab.     -## Security Considerations +## Prerequisites and Security Considerations + +
+Certificate stores hosted on Linux servers: -**For Linux orchestrated servers:** -1. The Remote File Orchestrator Extension makes use of a few common Linux commands when managing stores on Linux servers. If the credentials you will be connecting with need elevated access to run these commands or to access the certificate store files these commands operate against, you must set up the user id as a sudoer with no password necessary and set the config.json "UseSudo" value to "Y" (See "Config File Setup" later in this README for more information on setting up the config.json file). The full list of these commands below: +1. The Remote File Orchestrator Extension makes use of a few common Linux commands when managing stores on Linux servers. If the credentials you will be connecting with need elevated access to run these commands or to access the certificate store files these commands operate against, you must set up the user id as a sudoer with no password necessary and set the config.json "UseSudo" value to "Y". When RemoteFile is using orchestration, managing local or external certificate stores using SSH or WinRM, the security context is determined by the user id entered in the Keyfactor Command certificate store or discovery job screens. When RemoteFile is running as an agent, managing local stores only, the security context is the user id running the Keyfactor Command Universal Orchestrator service account. The full list of these commands below: |Shell Command|Used For| |---|---| @@ -141,29 +215,39 @@ The version number of a the Remote File Orchestrator Extension can be verified b |rm|Used by Inventory and Management Add/Remove jobs to remove temporary files (only when an alternate upload/download folder has been configured).| |install|Used by the Management Create Store job when initializing a certificate store file.| |orapki|Oracle Wallet CLI utility used by Inventory and Management Add/Remove jobs to manipulate an Oracle Wallet certificate store. Used for the RFORA store type only.| -|gskcapicmd|IBM Key Database CLI utility used by Inventory and Management Add/Remove jobs to manipulate an IBM Key Database certificate store. Used for the RFKDB store type only.| +|gskcapicmd|IBM Key Database CLI utility used by Inventory and Management Add/Remove jobs to manipulate an IBM Key Database certificate store. Used for the RFKDB store type only.| + +2. When orchestrating management of local or external certificate stores, the Remote File Orchestrator Extension makes use of SFTP and/or SCP to transfer files to and from the orchestrated server. SFTP/SCP cannot make use of sudo, so all folders containing certificate stores will need to allow SFTP/SCP file transfer for the user assigned to the certificate store/discovery job. If this is not possible, set the values in the config.json apprpriately to use an alternative upload/download folder that does allow SFTP/SCP file transfer. If the certificate store/discovery job is configured for local (agent) access, the account running the Keyfactor Universal Orchestrator service must have access to read/write to the certificate store location, OR the config.json file must be set up to use the alternative upload/download file. + +3. SSH Key Authentication: When creating a Keyfactor certificate store for the remote file orchestrator extension, you may supply either a user id and password for the certificate store credentials (directly or through one of Keyfactor Command's PAM integrations), or supply a user id and SSH private key. Both PKCS#1 (BEGIN RSA PRIVATE KEY) and PKCS#8 (BEGIN PRIVATE KEY) formats are supported for the SSH private key. If using the normal Keyfactor Command credentials dialog without PAM integration, just copy and paste the full SSH private key into the Password textbox. SSH Key Authentication is not available when running locally as an agent. -2. The Remote File Orchestrator Extension makes use of SFTP and/or SCP to transfer files to and from the orchestrated server. SFTP/SCP cannot make use of sudo, so all folders containing certificate stores will need to allow SFTP/SCP file transfer. If this is not possible, set the values in the config.json apprpriately to use an alternative upload/download folder that does allow SFTP/SCP file transfer (See "Config File Setup" later in this README regarding the config.json file). +Please reference [Configuration File Setup](#configuration-file-setup) for more information on setting up the config.json file and [Certificate Stores and Discovery Jobs](#certificate-stores-and-discovery-jobs) for more information on the items above. +
-3. SSH Key Authentication: When creating a Keyfactor certificate store for the remote file orchestrator extension (see "Creating Certificate Stores" later in this README, you may supply either a user id and password for the certificate store credentials (directly or through one of Keyfactor Command's PAM integrations), or a user id and SSH private key. Both PKCS#1 (BEGIN RSA PRIVATE KEY) and PKCS#8 (BEGIN PRIVATE KEY) formats are supported for the SSH private key. If using the normal Keyfactor Command credentials dialog without PAM integration, just copy and paste the full SSH private key into the Password textbox. +
+Certificate stores hosted on Windows servers: +1. When orchestrating management of external (and potentially local) certificate stores, the RemoteFile Orchestrator Extension makes use of WinRM to connect to external certificate store servers. The security context used is the user id entered in the Keyfactor Command certificate store or discovery job screen. Make sure that WinRM is set up on the orchestrated server and that the WinRM port (by convention, 5585 for HTTP and 5586 for HTTPS) is part of the certificate store path when setting up your certificate stores/discovery jobs. If running as an agent, managing local certificate stores, local commands are run under the security context of the user account running the Keyfactor Universal Orchestrator Service. Please reference [Certificate Stores and Discovery Jobs](#certificate-stores-and-discovery-jobs) for more information on creating certificate stores for the RemoteFile Orchestrator Extension. -**For Windows orchestrated servers:** -1. 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 When creating a new certificate store in Keyfactor Command (See "Creating Certificate Stores" later in this README). +
Please consult with your company's system administrator for more information on configuring SSH/SFTP/SCP or WinRM in your environment. -  + +   ## Remote File Orchestrator Extension Installation -1. Create the certificate store types you wish to manage. Please refer to the individual sections devoted to each supported store type under "Certificate Store Types" later in this README. -2. Stop the Keyfactor Universal Orchestrator Service for the orchestrator you plan to install this extension to run on. -3. In the Keyfactor Orchestrator installation folder (by convention usually C:\Program Files\Keyfactor\Keyfactor Orchestrator), find the "Extensions" folder. Underneath that, create a new folder named "RemoteFile". You may choose to use a different name if you wish. -4. Download the latest version of the RemoteFile orchestrator extension from [GitHub](https://github.com/Keyfactor/remote-file-orchestrator). Click on the "Latest" release link on the right hand side of the main page and download the first zip file. -5. Copy the contents of the download installation zip file to the folder created in Step 3. -6. (Optional) If you decide to create one or more certificate store types with short names different than the suggested values (please see the individual certificate store type sections in "Certificate Store Types" later in this README for more information regarding certificate store types), edit the manifest.json file in the folder you created in step 3, and modify each "ShortName" in each "Certstores.{ShortName}.{Operation}" line with the ShortName you used to create the respective certificate store type. If you created it with the suggested values, this step can be skipped. -7. Modify the config.json file (See the "Configuration File Setup" section later in this README) -8. Start the Keyfactor Universal Orchestrator Service. -  -  +1. Review the [Prerequisites and Security Considerations](#prerequisites-and-security-considerations) section and make sure your environment is set up as required. +2. Refer to the [Creating Certificate Store Types](#creating-certificate-store-types) section to create the certificate store types you wish to manage. +3. Stop the Keyfactor Universal Orchestrator Service on the server you plan to install this extension to run on. +4. In the Keyfactor Orchestrator installation folder (by convention usually C:\Program Files\Keyfactor\Keyfactor Orchestrator for a Windows install or /opt/keyfactor/orchestrator/ for a Linux install), find the "Extensions" folder. Underneath that, create a new folder named "RemoteFile". You may choose to use a different name if you wish. +5. Download the latest version of the RemoteFile orchestrator extension from [GitHub](https://github.com/Keyfactor/remote-file-orchestrator). Click on the "Latest" release link on the right hand side of the main page and download the first zip file. +6. Copy the contents of the download installation zip file to the folder created in step 4. +7. (Optional) If you decide to create one or more certificate store types with short names different than the suggested values, edit the manifest.json file in the folder you created in step 4, and modify each "ShortName" in each "Certstores.{ShortName}.{Operation}" line with the ShortName you used to create the respective certificate store type. +8. Modify the config.json file to use the settings you desire. Please go to [Configuration File Setup](#configuration-file-setup) to learn more. +9. Start the Keyfactor Universal Orchestrator Service. + + + +  ## Configuration File Setup The Remote File Orchestrator Extension uses a JSON configuration file. It is located in the {Keyfactor Orchestrator Installation Folder}\Extensions\RemoteFile. None of the values are required, and a description of each follows below: @@ -178,227 +262,341 @@ The Remote File Orchestrator Extension uses a JSON configuration file. It is lo "DefaultOwnerOnStoreCreation": "" } -**UseSudo** (Applicable for Linux orchestrated servers only) - Y/N - Determines whether to prefix certain Linux command with "sudo". This can be very helpful in ensuring that the user id running commands over an ssh connection 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 Windows orchestrated servers, this setting has no effect. Setting this value to "N" will result in "sudo" not being added to Linux commands. -**DefaultSudoImpersonatedUser** (Applicable for Linux orchestrated servers only) - Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is set to an empty string, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see later in this section) as well as permissions to execute the commands listed in the "Security Considerations" section above. This value will be used for all certificate stores managed by this orchestrator extension implementation UNLESS overriden by the SudoImpersonatedUser certificate store type custom field setting described later in the Certificate Store Types section. -**CreateStoreOnAddIfMissing** - Y/N - Determines, during a Management-Add job, if a certificate store should be created if it does not already exist. If set to "N", and the store referenced in the Management-Add job is not found, the job will return an error with a message stating that the store does not exist. If set to "Y", the store will be created and the certificate added to the certificate store. **Default value if missing - N**. -**UseNegotiateAuth** (Applicable for Windows orchestrated servers only) – Y/N - Determines if WinRM should use Negotiate (Y) when connecting to the remote server. **Default Value if missing - N**. -**SeparateUploadFilePath**(Applicable for Linux managed servers only) – Set this to the path you wish to use as the location on the orchestrated server to upload/download and later remove temporary work files when processing jobs. If set to "" or not provided, the location of the certificate store itself will be used. File transfer itself is performed using SCP or SFTP protocols (see FileT ransferProtocol setting). **Default Value if missing - blank**. -**FileTransferProtocol** (Applicable for Linux orchestrated servers only) - SCP/SFTP/Both - Determines the protocol to use when uploading/downloading files while processing a job. Valid values are: SCP - uses SCP, SFTP - uses SFTP, or Both - will attempt to use SCP first, and if that does not work, will attempt the file transfer via SFTP. **Default Value if missing - SCP**. -**DefaultLinuxPermissionsOnStoreCreation** (Applicable for Linux managed servers only) - 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 or a Management Add job where CreateStoreOnAddIsMissing is set to "Y". 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 (See the "Certificatee Store Types Supported" section later in this README). **Default Value if missing - 600**. -**DefaultOwnerOnStoreCreation** (Applicable for Linux managed servers only) - When a Management job is run to remotely create the physical certificate store on a remote server, by default the file owner and group will be set to the user name associated with the Keyfactor certificate store. Setting DefaultOwnerOnStoreCreation to an alternative valid Linux user name will set that as the owner/group instead. If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please make sure that the user associated with the certificate store will have valid permissions to chown the certificate store file to this alernative owner. The optional "Linux File Owner on Store Creation" custom parameter setting for a specific certificate store (See the "Certificatee Store Types Supported" section later in this README) can override this value for a specific store. **Default Value if missing - blank**. -  -  -## Certificate Store Types - -When setting up the certificate store types you wish the Remote File Orchestrator Extension to manage, there are some common settings that will be the same for all supported types. To create a new Certificate Store Type in Keyfactor Command, first click on settings (the gear icon on the top right) => Certificate Store Types => Add. Alternatively, there are CURL scripts for all of the currently implemented certificate store types in the Certificate Store Type CURL Scripts folder in this repo if you wish to automate the creation of the desired store types. - -**Common Values:** -*Basic Tab:* -- **Name** – Required. The display name you wish to use for the new Certificate Store Type. -- **ShortName** - Required. See specific certificate store type instructions below. -- **Custom Capability** - Unchecked -- **Supported Job Types** - Inventory, Add, Remove, Create, and Discovery should all be checked. -- **Needs Server** - Checked -- **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. -- **Uses PowerShell** - Unchecked -- **Requires Store Password** - Checked. NOTE: This does not require that a certificate store have a password, but merely ensures that a user who creates a Keyfactor Command Certificate Store MUST click the Store Password button and either enter a password or check No Password. Certificate stores with no passwords are still possible for certain certificate store types when checking this option. -- **Supports Entry Password** - Unchecked. - -*Advanced Tab:* -- **Store Path Type** - Freeform -- **Supports Custom Alias** - See specific certificate store type instructions below. -- **Private Key Handling** - See specific certificate store type instructions below -- **PFX Password Style** - Default - -*Custom Fields Tab:* -- **Name:** LinuxFilePermissionsOnStoreCreation, **Display Name:** Linux File Permissions on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultLinuxPermissionsOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, must be 3 digits all between 0-7. This represents the Linux file permissions that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". -- **Name:** LinuxFileOwnerOnStoreCreation, **Display Name:** Linux File Owner on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultOwnerOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, represents the alternate Linux file owner/group that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please confirm that the user name associated with this Keyfactor certificate store has valid permissions to chown the certificate file to this owner. -- **Name:** SudoImpersonatedUser, **Display Name:** Sudo Impersonated User Id, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultSudoImpersonatedUser setting in config.json (see Configuration File Setup section above). Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is empty, and nothing is set for DefaultSudoImpersonatedUser in your config.json, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see Configuration File Setup section above) as well as permissions to execute the commands listed in the "Security Considerations" section above. - -Entry Parameters Tab: -- See specific certificate store type instructions below +
+UseSudo (Applicable for Linux hosted certificate stores only) -  -  -************************************** -**RFPkcs12 Certificate Store Type** -************************************** +* Determines whether to prefix Linux command with "sudo". This can be very helpful in ensuring that the user id running commands over an ssh connection 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. Setting this value to "N" will result in "sudo" not being added to Linux commands. +* Allowed values - Y/N +* Default value - N -The RFPkcs12 store type can be used to manage any PKCS#12 compliant file format INCLUDING java keystores of type PKCS12. +
-Use cases supported: -1. One-to-many trust entries - A single certificate without a private key in a certificate store. Each certificate identified with a custom alias or certificate thumbprint. -2. One-to-many key entries - One-to-many certificates with private keys and optionally the full certificate chain. Each certificate identified with a custom alias or certificate thumbprint. -3. A mix of trust and key entries. +
+DefaultSudoImpersonatedUser (Applicable for Linux hosted certificate stores only) -**Specific Certificate Store Type Values** -*Basic Tab:* -- **Short Name** – Required. Suggested value - **RFPkcs12**. If you choose to use a different value you must make the corresponding modification to the manifest.json file (see "Remote File Orchestrator Extension Installation", step 6 above). +* Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is set to an empty string, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see later in this section) as well as permissions to execute the commands listed in the "Prerequisites and Security Considerations" section above. This value will be used for all certificate stores managed by this orchestrator extension implementation UNLESS overriden by the SudoImpersonatedUser certificate store type custom field setting described later in the [Creating Certificate Store Types](#creating-certificate-store-types) section. +* Allowed values - Any valid user id that the destination Linux server will recognize +* Default value - blank (root will be used) -*Advanced Tab:* -- **Supports Custom Alias** - Required. -- **Private Key Handling** - Optional. +
-*Custom Fields Tab:* -- no adittional custom fields/parameters +
+CreateStoreOnAddIfMissing -Entry Parameters Tab: -- no additional entry parameters +* Determines, during a Management-Add job, if a certificate store should be created if it does not already exist. If set to "N", and the store referenced in the Management-Add job is not found, the job will return an error with a message stating that the store does not exist. If set to "Y", the store will be created and the certificate added to the certificate store. +* Allowed values - Y/N +* Default value - N -  -  -************************************** -**RFJKS Certificate Store Type** -************************************** +
-The RFJKS store type can be used to manage java keystores of type JKS. **PLEASE NOTE:** Java keystores of type PKCS12 **_cannot_** be managed by the RFJKS type. You **_must_** use RFPkcs12. +
+UseNegotiateAuth (Applicable for Windows hosted certificate stores only) -Use cases supported: -1. One-to-many trust entries - A single certificate without a private key in a certificate store. Each certificate identified with a custom alias or certificate thumbprint. -2. One-to-many key entries - One-to-many certificates with private keys and optionally the full certificate chain. Each certificate identified with a custom alias or certificate thumbprint. -3. A mix of trust and key entries. +* Determines if WinRM should use Negotiate (Y) when connecting to the remote server. +* Allowed values - Y/N +* Default value - N -**Specific Certificate Store Type Values** -*Basic Tab:* -- **Short Name** – Required. Suggested value - **RFJKS**. If you choose to use a different value you must make the corresponding modification to the manifest.json file (see "Remote File Orchestrator Extension Installation", step 6 above). +
-*Advanced Tab:* -- **Supports Custom Alias** - Required. -- **Private Key Handling** - Optional. +
+SeparateUploadFilePath (Applicable for Linux hosted certificate stores only) -*Custom Fields Tab:* -- no adittional custom fields/parameters +* Set this to the path you wish to use as the location on the orchestrated server to upload/download and later remove temporary work files when processing jobs. If set to "" or not provided, the location of the certificate store itself will be used. File transfer is performed using the SCP or SFTP protocols (see the File TransferProtocol setting). +* Allowed values - Any valid, existing Linux path configured to allow SCP/SFTP file upload/download tranfers. +* Default value - blank (actual store path will be used) -Entry Parameters Tab: -- no additional entry parameters +
-  -  -************************************** -**RFPEM Certificate Store Type** -************************************** +
+FileTransferProtocol (Applicable for Linux hosted certificate stores only) -The RFPEM store type can be used to manage PEM encoded files. +* Determines the protocol to use when uploading/downloading files while processing a job. +* Allowed values - SCP, SFTP or Both. If "Both" is entered, SCP will be attempted first, and if that does not work, SFTP will be tried. +* Default value - SCP. -Use cases supported: -1. Trust stores - A file with one-to-many certificates (no private keys, no certificate chains). -2. Single certificate stores with private key in the file. -3. Single certificate stores with certificate chain and private key in the file. -4. Single certificate stores with private key in an external file. -5. Single certificate stores with certificate chain in the file and private key in an external file +
-**Specific Certificate Store Type Values** -*Basic Tab:* -- **Short Name** – Required. Suggested value - **RFPEM**. If you choose to use a different value you must make the corresponding modification to the manifest.json file (see "Remote File Orchestrator Extension Installation", step 6 above). +
+DefaultLinuxPermissionsOnStoreCreation (Applicable for Linux hosted certificate stores only) -*Advanced Tab:* -- **Supports Custom Alias** - Forbidden. -- **Private Key Handling** - Optional. +* The Linux file permissions that will be set on a new certificate store created via a Management Create job or a Management Add job where CreateStoreOnAddIsMissing is set to "Y". 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. See the [Creating Certificate Store Types](#creating-certificate-store-types) section for more information on creating RemoteFile certificate store types. +* Allowed values - Any 3 digit value from 000-777. +* Default Value - 600. -*Custom Fields Tab:* -- **Name:** IsTrustStore, **Display Name:** Trust Store, **Type:** Bool, **Default Value:** false. This custom field is **not required**. Default value if not present is 'false'. If 'true', this store will be identified as a trust store. Any certificates attempting to be added via a Management-Add job that contain a private key will raise an error with an accompanying message. Multiple certificates may be added to the store in this use case. If set to 'false', this store can only contain a single certificate with chain and private key. Management-Add jobs attempting to add a certificate without a private key to a store marked as IsTrustStore = 'false' will raise an error with an accompanying message. -- **Name:** IncludesChain, **Display Name:** Store Includes Chain, **Type:** Bool, **Default Value:** false. This custom field is **not required**. Default value if not present is 'false'. If 'true' the full certificate chain, if sent by Keyfactor Command, will be stored in the file. The order of appearance is always assumed to be 1) end entity certificate, 2) issuing CA certificate, and 3) root certificate. If additional CA tiers are applicable, the order will be end entity certificate up to the root CA certificate. if set to 'false', only the end entity certificate and private key will be stored in this store. This setting is only valid when IsTrustStore = false. -- **Name:** SeparatePrivateKeyFilePath, **Display Name:** Separate Private Key File Location, **Type:** String, **Default Value:** empty. This custom field is **not required**. If empty, or not provided, it will be assumed that the private key for the certificate stored in this file will be inside the same file as the certificate. If the full path AND file name is put here, that location will be used to store the private key as an external file. This setting is only valid when IsTrustStore = false. -- **Name:** IsRSAPrivateKey, **Display Name:** Is RSA Private Key, **Type:** Bool, **Default Value:** false. This custom field is **not required**. Default value if not present is 'false'. If 'true' it will be assumed that the private key for the certificate is a PKCS#1 RSA formatted private key (BEGIN RSA PRIVATE KEY). If 'false' (default), encrypted/non-encrypted PKCS#8 (BEGIN [ENCRYPTED] PRIVATE KEY) is assumed If set to 'true' the store password **must** be set to "no password", as PKCS#1 does not support encrypted keys. This setting is only valid when IsTrustStore = false. -- **Name:** IgnorePrivateKeyOnInventory, **Display Name:** Ignore Private Key On Inventory, **Type:** Bool, **Default Value:** false. This custom field is **not required**. Default value if not present is 'false'. If 'true', inventory for this certificate store will be performed without accessing the certificate's private key or the store password. This will functionally make the store INVENTORY ONLY, as all certificates will be returned with "Private Key Entry" = false. Also, no certificate chain relationships will be maintained, and all certificates will be considered separate entries (basically a trust store). This may be useful in situations where the client does not know the store password at inventory run time, but would still like the certificates to be imported into Keyfactor Command. Once the correct store password is entered for the store, the client may de-select this option (change the value to False), schedule an inventory job, and then the appropriate private key entry and chain information should be properly stored in the Keyfactor Command location, allowing for renewal/removal of the certificate at a later time. +
-Entry Parameters Tab: -- no additional entry parameters +
+DefaultOwnerOnStoreCreation (Applicable for Linux hosted certificate stores only) + +* When a Management job is run to remotely create the physical certificate store on a remote server, by default the file owner and group will be set to the user name associated with the Keyfactor certificate store. Setting DefaultOwnerOnStoreCreation to an alternative valid Linux user name will set that as the owner/group instead. If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please make sure that the user associated with the certificate store will have valid permissions to chown the certificate store file to this alernative owner. The optional "Linux File Owner on Store Creation" custom parameter setting for a specific certificate store can override this value for a specific store. See the [Creating Certificate Store Types](#creating-certificate-store-types) section for more information on creating RemoteFile certificate store types. +* Allowed values - Any valid user id that the destination Linux server will recognize +* Default Value - blank (the ID associated with the Keyfactor certificate store will be used). + +
  -  -************************************** -**RFDER Certificate Store Type** -************************************** +## Creating Certificate Store Types -The RFDER store type can be used to manage DER encoded files. +Below are the various certificate store types that the RemoteFile Orchestator Extension manages. To create a new Certificate Store Type in Keyfactor Command, first click on settings (the gear icon on the top right) => Certificate Store Types => Add. Next, follow the incstructions under each store type you wish to set up. -Use cases supported: -1. Single certificate stores with private key in an external file. -5. Single certificate stores with no private key. +
+RFPkcs12 - Pkcs12 formatted certificate file (including java keystores of type PKCS12) -**Specific Certificate Store Type Values** -*Basic Tab:* -- **Short Name** – Required. Suggested value - **RFDER**. If you choose to use a different value you must make the corresponding modification to the manifest.json file (see "Remote File Orchestrator Extension Installation", step 6 above). +- Basic Tab: -*Advanced Tab:* -- **Supports Custom Alias** - Forbidden. -- **Private Key Handling** - Optional. + - **Name** – Required. The display name you wish to use for the new Certificate Store Type. + - **Short Name** – Required. Suggested value - **RFPkcs12**. If you choose to use a different value you must make the corresponding modification to the manifest.json file. See [Remote File Orchestrator Extension Installation](#remote-file-orchestrator-extension-installation), step 7 above. + - **Custom Capability** - Unchecked + - **Supported Job Types** - Inventory, Add, Remove, Create, and Discovery should all be checked. + - **Needs Server** - Checked + - **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. + - **Uses PowerShell** - Unchecked + - **Requires Store Password** - Checked. NOTE: This does not require that a certificate store have a password, but merely ensures that a user who creates a Keyfactor Command Certificate Store MUST click the Store Password button and either enter a password or check No Password. Certificate stores with no passwords are still possible for certain certificate store types when checking this option. + - **Supports Entry Password** - Unchecked. -*Custom Fields Tab:* -- **Name:** SeparatePrivateKeyFilePath, **Display Name:** Separate Private Key File Location, **Type:** String, **Default Value:** empty. This custom field is **not required**. If empty, or not provided, it will be assumed that there is no private key associated with this DER store. If the full path AND file name is entered here, that location will be used to store the private key as an external file in DER format. +- Advanced Tab: -Entry Parameters Tab: -- no additional entry parameters + - **Store Path Type** - Freeform + - **Supports Custom Alias** - Required. + - **Private Key Handling** - Optional. + - **PFX Password Style** - Default -  -  -************************************** -**RFKDB Certificate Store Type** -************************************** +- Custom Fields Tab: -The RFKDB store type can be used to manage IBM Key Database Files (KDB) files. The IBM utility, GSKCAPICMD, is used to read and write certificates from and to the target store and is therefore required to be installed on the server where each KDB certificate store being managed resides, and its location MUST be in the system $Path. + - **Name:** LinuxFilePermissionsOnStoreCreation, **Display Name:** Linux File Permissions on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultLinuxPermissionsOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, must be 3 digits all between 0-7. This represents the Linux file permissions that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". + - **Name:** LinuxFileOwnerOnStoreCreation, **Display Name:** Linux File Owner on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultOwnerOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, represents the alternate Linux file owner/group that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please confirm that the user name associated with this Keyfactor certificate store has valid permissions to chown the certificate file to this owner. + - **Name:** SudoImpersonatedUser, **Display Name:** Sudo Impersonated User Id, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultSudoImpersonatedUser setting in config.json (see Configuration File Setup section above). Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is empty, and nothing is set for DefaultSudoImpersonatedUser in your config.json, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see Configuration File Setup section above) as well as permissions to execute the commands listed in the "Security Considerations" section above. -Use cases supported: -1. One-to-many trust entries - A single certificate without a private key in a certificate store. Each certificate identified with a custom alias or certificate thumbprint. -2. One-to-many key entries - One-to-many certificates with private keys and optionally the full certificate chain. Each certificate identified with a custom alias or certificate thumbprint. -3. A mix of trust and key entries. +- Entry Parameters Tab: -**Specific Certificate Store Type Values** -*Basic Tab:* -- **Short Name** – Required. Suggested value - **RFKDB**. If you choose to use a different value you must make the corresponding modification to the manifest.json file (see "Remote File Orchestrator Extension Installation", step 6 above). + - no additional entry parameters -*Advanced Tab:* -- **Supports Custom Alias** - Required. -- **Private Key Handling** - Optional. +
-*Custom Fields Tab:* -- no adittional custom fields/parameters +
+RFJKS - Java keystore -Entry Parameters Tab: -- no additional entry parameters +- Basic Tab: -  -  -************************************** -**RFORA Certificate Store Type** -************************************** + - **Name** – Required. The display name you wish to use for the new Certificate Store Type. + - **Short Name** – Required. Suggested value - **RFJKS**. If you choose to use a different value you must make the corresponding modification to the manifest.json file. See [Remote File Orchestrator Extension Installation](#remote-file-orchestrator-extension-installation), step 7 above. + - **Custom Capability** - Unchecked + - **Supported Job Types** - Inventory, Add, Remove, Create, and Discovery should all be checked. + - **Needs Server** - Checked + - **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. + - **Uses PowerShell** - Unchecked + - **Requires Store Password** - Checked. NOTE: This does not require that a certificate store have a password, but merely ensures that a user who creates a Keyfactor Command Certificate Store MUST click the Store Password button and either enter a password or check No Password. Certificate stores with no passwords are still possible for certain certificate store types when checking this option. + - **Supports Entry Password** - Unchecked. -The RFORA store type can be used to manage Pkcs2 Oracle Wallets. Please note that while this should work for Pkcs12 Oracle Wallets installed on both Windows and Linux servers, this has only been tested on wallets installed on Windows. Please note, when entering the Store Path for an Oracle Wallet in Keyfactor Command, make sure to INCLUDE the eWallet.p12 file name that by convention is the name of the Pkcs12 wallet file that gets created. +- Advanced Tab: -Use cases supported: -1. One-to-many trust entries - A single certificate without a private key in a certificate store. Each certificate identified with a custom alias or certificate thumbprint. -2. One-to-many key entries - One-to-many certificates with private keys and optionally the full certificate chain. Each certificate identified with a custom alias or certificate thumbprint. -3. A mix of trust and key entries. + - **Store Path Type** - Freeform + - **Supports Custom Alias** - Required. + - **Private Key Handling** - Optional. + - **PFX Password Style** - Default -**Specific Certificate Store Type Values** -*Basic Tab:* -- **Short Name** – Required. Suggested value - **RFORA**. If you choose to use a different value you must make the corresponding modification to the manifest.json file (see "Remote File Orchestrator Extension Installation", step 6 above). +- Custom Fields Tab: + + - **Name:** LinuxFilePermissionsOnStoreCreation, **Display Name:** Linux File Permissions on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultLinuxPermissionsOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, must be 3 digits all between 0-7. This represents the Linux file permissions that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". + - **Name:** LinuxFileOwnerOnStoreCreation, **Display Name:** Linux File Owner on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultOwnerOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, represents the alternate Linux file owner/group that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please confirm that the user name associated with this Keyfactor certificate store has valid permissions to chown the certificate file to this owner. + - **Name:** SudoImpersonatedUser, **Display Name:** Sudo Impersonated User Id, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultSudoImpersonatedUser setting in config.json (see Configuration File Setup section above). Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is empty, and nothing is set for DefaultSudoImpersonatedUser in your config.json, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see Configuration File Setup section above) as well as permissions to execute the commands listed in the "Security Considerations" section above. -*Advanced Tab:* -- **Supports Custom Alias** - Required. -- **Private Key Handling** - Optional. +- Entry Parameters Tab: -*Custom Fields Tab:* -- **Name:** WorkFolder, **Display Name:** Work Folder, **Type:** String, **Default Value:** empty. This custom field is **required**. This required field should contain the path on the managed server where temporary work files can be created during Inventory and Management jobs. These files will be removed at the end of each job Please make sure that user id you have assigned to this certificate store will have access to create, modify, and delete files from this folder. + - no additional entry parameters -Entry Parameters Tab: -- no additional entry parameters +
+ +
+RFPEM - PEM formatted certificate file + +- Basic Tab: + + - **Name** – Required. The display name you wish to use for the new Certificate Store Type. + - **Short Name** – Required. Suggested value - **RFPEM**. If you choose to use a different value you must make the corresponding modification to the manifest.json file. See [Remote File Orchestrator Extension Installation](#remote-file-orchestrator-extension-installation), step 7 above. + - **Custom Capability** - Unchecked + - **Supported Job Types** - Inventory, Add, Remove, Create, and Discovery should all be checked. + - **Needs Server** - Checked + - **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. + - **Uses PowerShell** - Unchecked + - **Requires Store Password** - Checked. NOTE: This does not require that a certificate store have a password, but merely ensures that a user who creates a Keyfactor Command Certificate Store MUST click the Store Password button and either enter a password or check No Password. Certificate stores with no passwords are still possible for certain certificate store types when checking this option. + - **Supports Entry Password** - Unchecked. + +- Advanced Tab: + + - **Store Path Type** - Freeform + - **Supports Custom Alias** - Forbidden. + - **Private Key Handling** - Optional. + - **PFX Password Style** - Default + +- Custom Fields Tab: + + - **Name:** LinuxFilePermissionsOnStoreCreation, **Display Name:** Linux File Permissions on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultLinuxPermissionsOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, must be 3 digits all between 0-7. This represents the Linux file permissions that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". + - **Name:** LinuxFileOwnerOnStoreCreation, **Display Name:** Linux File Owner on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultOwnerOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, represents the alternate Linux file owner/group that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please confirm that the user name associated with this Keyfactor certificate store has valid permissions to chown the certificate file to this owner. + - **Name:** SudoImpersonatedUser, **Display Name:** Sudo Impersonated User Id, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultSudoImpersonatedUser setting in config.json (see Configuration File Setup section above). Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is empty, and nothing is set for DefaultSudoImpersonatedUser in your config.json, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see Configuration File Setup section above) as well as permissions to execute the commands listed in the "Security Considerations" section above. + - **Name:** IsTrustStore, **Display Name:** Trust Store, **Type:** Bool, **Default Value:** false. This custom field is **not required**. Default value if not present is 'false'. If 'true', this store will be identified as a trust store. Any certificates attempting to be added via a Management-Add job that contain a private key will raise an error with an accompanying message. Multiple certificates may be added to the store in this use case. If set to 'false', this store can only contain a single certificate with chain and private key. Management-Add jobs attempting to add a certificate without a private key to a store marked as IsTrustStore = 'false' will raise an error with an accompanying message. + - **Name:** IncludesChain, **Display Name:** Store Includes Chain, **Type:** Bool, **Default Value:** false. This custom field is **not required**. Default value if not present is 'false'. If 'true' the full certificate chain, if sent by Keyfactor Command, will be stored in the file. The order of appearance is always assumed to be 1) end entity certificate, 2) issuing CA certificate, and 3) root certificate. If additional CA tiers are applicable, the order will be end entity certificate up to the root CA certificate. if set to 'false', only the end entity certificate and private key will be stored in this store. This setting is only valid when IsTrustStore = false. + - **Name:** SeparatePrivateKeyFilePath, **Display Name:** Separate Private Key File Location, **Type:** String, **Default Value:** empty. This custom field is **not required**. If empty, or not provided, it will be assumed that the private key for the certificate stored in this file will be inside the same file as the certificate. If the full path AND file name is put here, that location will be used to store the private key as an external file. This setting is only valid when IsTrustStore = false. + - **Name:** IsRSAPrivateKey, **Display Name:** Is RSA Private Key, **Type:** Bool, **Default Value:** false. This custom field is **not required**. Default value if not present is 'false'. If 'true' it will be assumed that the private key for the certificate is a PKCS#1 RSA formatted private key (BEGIN RSA PRIVATE KEY). If 'false' (default), encrypted/non-encrypted PKCS#8 (BEGIN [ENCRYPTED] PRIVATE KEY) is assumed If set to 'true' the store password **must** be set to "no password", as PKCS#1 does not support encrypted keys. This setting is only valid when IsTrustStore = false. + - **Name:** IgnorePrivateKeyOnInventory, **Display Name:** Ignore Private Key On Inventory, **Type:** Bool, **Default Value:** false. This custom field is **not required**. Default value if not present is 'false'. If 'true', inventory for this certificate store will be performed without accessing the certificate's private key or the store password. This will functionally make the store INVENTORY ONLY, as all certificates will be returned with "Private Key Entry" = false. Also, no certificate chain relationships will be maintained, and all certificates will be considered separate entries (basically a trust store). This may be useful in situations where the client does not know the store password at inventory run time, but would still like the certificates to be imported into Keyfactor Command. Once the correct store password is entered for the store, the client may de-select this option (change the value to False), schedule an inventory job, and then the appropriate private key entry and chain information should be properly stored in the Keyfactor Command location, allowing for renewal/removal of the certificate at a later time. + +- Entry Parameters Tab: + + - no additional entry parameters + +
+ +
+RFDER - DER formatted certificate file + +- Basic Tab: + + - **Name** – Required. The display name you wish to use for the new Certificate Store Type. + - **Short Name** – Required. Suggested value - **RFDER**. If you choose to use a different value you must make the corresponding modification to the manifest.json file. See [Remote File Orchestrator Extension Installation](#remote-file-orchestrator-extension-installation), step 7 above. + - **Custom Capability** - Unchecked + - **Supported Job Types** - Inventory, Add, Remove, Create, and Discovery should all be checked. + - **Needs Server** - Checked + - **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. + - **Uses PowerShell** - Unchecked + - **Requires Store Password** - Checked. NOTE: This does not require that a certificate store have a password, but merely ensures that a user who creates a Keyfactor Command Certificate Store MUST click the Store Password button and either enter a password or check No Password. Certificate stores with no passwords are still possible for certain certificate store types when checking this option. + - **Supports Entry Password** - Unchecked. + +- Advanced Tab: + + - **Store Path Type** - Freeform + - **Supports Custom Alias** - Forbidden. + - **Private Key Handling** - Optional. + - **PFX Password Style** - Default + +- Custom Fields Tab: + + - **Name:** LinuxFilePermissionsOnStoreCreation, **Display Name:** Linux File Permissions on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultLinuxPermissionsOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, must be 3 digits all between 0-7. This represents the Linux file permissions that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". + - **Name:** LinuxFileOwnerOnStoreCreation, **Display Name:** Linux File Owner on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultOwnerOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, represents the alternate Linux file owner/group that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please confirm that the user name associated with this Keyfactor certificate store has valid permissions to chown the certificate file to this owner. + - **Name:** SudoImpersonatedUser, **Display Name:** Sudo Impersonated User Id, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultSudoImpersonatedUser setting in config.json (see Configuration File Setup section above). Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is empty, and nothing is set for DefaultSudoImpersonatedUser in your config.json, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see Configuration File Setup section above) as well as permissions to execute the commands listed in the "Security Considerations" section above. + - **Name:** SeparatePrivateKeyFilePath, **Display Name:** Separate Private Key File Location, **Type:** String, **Default Value:** empty. This custom field is **not required**. If empty, or not provided, it will be assumed that there is no private key associated with this DER store. If the full path AND file name is entered here, that location will be used to store the private key as an external file in DER format. + +- Entry Parameters Tab: + + - no additional entry parameters + +
+ +
+RFKDB - IBM Key Database File + +- Basic Tab: + + - **Name** – Required. The display name you wish to use for the new Certificate Store Type. + - **Short Name** – Required. Suggested value - **RFKDB**. If you choose to use a different value you must make the corresponding modification to the manifest.json file. See [Remote File Orchestrator Extension Installation](#remote-file-orchestrator-extension-installation), step 7 above. + - **Custom Capability** - Unchecked + - **Supported Job Types** - Inventory, Add, Remove, Create, and Discovery should all be checked. + - **Needs Server** - Checked + - **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. + - **Uses PowerShell** - Unchecked + - **Requires Store Password** - Checked. NOTE: This does not require that a certificate store have a password, but merely ensures that a user who creates a Keyfactor Command Certificate Store MUST click the Store Password button and either enter a password or check No Password. Certificate stores with no passwords are still possible for certain certificate store types when checking this option. + - **Supports Entry Password** - Unchecked. + +- Advanced Tab: + + - **Store Path Type** - Freeform + - **Supports Custom Alias** - Required. + - **Private Key Handling** - Optional. + - **PFX Password Style** - Default + +- Custom Fields Tab: + + - **Name:** LinuxFilePermissionsOnStoreCreation, **Display Name:** Linux File Permissions on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultLinuxPermissionsOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, must be 3 digits all between 0-7. This represents the Linux file permissions that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". + - **Name:** LinuxFileOwnerOnStoreCreation, **Display Name:** Linux File Owner on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultOwnerOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, represents the alternate Linux file owner/group that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please confirm that the user name associated with this Keyfactor certificate store has valid permissions to chown the certificate file to this owner. + - **Name:** SudoImpersonatedUser, **Display Name:** Sudo Impersonated User Id, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultSudoImpersonatedUser setting in config.json (see Configuration File Setup section above). Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is empty, and nothing is set for DefaultSudoImpersonatedUser in your config.json, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see Configuration File Setup section above) as well as permissions to execute the commands listed in the "Security Considerations" section above. + +- Entry Parameters Tab: + + - no additional entry parameters + +
+ +
+RFORA - Oracle Wallet + +- Basic Tab: + + - **Name** – Required. The display name you wish to use for the new Certificate Store Type. + - **Short Name** – Required. Suggested value - **RFORA**. If you choose to use a different value you must make the corresponding modification to the manifest.json file. See [Remote File Orchestrator Extension Installation](#remote-file-orchestrator-extension-installation), step 7 above. + - **Custom Capability** - Unchecked + - **Supported Job Types** - Inventory, Add, Remove, Create, and Discovery should all be checked. + - **Needs Server** - Checked + - **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. + - **Uses PowerShell** - Unchecked + - **Requires Store Password** - Checked. NOTE: This does not require that a certificate store have a password, but merely ensures that a user who creates a Keyfactor Command Certificate Store MUST click the Store Password button and either enter a password or check No Password. Certificate stores with no passwords are still possible for certain certificate store types when checking this option. + - **Supports Entry Password** - Unchecked. + +- Advanced Tab: + + - **Store Path Type** - Freeform + - **Supports Custom Alias** - Required. + - **Private Key Handling** - Optional. + - **PFX Password Style** - Default + +- Custom Fields Tab: + + - **Name:** LinuxFilePermissionsOnStoreCreation, **Display Name:** Linux File Permissions on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultLinuxPermissionsOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, must be 3 digits all between 0-7. This represents the Linux file permissions that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". + - **Name:** LinuxFileOwnerOnStoreCreation, **Display Name:** Linux File Owner on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultOwnerOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, represents the alternate Linux file owner/group that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please confirm that the user name associated with this Keyfactor certificate store has valid permissions to chown the certificate file to this owner. + - **Name:** SudoImpersonatedUser, **Display Name:** Sudo Impersonated User Id, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultSudoImpersonatedUser setting in config.json (see Configuration File Setup section above). Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is empty, and nothing is set for DefaultSudoImpersonatedUser in your config.json, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see Configuration File Setup section above) as well as permissions to execute the commands listed in the "Security Considerations" section above. + - **Name:** WorkFolder, **Display Name:** Work Folder, **Type:** String, **Default Value:** empty. This custom field is **required**. This required field should contain the path on the managed server where temporary work files can be created during Inventory and Management jobs. These files will be removed at the end of each job Please make sure that user id you have assigned to this certificate store will have access to create, modify, and delete files from this folder. + +- Entry Parameters Tab: + + - no additional entry parameters + +
  -  -## Creating Certificate Stores and Scheduling Discovery Jobs +## Certificate Stores and Discovery Jobs + +When creating new certificate stores or scheduling discovery jobs in Keyfactor Command, there are a few fields that are important to highlight here: + +
+Client Machine (certificate stores and discovery jobs) + +For Linux orchestrated servers, "Client Machine" should be the DNS name or IP address of the remote orchestrated server, while for Windows orchestratred servers, it should be the following URL format: protocol://dns-or-ip:port, where +* protocol is http or https, whatever your WinRM configuration uses +* dns-or-ip is the DNS name or IP address of the server +* port is the port WinRM is running under, usually 5985 for http and 5986 for https. + +Example: https://myserver.mydomain.com:5986 + +If running as an agent (accessing stores on the server where the Universal Orchestrator Services is installed ONLY), Client Machine can be entered as stated above, OR you can bypass SSH/WinRM and access the local file system directly by adding "|LocalMachine" to the end of your value for Client Machine, for example "1.1.1.1|LocalMachine". In this instance the value to the left of the pipe (|) is ignored. It is important to make sure the values for Client Machine and Store Path together are unique for each certificate store created, as Keyfactor Command requires the Store Type you select, along with Client Machine, and Store Path together must be unique. To ensure this, it is good practice to put the full DNS or IP Address to the left of the | character when setting up a cerificate store that will accessed without a WinRM/SSH connection. + +
-Please refer to the Keyfactor Command Reference Guide for information on creating certificate stores and scheduling Discovery jobs in Keyfactor Command. However, there are a few fields that are important to highlight here - Client Machine, Store Path (Creating Certificate Stores), and Directories to search (Discovery jobs) and Extensions (Discovery jobs). For Linux orchestrated servers, "Client Machine" should be the DNS or IP address of the remote orchestrated server while "Store Path" is the full path and file name of the file based store, beginning with a forward slash (/). For Windows orchestrated servers, "Client Machine" should be of the format {protocol}://{dns-or-ip}:{port} where {protocol} is either http or https, {dns-or-ip} is the DNS or IP address of the remote orchestrated server, and {port} is the port where WinRM is listening, by convention usually 5985 for http and 5986 for https. Alternately, entering the keyword "localhost" for "Client Machine" will point to the server where the orchestrator service is installed and WinRM WILL NOT be required. "Store Path" is the full path and file name of the file based store, beginning with a drive letter (i.e. c:\). For example valid values for Client Machine and Store Path for Linux and Windows managed servers may look something like: +
+Store Path (certificate stores only) -Linux: Client Machine - 127.0.0.1 or MyLinuxServerName; Store Path - /home/folder/path/storename.ext -Windows: Client Machine - https://My.Server.Domain:5986; Store Path - c:\folder\path\storename.ext +For Linux orchestrated servers, "StorePath" will begin with a forward slash (/) and contain the full path and file name, including file extension if one exists (i.e. /folder/path/storename.ext). For Windows orchestrated servers, it should be the full path and file name, including file extension if one exists, beginning with a drive letter (i.e. c:\folder\path\storename.ext). -Credentials **must** be entered: a user id and either a password or valid PAM key if the password is stored in a KF Command configured PAM integration. Alternatively, this password can be an SSH private key if connecting to a Linux server using SSH private key authentication. +
-For "Directories to search", you can chain paths with a comma delimiter as documented in the Keyfactor Command Reference Guide, but there is also a special value that can be used instead - fullscan. Entering fullscan in this field will tell the RemoteFile discovery job to search all available drive letters and recursively search all of them for files matching the other search criteria. +
+Server Username/Password (certificate stores and discovery jobs) -For "Extensions", a reserved value of noext will cause the RemoteFile discovery job to search for files that do not have an extension. This value can be chained with other extensions using a comma delimiter. For example, entering pem,jks,noext will cause the RemoteFile discovery job to search for files with extensions of PEM or JKS or files that do not have extensions. +A username and password (or valid PAM key if the username and/or password is stored in a KF Command configured PAM integration). The password can be an SSH private key if connecting via SSH to a server using SSH private key authentication. If acting as an *agent* using local file access, just check "No Value" for the username and password. + +
+
+Directories to Search (discovery jobs only) + +Enter one or more comma delimitted file paths to search (please reference the Keyfactor Command Reference Guide for more information), but there is also a special value that can be used on Windows orchestrated servers instead - "fullscan". Entering fullscan in this field will tell the RemoteFile discovery job to search all available drive letters at the root and recursively search all of them for files matching the other search criteria. + +
+ +
+Extensions (discovery jobs only) + +In addition to entering one or more comma delimitted extensions to search for (please reference the Keyfactor Command Reference Guide for more information), a reserved value of "noext" can be used that will cause the RemoteFile discovery job to search for files that do not have an extension. This value can be chained with other extensions using the comma delimiter. For example, entering pem,jks,noext will cause the RemoteFile discovery job to return file locations with extensions of "pem", "jks", *and* files that do not have extensions. + +
+ +Please refer to the Keyfactor Command Reference Guide for complete information on creating certificate stores and scheduling discovery jobs in Keyfactor Command.     ## Developer Notes @@ -420,10 +618,13 @@ Steps to create a new supported file based certificate store type: 8. After compiling, move all compiled files, including the config.json and manifest.json to {Keyfactor Orchestrator Installation Folder}\Extensions\RemoteFile. 9. Create the certificate store type in Keyfactor Command 10. Add a new CURL script to build the proper Keyfactor Command certificate store type and place it under "Certificate Store Type CURL Scripts". The name of the file should match the ShortName you are using for the new store type. -11. Update the documenation in readme_source.md by adding a new section under "Certificate Store Types" for this new supported file based store type. Include a pointer to the CURL script created in step 10. +11. Update the documenation in readme_source.md by adding a new section under [Creating Certificate Store Types](#creating-certificate-store-types) for this new supported file based store type. Include a pointer to the CURL script created in step 10.     ## License [Apache](https://apache.org/licenses/LICENSE-2.0) +When creating cert store type manually, that store property names and entry parameter names are case sensitive + + diff --git a/RemoteFile/ManagementBase.cs b/RemoteFile/ManagementBase.cs index 5bb1d432..a6c213c7 100644 --- a/RemoteFile/ManagementBase.cs +++ b/RemoteFile/ManagementBase.cs @@ -64,7 +64,7 @@ public JobResult ProcessJob(ManagementJobConfiguration config) switch (config.OperationType) { case CertStoreOperationType.Add: - logger.LogDebug($"BEGIN create Operation for {config.CertificateStoreDetails.StorePath} on {config.CertificateStoreDetails.ClientMachine}."); + logger.LogDebug($"BEGIN add Operation for {config.CertificateStoreDetails.StorePath} on {config.CertificateStoreDetails.ClientMachine}."); if (!certificateStore.DoesStoreExist()) { if (ApplicationSettings.CreateStoreIfMissing) @@ -76,7 +76,7 @@ public JobResult ProcessJob(ManagementJobConfiguration config) certificateStore.AddCertificate((config.JobCertificate.Alias ?? new X509Certificate2(Convert.FromBase64String(config.JobCertificate.Contents), config.JobCertificate.PrivateKeyPassword).Thumbprint), config.JobCertificate.Contents, config.Overwrite, config.JobCertificate.PrivateKeyPassword); certificateStore.SaveCertificateStore(certificateStoreSerializer.SerializeRemoteCertificateStore(certificateStore.GetCertificateStore(), storePathFile.Path, storePathFile.File, storePassword, certificateStore.RemoteHandler)); - logger.LogDebug($"END create Operation for {config.CertificateStoreDetails.StorePath} on {config.CertificateStoreDetails.ClientMachine}."); + logger.LogDebug($"END add Operation for {config.CertificateStoreDetails.StorePath} on {config.CertificateStoreDetails.ClientMachine}."); break; case CertStoreOperationType.Remove: diff --git a/RemoteFile/RemoteCertificateStore.cs b/RemoteFile/RemoteCertificateStore.cs index cf5a7995..3e23edd6 100644 --- a/RemoteFile/RemoteCertificateStore.cs +++ b/RemoteFile/RemoteCertificateStore.cs @@ -12,7 +12,6 @@ using System.Security.Cryptography.X509Certificates; using System.Text; using System.Text.RegularExpressions; -using System.Threading; using Microsoft.Extensions.Logging; @@ -22,7 +21,7 @@ using Keyfactor.Extensions.Orchestrator.RemoteFile.RemoteHandlers; using Keyfactor.Extensions.Orchestrator.RemoteFile.Models; using Keyfactor.Logging; -using System.Management.Automation; +using System.Runtime.InteropServices; namespace Keyfactor.Extensions.Orchestrator.RemoteFile { @@ -30,6 +29,7 @@ internal class RemoteCertificateStore { private const string NO_EXTENSION = "noext"; private const string FULL_SCAN = "fullscan"; + private const string LOCAL_MACHINE_SUFFIX = "|localmachine"; internal enum ServerTypeEnum { @@ -340,10 +340,12 @@ internal void Initialize(string sudoImpersonatedUser) { logger.MethodEntry(LogLevel.Debug); - if (ServerType == ServerTypeEnum.Linux) - RemoteHandler = new SSHHandler(Server, ServerId, ServerPassword, sudoImpersonatedUser); + bool treatAsLocal = Server.ToLower().EndsWith(LOCAL_MACHINE_SUFFIX); + + if (ServerType == ServerTypeEnum.Linux || RuntimeInformation.IsOSPlatform(OSPlatform.Linux)) + RemoteHandler = treatAsLocal ? new LinuxLocalHandler() as IRemoteHandler : new SSHHandler(Server, ServerId, ServerPassword, ServerType == ServerTypeEnum.Linux, sudoImpersonatedUser) as IRemoteHandler; else - RemoteHandler = new WinRMHandler(Server, ServerId, ServerPassword); + RemoteHandler = new WinRMHandler(Server, ServerId, ServerPassword, treatAsLocal); RemoteHandler.Initialize(); @@ -389,10 +391,10 @@ private List FindStoresLinux(string[] paths, string[] extensions, string { foreach (string fileName in fileNames) { - command += (command.IndexOf("-iname") == -1 ? string.Empty : "-or "); - command += $"-iname '{fileName.Trim()}"; + command += (command.IndexOf("-name") == -1 ? string.Empty : "-or "); + command += $"-name '{fileName.Trim()}"; if (extension.ToLower() == NO_EXTENSION) - command += $"' ! -iname '*.*' "; + command += $"' ! -name '*.*' "; else command += $".{extension.Trim()}' "; } diff --git a/RemoteFile/RemoteFile.csproj b/RemoteFile/RemoteFile.csproj index e0f8735d..1ee2cf4e 100644 --- a/RemoteFile/RemoteFile.csproj +++ b/RemoteFile/RemoteFile.csproj @@ -2,10 +2,18 @@ false - netcoreapp3.1 + net6.0 true + + none + + + + none + + @@ -13,11 +21,11 @@ + - - + diff --git a/RemoteFile/RemoteHandlers/BaseRemoteHandler.cs b/RemoteFile/RemoteHandlers/BaseRemoteHandler.cs index f0d30896..179e929d 100644 --- a/RemoteFile/RemoteHandlers/BaseRemoteHandler.cs +++ b/RemoteFile/RemoteHandlers/BaseRemoteHandler.cs @@ -8,6 +8,7 @@ using Keyfactor.Logging; using Microsoft.Extensions.Logging; +using System.Text.RegularExpressions; namespace Keyfactor.Extensions.Orchestrator.RemoteFile.RemoteHandlers { @@ -16,6 +17,7 @@ abstract class BaseRemoteHandler : IRemoteHandler internal ILogger _logger; internal const string PASSWORD_MASK_VALUE = "[PASSWORD]"; internal const int PASSWORD_LENGTH_MAX = 100; + internal const string LINUX_PERMISSION_REGEXP = "^[0-7]{3}$"; public string Server { get; set; } @@ -24,6 +26,13 @@ public BaseRemoteHandler() _logger = LogHandler.GetClassLogger(this.GetType()); } + public static void AreLinuxPermissionsValid(string permissions) + { + Regex regex = new Regex(LINUX_PERMISSION_REGEXP); + if (!regex.IsMatch(permissions)) + throw new RemoteFileException($"Invalid format for Linux file permissions. This value must be exactly 3 digits long with each digit between 0-7 but found {permissions} instead."); + } + public abstract void Initialize(); public abstract void Terminate(); diff --git a/RemoteFile/RemoteHandlers/LinuxLocalHandler.cs b/RemoteFile/RemoteHandlers/LinuxLocalHandler.cs new file mode 100644 index 00000000..8195ad44 --- /dev/null +++ b/RemoteFile/RemoteHandlers/LinuxLocalHandler.cs @@ -0,0 +1,166 @@ +// Copyright 2021 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.IO; +using System.Security.Cryptography; + +using CliWrap; +using CliWrap.Buffered; + +using Renci.SshNet; + +using Microsoft.Extensions.Logging; + +using Keyfactor.Logging; +using Keyfactor.PKI.PrivateKeys; +using Keyfactor.PKI.PEM; + +namespace Keyfactor.Extensions.Orchestrator.RemoteFile.RemoteHandlers +{ + class LinuxLocalHandler : BaseRemoteHandler + { + private Command BaseCommand { get; set; } + + internal LinuxLocalHandler() + { + _logger.MethodEntry(LogLevel.Debug); + _logger.MethodExit(LogLevel.Debug); + } + + public override void Initialize() + { + _logger.MethodEntry(LogLevel.Debug); + + BaseCommand = Cli.Wrap("/bin/bash"); + + _logger.MethodExit(LogLevel.Debug); + } + + public override void Terminate() + { + _logger.MethodEntry(LogLevel.Debug); + _logger.MethodExit(LogLevel.Debug); + } + + public override string RunCommand(string commandText, object[] arguments, bool withSudo, string[] passwordsToMaskInLog) + { + _logger.MethodEntry(LogLevel.Debug); + + string sudo = $"echo -e \\n | sudo -S "; + + try + { + if (withSudo) + commandText = sudo + commandText; + + string displayCommand = commandText; + if (passwordsToMaskInLog != null) + { + foreach (string password in passwordsToMaskInLog) + displayCommand = displayCommand.Replace(password, PASSWORD_MASK_VALUE); + } + + _logger.LogDebug($"RunCommand: {displayCommand}"); + + Command cmd = BaseCommand.WithArguments($@"-c ""{commandText}"""); + BufferedCommandResult result = cmd.ExecuteBufferedAsync().GetAwaiter().GetResult(); + + _logger.LogDebug($"Linux Local Results: {displayCommand}::: {result.StandardOutput}::: {result.StandardError}"); + + if (!String.IsNullOrEmpty(result.StandardError)) + throw new ApplicationException(result.StandardError); + + _logger.MethodExit(LogLevel.Debug); + + return result.StandardOutput; + } + catch (Exception ex) + { + _logger.LogError($"Exception during RunCommand...{RemoteFileException.FlattenExceptionMessages(ex, ex.Message)}"); + throw ex; + } + } + + public override void UploadCertificateFile(string path, string fileName, byte[] certBytes) + { + _logger.MethodEntry(LogLevel.Debug); + _logger.LogDebug($"UploadCertificateFile: {path}{fileName}"); + + string uploadPath = path+fileName; + + try + { + File.WriteAllBytes(uploadPath, certBytes); + } + catch (Exception ex) + { + _logger.LogError($"Error attempting upload file to {uploadPath}..."); + _logger.LogError($"Upload Exception: {RemoteFileException.FlattenExceptionMessages(ex, ex.Message)}"); + throw new RemoteFileException($"Error attempting upload file to {uploadPath}.", ex); + } + + _logger.MethodExit(LogLevel.Debug); + } + + public override byte[] DownloadCertificateFile(string path) + { + _logger.MethodEntry(LogLevel.Debug); + _logger.LogDebug($"DownloadCertificateFile: {path}"); + + byte[] rtnStore = new byte[] { }; + + try + { + rtnStore = File.ReadAllBytes(path); + } + catch (Exception ex) + { + _logger.LogError($"Error attempting download file {path}..."); + _logger.LogError($"Download Exception: {RemoteFileException.FlattenExceptionMessages(ex, ex.Message)}"); + throw new RemoteFileException($"Error attempting download file {path}.", ex); + } + + _logger.MethodExit(LogLevel.Debug); + + return rtnStore; + } + + public override void CreateEmptyStoreFile(string path, string linuxFilePermissions, string linuxFileOwner) + { + _logger.MethodEntry(LogLevel.Debug); + string[] linuxGroupOwner = linuxFileOwner.Split(":"); + string linuxFileGroup = linuxFileOwner; + + if (linuxGroupOwner.Length == 2) + { + linuxFileOwner = linuxGroupOwner[0]; + linuxFileGroup = linuxGroupOwner[1]; + } + + AreLinuxPermissionsValid(linuxFilePermissions); + RunCommand($"install -m {linuxFilePermissions} -o {linuxFileOwner} -g {linuxFileGroup} /dev/null {path}", null, ApplicationSettings.UseSudo, null); + + _logger.MethodExit(LogLevel.Debug); + } + + public override bool DoesFileExist(string path) + { + _logger.MethodEntry(LogLevel.Debug); + _logger.LogDebug($"DoesFileExist: {path}"); + + return File.Exists(path); + } + + public override void RemoveCertificateFile(string path, string fileName) + { + _logger.LogDebug($"RemoveCertificateFile: {path} {fileName}"); + + RunCommand($"rm {path}{fileName}", null, ApplicationSettings.UseSudo, null); + } + } +} diff --git a/RemoteFile/RemoteHandlers/SSHHandler.cs b/RemoteFile/RemoteHandlers/SSHHandler.cs index 55a9578b..64668815 100644 --- a/RemoteFile/RemoteHandlers/SSHHandler.cs +++ b/RemoteFile/RemoteHandlers/SSHHandler.cs @@ -9,7 +9,6 @@ using System.Collections.Generic; using System.IO; using System.Security.Cryptography; -using System.Text.RegularExpressions; using System.Text; using Renci.SshNet; @@ -24,18 +23,18 @@ namespace Keyfactor.Extensions.Orchestrator.RemoteFile.RemoteHandlers { class SSHHandler : BaseRemoteHandler { - private const string LINUX_PERMISSION_REGEXP = "^[0-7]{3}$"; private ConnectionInfo Connection { get; set; } private string SudoImpersonatedUser { get; set; } - + private bool IsStoreServerLinux { get; set; } private SshClient sshClient; - internal SSHHandler(string server, string serverLogin, string serverPassword, string sudoImpersonatedUser) + internal SSHHandler(string server, string serverLogin, string serverPassword, bool isStoreServerLinux, string sudoImpersonatedUser) { _logger.MethodEntry(LogLevel.Debug); Server = server; SudoImpersonatedUser = sudoImpersonatedUser; + IsStoreServerLinux = isStoreServerLinux; List authenticationMethods = new List(); if (serverPassword.Length < PASSWORD_LENGTH_MAX) @@ -65,7 +64,7 @@ internal SSHHandler(string server, string serverLogin, string serverPassword, st } Connection = new ConnectionInfo(server, serverLogin, authenticationMethods.ToArray()); - + _logger.MethodExit(LogLevel.Debug); } @@ -82,14 +81,14 @@ public override void Initialize() { throw new RemoteFileException($"Error making a SSH connection to remote server {Connection.Host}, for user {Connection.Username}. Please contact your company's system administrator to verify connection and permission settings.", ex); } - + _logger.MethodExit(LogLevel.Debug); } public override void Terminate() { _logger.MethodEntry(LogLevel.Debug); - + sshClient.Disconnect(); sshClient.Dispose(); @@ -99,14 +98,13 @@ public override void Terminate() public override string RunCommand(string commandText, object[] arguments, bool withSudo, string[] passwordsToMaskInLog) { _logger.MethodEntry(LogLevel.Debug); - _logger.LogDebug($"RunCommand: {commandText}"); string sudo = $"sudo -S "; string echo = $"echo -e '\n' | "; try { - if (withSudo) + if (withSudo && IsStoreServerLinux) { if (string.IsNullOrEmpty(SudoImpersonatedUser)) commandText = sudo + commandText; @@ -114,7 +112,15 @@ public override string RunCommand(string commandText, object[] arguments, bool w commandText = sudo + $"-u {SudoImpersonatedUser}" + " " + commandText; } - commandText = echo + commandText; + if (IsStoreServerLinux) + { + commandText = echo + commandText; + } + else + { + commandText = "powershell -Command \"" + commandText + "\""; + commandText = commandText.Replace(@"\", @"\\"); + } string displayCommand = commandText; if (passwordsToMaskInLog != null) @@ -151,9 +157,10 @@ public override void UploadCertificateFile(string path, string fileName, byte[] string uploadPath = path+fileName; - if (!string.IsNullOrEmpty(ApplicationSettings.SeparateUploadFilePath)) + if (!string.IsNullOrEmpty(ApplicationSettings.SeparateUploadFilePath) && IsStoreServerLinux) { uploadPath = ApplicationSettings.SeparateUploadFilePath + fileName; + _logger.LogDebug($"uploadPath: {uploadPath}"); } bool scpError = false; @@ -169,7 +176,7 @@ public override void UploadCertificateFile(string path, string fileName, byte[] using (MemoryStream stream = new MemoryStream(certBytes)) { - client.Upload(stream, FormatFTPPath(uploadPath)); + client.Upload(stream, FormatFTPPath(uploadPath, false)); } } catch (Exception ex) @@ -200,7 +207,7 @@ public override void UploadCertificateFile(string path, string fileName, byte[] using (MemoryStream stream = new MemoryStream(certBytes)) { - client.UploadFile(stream, FormatFTPPath(uploadPath)); + client.UploadFile(stream, FormatFTPPath(uploadPath, !IsStoreServerLinux)); } } catch (Exception ex) @@ -216,7 +223,7 @@ public override void UploadCertificateFile(string path, string fileName, byte[] } } - if (!string.IsNullOrEmpty(ApplicationSettings.SeparateUploadFilePath)) + if (!string.IsNullOrEmpty(ApplicationSettings.SeparateUploadFilePath) && IsStoreServerLinux) { RunCommand($"tee {path}/{fileName} < {uploadPath} > /dev/null", null, ApplicationSettings.UseSudo, null); RunCommand($"rm {uploadPath}", null, ApplicationSettings.UseSudo, null); @@ -236,7 +243,7 @@ public override byte[] DownloadCertificateFile(string path) string altPathOnly = string.Empty; string altFileNameOnly = string.Empty; - if (!string.IsNullOrEmpty(ApplicationSettings.SeparateUploadFilePath)) + if (!string.IsNullOrEmpty(ApplicationSettings.SeparateUploadFilePath) && IsStoreServerLinux) { SplitStorePathFile(path, out altPathOnly, out altFileNameOnly); downloadPath = ApplicationSettings.SeparateUploadFilePath + altFileNameOnly; @@ -258,7 +265,7 @@ public override byte[] DownloadCertificateFile(string path) using (MemoryStream stream = new MemoryStream()) { - client.Download(FormatFTPPath(downloadPath), stream); + client.Download(FormatFTPPath(downloadPath, false), stream); rtnStore = stream.ToArray(); } } @@ -290,7 +297,7 @@ public override byte[] DownloadCertificateFile(string path) using (MemoryStream stream = new MemoryStream()) { - client.DownloadFile(FormatFTPPath(downloadPath), stream); + client.DownloadFile(FormatFTPPath(downloadPath, !IsStoreServerLinux), stream); rtnStore = stream.ToArray(); } } @@ -307,7 +314,7 @@ public override byte[] DownloadCertificateFile(string path) } } - if (!string.IsNullOrEmpty(ApplicationSettings.SeparateUploadFilePath)) + if (!string.IsNullOrEmpty(ApplicationSettings.SeparateUploadFilePath) && IsStoreServerLinux) { RunCommand($"rm {downloadPath}", null, ApplicationSettings.UseSudo, null); } @@ -329,8 +336,13 @@ public override void CreateEmptyStoreFile(string path, string linuxFilePermissio linuxFileGroup = linuxGroupOwner[1]; } - AreLinuxPermissionsValid(linuxFilePermissions); - RunCommand($"install -m {linuxFilePermissions} -o {linuxFileOwner} -g {linuxFileGroup} /dev/null {path}", null, ApplicationSettings.UseSudo, null); + if (IsStoreServerLinux) + { + AreLinuxPermissionsValid(linuxFilePermissions); + RunCommand($"install -m {linuxFilePermissions} -o {linuxFileOwner} -g {linuxFileGroup} /dev/null {path}", null, ApplicationSettings.UseSudo, null); + } + else + RunCommand($@"Out-File -FilePath ""{path}""", null, false, null); _logger.MethodExit(LogLevel.Debug); } @@ -339,14 +351,15 @@ public override bool DoesFileExist(string path) { _logger.MethodEntry(LogLevel.Debug); _logger.LogDebug($"DoesFileExist: {path}"); - + using (SftpClient client = new SftpClient(Connection)) { try { client.Connect(); - string existsPath = FormatFTPPath(path); + string existsPath = FormatFTPPath(path, !IsStoreServerLinux); bool exists = client.Exists(existsPath); + _logger.LogDebug(existsPath); _logger.MethodExit(LogLevel.Debug); @@ -359,13 +372,6 @@ public override bool DoesFileExist(string path) } } - public static void AreLinuxPermissionsValid(string permissions) - { - Regex regex = new Regex(LINUX_PERMISSION_REGEXP); - if (!regex.IsMatch(permissions)) - throw new RemoteFileException($"Invalid format for Linux file permissions. This value must be exactly 3 digits long with each digit between 0-7 but found {permissions} instead."); - } - public override void RemoveCertificateFile(string path, string fileName) { _logger.LogDebug($"RemoveCertificateFile: {path} {fileName}"); @@ -413,12 +419,17 @@ private string ConvertToPKCS1(string privateKey) return pemString.Replace("PRIVATE", "RSA PRIVATE"); } - private string FormatFTPPath(string path) + private string FormatFTPPath(string path, bool addLeadingSlashForWindows) { _logger.MethodEntry(LogLevel.Debug); + + string rtnPath = IsStoreServerLinux ? path : path.Replace("\\", "/"); + rtnPath = addLeadingSlashForWindows ? "/" + rtnPath : rtnPath; + + _logger.LogTrace($"Formatted path: {rtnPath}"); _logger.MethodExit(LogLevel.Debug); - return path.Substring(0, 1) == @"/" ? path : @"/" + path.Replace("\\", "/"); + return rtnPath; } } } diff --git a/RemoteFile/RemoteHandlers/WinRMHandler.cs b/RemoteFile/RemoteHandlers/WinRMHandler.cs index c197f125..c8842837 100644 --- a/RemoteFile/RemoteHandlers/WinRMHandler.cs +++ b/RemoteFile/RemoteHandlers/WinRMHandler.cs @@ -8,7 +8,6 @@ using System; using System.Collections.Generic; using System.Management.Automation; -using System.Management.Automation.Remoting; using System.Management.Automation.Runspaces; using System.Net; using System.Text; @@ -26,13 +25,16 @@ class WinRMHandler : BaseRemoteHandler private Runspace runspace { get; set; } private WSManConnectionInfo connectionInfo { get; set; } + private bool RunLocal { get; set; } - internal WinRMHandler(string server, string serverLogin, string serverPassword) + internal WinRMHandler(string server, string serverLogin, string serverPassword, bool treatAsLocal) { _logger.MethodEntry(LogLevel.Debug); Server = server; - if (Server.ToLower() != "localhost") + RunLocal = Server.ToLower() == "localhost" || treatAsLocal; + + if (!RunLocal) { connectionInfo = new WSManConnectionInfo(new System.Uri($"{Server}/wsman")); if (!string.IsNullOrEmpty(serverLogin)) @@ -50,7 +52,7 @@ public override void Initialize() try { - if (Server.ToLower() == "localhost") + if (RunLocal) { runspace = RunspaceFactory.CreateRunspace(); } diff --git a/images/orchestrator-agent.png b/images/orchestrator-agent.png new file mode 100644 index 00000000..bdeaea4c Binary files /dev/null and b/images/orchestrator-agent.png differ diff --git a/readme_source.md b/readme_source.md index 452661dc..b77ef7da 100644 --- a/readme_source.md +++ b/readme_source.md @@ -1,34 +1,108 @@  ## Overview The Remote File Orchestrator Extension is a multi-purpose integration that can remotely manage a variety of file-based certificate stores and can easily be extended to manage others. The certificate store types that can be managed in the current version are: -- Java Keystores of type JKS -- PKCS12 files, including, but not limited to, Java keystores of type PKCS12 -- PEM formatted files -- DER formatted files -- IBM Key Database files (KDB) -- Oracle Wallet Pkcs12 files -While the Keyfactor Universal Orchestrator (UO) can be installed on either Windows or Linux; likewise, the Remote File Orchestrator Extension can be used to manage certificate stores residing on both Windows and Linux servers. The supported configurations of Universal Orchestrator hosts and managed orchestrated servers are shown below: +
+RFPkcs12 + +The RFPkcs12 store type can be used to manage any PKCS#12 compliant file format INCLUDING java keystores of type PKCS12. + +Use cases supported: +1. One-to-many trust entries - A trust entry is considered single certificate without a private key in a certificate store. Each trust entry is identified with a custom alias. +2. One-to-many key entries - One-to-many certificates with private keys and optionally the full certificate chain. Each certificate identified with a custom alias. +3. A mix of trust and key entries. + +
+ +
+RFJKS + +The RFJKS store type can be used to manage java keystores of type JKS. **PLEASE NOTE:** Java keystores of type PKCS12 **_cannot_** be managed by the RFJKS type. You **_must_** use RFPkcs12. + +Use cases supported: +1. One-to-many trust entries - A trust entry is considered single certificate without a private key in a certificate store. Each trust entry is identified with a custom alias. +2. One-to-many key entries - One-to-many certificates with private keys and optionally the full certificate chain. Each certificate identified with a custom alias. +3. A mix of trust and key entries. + +
+ +
+RFPEM + +The RFPEM store type can be used to manage PEM encoded files. + +Use cases supported: +1. Trust stores - A file with one-to-many certificates (no private keys, no certificate chains). +2. Single certificate stores with private key in the file. +3. Single certificate stores with certificate chain and private key in the file. +4. Single certificate stores with private key in an external file. +5. Single certificate stores with certificate chain in the file and private key in an external file + +NOTE: PEM stores may only have one private key (internal or external) associated with the store, as only one certificate/chain/private key combination can be stored in a PEM store supported by RFPEM. + +
+ +
+ +RFDER + +The RFDER store type can be used to manage DER encoded files. + +Use cases supported: +1. Single certificate stores with private key in an external file. +2. Single certificate stores with no private key. + +
+ +
+RFKDB + +The RFKDB store type can be used to manage IBM Key Database Files (KDB) files. The IBM utility, GSKCAPICMD, is used to read and write certificates from and to the target store and is therefore required to be installed on the server where each KDB certificate store being managed resides, and its location MUST be in the system $Path. + +Use cases supported: +1. One-to-many trust entries - A trust entry is considered single certificate without a private key in a certificate store. Each trust entry is identified with a custom alias. +2. One-to-many key entries - One-to-many certificates with private keys and optionally the full certificate chain. Each certificate identified with a custom alias. +3. A mix of trust and key entries. + +
+ +
+RFORA + +The RFORA store type can be used to manage Pkcs12 Oracle Wallets. Please note that while this should work for Pkcs12 Oracle Wallets installed on both Windows and Linux servers, this has only been tested on wallets installed on Windows. Please note, when entering the Store Path for an Oracle Wallet in Keyfactor Command, make sure to INCLUDE the eWallet.p12 file name that by convention is the name of the Pkcs12 wallet file that gets created. + +Use cases supported: +1. One-to-many trust entries - A trust entry is considered single certificate without a private key in a certificate store. Each trust entry is identified with a custom alias. +2. One-to-many key entries - One-to-many certificates with private keys and optionally the full certificate chain. Each certificate identified with a custom alias. +3. A mix of trust and key entries. + +
+ +The Keyfactor Univeral Orchestrator (UO) and RemoteFile Extension can be installed on either Windows or Linux operating systems as well as manage certificates residing on servers of both operating systems. A UO service managing certificates on remote servers is considered to be acting as an Orchestrator, while a UO service managing local certificates on the same server running the service is considered an Agent. When acting as an Orchestrator, connectivity from the orchestrator server hosting the RemoteFile extension to the orchestrated server hosting the certificate store(s) being managed is achieved via either an SSH (for Linux and possibly Windows orchestrated servers) or WinRM (for Windows orchestrated servers) connection. When acting as an agent, SSH/WinRM may still be used, OR the certificate store can be configured to bypass these and instead directly access the orchestrator server's file system. + +![](images/orchestrator-agent.png) + +Please review the [Prerequisites and Security Considerations](#prerequisites-and-security-considerations) and [Certificate Stores and Discovery Jobs](#certificate-stores-and-discovery-jobs) sections for more information on proper configuration and setup for these different architectures. The supported configurations of Universal Orchestrator hosts and managed orchestrated servers are detailed below: | | UO Installed on Windows | UO Installed on Linux | |-----|-----|------| -|Orchestrated Server on remote Windows server|✓ | | -|Orchestrated Server on remote Linux server|✓ |✓ | -|Orchestrated Server on same server as orchestrator service (Agent)|✓ |✓ | +|Orchestrated Server hosting certificate store(s) on remote Windows server|WinRM connection | SSH connection | +|Orchestrated Server hosting certificate store(s) on remote Linux server| SSH connection | SSH connection | +|Certificate store(s) on same server as orchestrator service (Agent)| WinRM connection or local file system | SSH connection or local file system | -This orchestrator extension makes use of an SSH connection to communicate remotely with certificate stores hosted on Linux servers and WinRM to communicate with certificate stores hosted on Windows servers. -  -  +  ## Versioning The version number of a the Remote File Orchestrator Extension can be verified by right clicking on the RemoteFile.dll file in the Extensions/RemoteFile installation folder, selecting Properties, and then clicking on the Details tab.     -## Security Considerations +## Prerequisites and Security Considerations -**For Linux orchestrated servers:** -1. The Remote File Orchestrator Extension makes use of a few common Linux commands when managing stores on Linux servers. If the credentials you will be connecting with need elevated access to run these commands or to access the certificate store files these commands operate against, you must set up the user id as a sudoer with no password necessary and set the config.json "UseSudo" value to "Y" (See "Config File Setup" later in this README for more information on setting up the config.json file). The full list of these commands below: +
+Certificate stores hosted on Linux servers: + +1. The Remote File Orchestrator Extension makes use of a few common Linux commands when managing stores on Linux servers. If the credentials you will be connecting with need elevated access to run these commands or to access the certificate store files these commands operate against, you must set up the user id as a sudoer with no password necessary and set the config.json "UseSudo" value to "Y". When RemoteFile is using orchestration, managing local or external certificate stores using SSH or WinRM, the security context is determined by the user id entered in the Keyfactor Command certificate store or discovery job screens. When RemoteFile is running as an agent, managing local stores only, the security context is the user id running the Keyfactor Command Universal Orchestrator service account. The full list of these commands below: |Shell Command|Used For| |---|---| @@ -40,29 +114,39 @@ The version number of a the Remote File Orchestrator Extension can be verified b |rm|Used by Inventory and Management Add/Remove jobs to remove temporary files (only when an alternate upload/download folder has been configured).| |install|Used by the Management Create Store job when initializing a certificate store file.| |orapki|Oracle Wallet CLI utility used by Inventory and Management Add/Remove jobs to manipulate an Oracle Wallet certificate store. Used for the RFORA store type only.| -|gskcapicmd|IBM Key Database CLI utility used by Inventory and Management Add/Remove jobs to manipulate an IBM Key Database certificate store. Used for the RFKDB store type only.| +|gskcapicmd|IBM Key Database CLI utility used by Inventory and Management Add/Remove jobs to manipulate an IBM Key Database certificate store. Used for the RFKDB store type only.| + +2. When orchestrating management of local or external certificate stores, the Remote File Orchestrator Extension makes use of SFTP and/or SCP to transfer files to and from the orchestrated server. SFTP/SCP cannot make use of sudo, so all folders containing certificate stores will need to allow SFTP/SCP file transfer for the user assigned to the certificate store/discovery job. If this is not possible, set the values in the config.json apprpriately to use an alternative upload/download folder that does allow SFTP/SCP file transfer. If the certificate store/discovery job is configured for local (agent) access, the account running the Keyfactor Universal Orchestrator service must have access to read/write to the certificate store location, OR the config.json file must be set up to use the alternative upload/download file. -2. The Remote File Orchestrator Extension makes use of SFTP and/or SCP to transfer files to and from the orchestrated server. SFTP/SCP cannot make use of sudo, so all folders containing certificate stores will need to allow SFTP/SCP file transfer. If this is not possible, set the values in the config.json apprpriately to use an alternative upload/download folder that does allow SFTP/SCP file transfer (See "Config File Setup" later in this README regarding the config.json file). +3. SSH Key Authentication: When creating a Keyfactor certificate store for the remote file orchestrator extension, you may supply either a user id and password for the certificate store credentials (directly or through one of Keyfactor Command's PAM integrations), or supply a user id and SSH private key. Both PKCS#1 (BEGIN RSA PRIVATE KEY) and PKCS#8 (BEGIN PRIVATE KEY) formats are supported for the SSH private key. If using the normal Keyfactor Command credentials dialog without PAM integration, just copy and paste the full SSH private key into the Password textbox. SSH Key Authentication is not available when running locally as an agent. -3. SSH Key Authentication: When creating a Keyfactor certificate store for the remote file orchestrator extension (see "Creating Certificate Stores" later in this README, you may supply either a user id and password for the certificate store credentials (directly or through one of Keyfactor Command's PAM integrations), or a user id and SSH private key. Both PKCS#1 (BEGIN RSA PRIVATE KEY) and PKCS#8 (BEGIN PRIVATE KEY) formats are supported for the SSH private key. If using the normal Keyfactor Command credentials dialog without PAM integration, just copy and paste the full SSH private key into the Password textbox. +Please reference [Configuration File Setup](#configuration-file-setup) for more information on setting up the config.json file and [Certificate Stores and Discovery Jobs](#certificate-stores-and-discovery-jobs) for more information on the items above. +
-**For Windows orchestrated servers:** -1. 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 When creating a new certificate store in Keyfactor Command (See "Creating Certificate Stores" later in this README). +
+Certificate stores hosted on Windows servers: +1. When orchestrating management of external (and potentially local) certificate stores, the RemoteFile Orchestrator Extension makes use of WinRM to connect to external certificate store servers. The security context used is the user id entered in the Keyfactor Command certificate store or discovery job screen. Make sure that WinRM is set up on the orchestrated server and that the WinRM port (by convention, 5585 for HTTP and 5586 for HTTPS) is part of the certificate store path when setting up your certificate stores/discovery jobs. If running as an agent, managing local certificate stores, local commands are run under the security context of the user account running the Keyfactor Universal Orchestrator Service. Please reference [Certificate Stores and Discovery Jobs](#certificate-stores-and-discovery-jobs) for more information on creating certificate stores for the RemoteFile Orchestrator Extension. + +
Please consult with your company's system administrator for more information on configuring SSH/SFTP/SCP or WinRM in your environment. -  + +   ## Remote File Orchestrator Extension Installation -1. Create the certificate store types you wish to manage. Please refer to the individual sections devoted to each supported store type under "Certificate Store Types" later in this README. -2. Stop the Keyfactor Universal Orchestrator Service for the orchestrator you plan to install this extension to run on. -3. In the Keyfactor Orchestrator installation folder (by convention usually C:\Program Files\Keyfactor\Keyfactor Orchestrator), find the "Extensions" folder. Underneath that, create a new folder named "RemoteFile". You may choose to use a different name if you wish. -4. Download the latest version of the RemoteFile orchestrator extension from [GitHub](https://github.com/Keyfactor/remote-file-orchestrator). Click on the "Latest" release link on the right hand side of the main page and download the first zip file. -5. Copy the contents of the download installation zip file to the folder created in Step 3. -6. (Optional) If you decide to create one or more certificate store types with short names different than the suggested values (please see the individual certificate store type sections in "Certificate Store Types" later in this README for more information regarding certificate store types), edit the manifest.json file in the folder you created in step 3, and modify each "ShortName" in each "Certstores.{ShortName}.{Operation}" line with the ShortName you used to create the respective certificate store type. If you created it with the suggested values, this step can be skipped. -7. Modify the config.json file (See the "Configuration File Setup" section later in this README) -8. Start the Keyfactor Universal Orchestrator Service. -  -  +1. Review the [Prerequisites and Security Considerations](#prerequisites-and-security-considerations) section and make sure your environment is set up as required. +2. Refer to the [Creating Certificate Store Types](#creating-certificate-store-types) section to create the certificate store types you wish to manage. +3. Stop the Keyfactor Universal Orchestrator Service on the server you plan to install this extension to run on. +4. In the Keyfactor Orchestrator installation folder (by convention usually C:\Program Files\Keyfactor\Keyfactor Orchestrator for a Windows install or /opt/keyfactor/orchestrator/ for a Linux install), find the "Extensions" folder. Underneath that, create a new folder named "RemoteFile". You may choose to use a different name if you wish. +5. Download the latest version of the RemoteFile orchestrator extension from [GitHub](https://github.com/Keyfactor/remote-file-orchestrator). Click on the "Latest" release link on the right hand side of the main page and download the first zip file. +6. Copy the contents of the download installation zip file to the folder created in step 4. +7. (Optional) If you decide to create one or more certificate store types with short names different than the suggested values, edit the manifest.json file in the folder you created in step 4, and modify each "ShortName" in each "Certstores.{ShortName}.{Operation}" line with the ShortName you used to create the respective certificate store type. +8. Modify the config.json file to use the settings you desire. Please go to [Configuration File Setup](#configuration-file-setup) to learn more. +9. Start the Keyfactor Universal Orchestrator Service. + + + +  ## Configuration File Setup The Remote File Orchestrator Extension uses a JSON configuration file. It is located in the {Keyfactor Orchestrator Installation Folder}\Extensions\RemoteFile. None of the values are required, and a description of each follows below: @@ -77,227 +161,341 @@ The Remote File Orchestrator Extension uses a JSON configuration file. It is lo "DefaultOwnerOnStoreCreation": "" } -**UseSudo** (Applicable for Linux orchestrated servers only) - Y/N - Determines whether to prefix certain Linux command with "sudo". This can be very helpful in ensuring that the user id running commands over an ssh connection 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 Windows orchestrated servers, this setting has no effect. Setting this value to "N" will result in "sudo" not being added to Linux commands. -**DefaultSudoImpersonatedUser** (Applicable for Linux orchestrated servers only) - Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is set to an empty string, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see later in this section) as well as permissions to execute the commands listed in the "Security Considerations" section above. This value will be used for all certificate stores managed by this orchestrator extension implementation UNLESS overriden by the SudoImpersonatedUser certificate store type custom field setting described later in the Certificate Store Types section. -**CreateStoreOnAddIfMissing** - Y/N - Determines, during a Management-Add job, if a certificate store should be created if it does not already exist. If set to "N", and the store referenced in the Management-Add job is not found, the job will return an error with a message stating that the store does not exist. If set to "Y", the store will be created and the certificate added to the certificate store. **Default value if missing - N**. -**UseNegotiateAuth** (Applicable for Windows orchestrated servers only) – Y/N - Determines if WinRM should use Negotiate (Y) when connecting to the remote server. **Default Value if missing - N**. -**SeparateUploadFilePath**(Applicable for Linux managed servers only) – Set this to the path you wish to use as the location on the orchestrated server to upload/download and later remove temporary work files when processing jobs. If set to "" or not provided, the location of the certificate store itself will be used. File transfer itself is performed using SCP or SFTP protocols (see FileT ransferProtocol setting). **Default Value if missing - blank**. -**FileTransferProtocol** (Applicable for Linux orchestrated servers only) - SCP/SFTP/Both - Determines the protocol to use when uploading/downloading files while processing a job. Valid values are: SCP - uses SCP, SFTP - uses SFTP, or Both - will attempt to use SCP first, and if that does not work, will attempt the file transfer via SFTP. **Default Value if missing - SCP**. -**DefaultLinuxPermissionsOnStoreCreation** (Applicable for Linux managed servers only) - 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 or a Management Add job where CreateStoreOnAddIsMissing is set to "Y". 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 (See the "Certificatee Store Types Supported" section later in this README). **Default Value if missing - 600**. -**DefaultOwnerOnStoreCreation** (Applicable for Linux managed servers only) - When a Management job is run to remotely create the physical certificate store on a remote server, by default the file owner and group will be set to the user name associated with the Keyfactor certificate store. Setting DefaultOwnerOnStoreCreation to an alternative valid Linux user name will set that as the owner/group instead. If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please make sure that the user associated with the certificate store will have valid permissions to chown the certificate store file to this alernative owner. The optional "Linux File Owner on Store Creation" custom parameter setting for a specific certificate store (See the "Certificatee Store Types Supported" section later in this README) can override this value for a specific store. **Default Value if missing - blank**. -  -  -## Certificate Store Types - -When setting up the certificate store types you wish the Remote File Orchestrator Extension to manage, there are some common settings that will be the same for all supported types. To create a new Certificate Store Type in Keyfactor Command, first click on settings (the gear icon on the top right) => Certificate Store Types => Add. Alternatively, there are CURL scripts for all of the currently implemented certificate store types in the Certificate Store Type CURL Scripts folder in this repo if you wish to automate the creation of the desired store types. - -**Common Values:** -*Basic Tab:* -- **Name** – Required. The display name you wish to use for the new Certificate Store Type. -- **ShortName** - Required. See specific certificate store type instructions below. -- **Custom Capability** - Unchecked -- **Supported Job Types** - Inventory, Add, Remove, Create, and Discovery should all be checked. -- **Needs Server** - Checked -- **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. -- **Uses PowerShell** - Unchecked -- **Requires Store Password** - Checked. NOTE: This does not require that a certificate store have a password, but merely ensures that a user who creates a Keyfactor Command Certificate Store MUST click the Store Password button and either enter a password or check No Password. Certificate stores with no passwords are still possible for certain certificate store types when checking this option. -- **Supports Entry Password** - Unchecked. - -*Advanced Tab:* -- **Store Path Type** - Freeform -- **Supports Custom Alias** - See specific certificate store type instructions below. -- **Private Key Handling** - See specific certificate store type instructions below -- **PFX Password Style** - Default - -*Custom Fields Tab:* -- **Name:** LinuxFilePermissionsOnStoreCreation, **Display Name:** Linux File Permissions on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultLinuxPermissionsOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, must be 3 digits all between 0-7. This represents the Linux file permissions that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". -- **Name:** LinuxFileOwnerOnStoreCreation, **Display Name:** Linux File Owner on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultOwnerOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, represents the alternate Linux file owner/group that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please confirm that the user name associated with this Keyfactor certificate store has valid permissions to chown the certificate file to this owner. -- **Name:** SudoImpersonatedUser, **Display Name:** Sudo Impersonated User Id, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultSudoImpersonatedUser setting in config.json (see Configuration File Setup section above). Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is empty, and nothing is set for DefaultSudoImpersonatedUser in your config.json, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see Configuration File Setup section above) as well as permissions to execute the commands listed in the "Security Considerations" section above. - -Entry Parameters Tab: -- See specific certificate store type instructions below +
+UseSudo (Applicable for Linux hosted certificate stores only) -  -  -************************************** -**RFPkcs12 Certificate Store Type** -************************************** +* Determines whether to prefix Linux command with "sudo". This can be very helpful in ensuring that the user id running commands over an ssh connection 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. Setting this value to "N" will result in "sudo" not being added to Linux commands. +* Allowed values - Y/N +* Default value - N -The RFPkcs12 store type can be used to manage any PKCS#12 compliant file format INCLUDING java keystores of type PKCS12. +
-Use cases supported: -1. One-to-many trust entries - A single certificate without a private key in a certificate store. Each certificate identified with a custom alias or certificate thumbprint. -2. One-to-many key entries - One-to-many certificates with private keys and optionally the full certificate chain. Each certificate identified with a custom alias or certificate thumbprint. -3. A mix of trust and key entries. +
+DefaultSudoImpersonatedUser (Applicable for Linux hosted certificate stores only) -**Specific Certificate Store Type Values** -*Basic Tab:* -- **Short Name** – Required. Suggested value - **RFPkcs12**. If you choose to use a different value you must make the corresponding modification to the manifest.json file (see "Remote File Orchestrator Extension Installation", step 6 above). +* Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is set to an empty string, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see later in this section) as well as permissions to execute the commands listed in the "Prerequisites and Security Considerations" section above. This value will be used for all certificate stores managed by this orchestrator extension implementation UNLESS overriden by the SudoImpersonatedUser certificate store type custom field setting described later in the [Creating Certificate Store Types](#creating-certificate-store-types) section. +* Allowed values - Any valid user id that the destination Linux server will recognize +* Default value - blank (root will be used) -*Advanced Tab:* -- **Supports Custom Alias** - Required. -- **Private Key Handling** - Optional. +
-*Custom Fields Tab:* -- no adittional custom fields/parameters +
+CreateStoreOnAddIfMissing -Entry Parameters Tab: -- no additional entry parameters +* Determines, during a Management-Add job, if a certificate store should be created if it does not already exist. If set to "N", and the store referenced in the Management-Add job is not found, the job will return an error with a message stating that the store does not exist. If set to "Y", the store will be created and the certificate added to the certificate store. +* Allowed values - Y/N +* Default value - N -  -  -************************************** -**RFJKS Certificate Store Type** -************************************** +
-The RFJKS store type can be used to manage java keystores of type JKS. **PLEASE NOTE:** Java keystores of type PKCS12 **_cannot_** be managed by the RFJKS type. You **_must_** use RFPkcs12. +
+UseNegotiateAuth (Applicable for Windows hosted certificate stores only) -Use cases supported: -1. One-to-many trust entries - A single certificate without a private key in a certificate store. Each certificate identified with a custom alias or certificate thumbprint. -2. One-to-many key entries - One-to-many certificates with private keys and optionally the full certificate chain. Each certificate identified with a custom alias or certificate thumbprint. -3. A mix of trust and key entries. +* Determines if WinRM should use Negotiate (Y) when connecting to the remote server. +* Allowed values - Y/N +* Default value - N -**Specific Certificate Store Type Values** -*Basic Tab:* -- **Short Name** – Required. Suggested value - **RFJKS**. If you choose to use a different value you must make the corresponding modification to the manifest.json file (see "Remote File Orchestrator Extension Installation", step 6 above). +
-*Advanced Tab:* -- **Supports Custom Alias** - Required. -- **Private Key Handling** - Optional. +
+SeparateUploadFilePath (Applicable for Linux hosted certificate stores only) -*Custom Fields Tab:* -- no adittional custom fields/parameters +* Set this to the path you wish to use as the location on the orchestrated server to upload/download and later remove temporary work files when processing jobs. If set to "" or not provided, the location of the certificate store itself will be used. File transfer is performed using the SCP or SFTP protocols (see the File TransferProtocol setting). +* Allowed values - Any valid, existing Linux path configured to allow SCP/SFTP file upload/download tranfers. +* Default value - blank (actual store path will be used) -Entry Parameters Tab: -- no additional entry parameters +
-  -  -************************************** -**RFPEM Certificate Store Type** -************************************** +
+FileTransferProtocol (Applicable for Linux hosted certificate stores only) -The RFPEM store type can be used to manage PEM encoded files. +* Determines the protocol to use when uploading/downloading files while processing a job. +* Allowed values - SCP, SFTP or Both. If "Both" is entered, SCP will be attempted first, and if that does not work, SFTP will be tried. +* Default value - SCP. -Use cases supported: -1. Trust stores - A file with one-to-many certificates (no private keys, no certificate chains). -2. Single certificate stores with private key in the file. -3. Single certificate stores with certificate chain and private key in the file. -4. Single certificate stores with private key in an external file. -5. Single certificate stores with certificate chain in the file and private key in an external file +
-**Specific Certificate Store Type Values** -*Basic Tab:* -- **Short Name** – Required. Suggested value - **RFPEM**. If you choose to use a different value you must make the corresponding modification to the manifest.json file (see "Remote File Orchestrator Extension Installation", step 6 above). +
+DefaultLinuxPermissionsOnStoreCreation (Applicable for Linux hosted certificate stores only) -*Advanced Tab:* -- **Supports Custom Alias** - Forbidden. -- **Private Key Handling** - Optional. +* The Linux file permissions that will be set on a new certificate store created via a Management Create job or a Management Add job where CreateStoreOnAddIsMissing is set to "Y". 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. See the [Creating Certificate Store Types](#creating-certificate-store-types) section for more information on creating RemoteFile certificate store types. +* Allowed values - Any 3 digit value from 000-777. +* Default Value - 600. -*Custom Fields Tab:* -- **Name:** IsTrustStore, **Display Name:** Trust Store, **Type:** Bool, **Default Value:** false. This custom field is **not required**. Default value if not present is 'false'. If 'true', this store will be identified as a trust store. Any certificates attempting to be added via a Management-Add job that contain a private key will raise an error with an accompanying message. Multiple certificates may be added to the store in this use case. If set to 'false', this store can only contain a single certificate with chain and private key. Management-Add jobs attempting to add a certificate without a private key to a store marked as IsTrustStore = 'false' will raise an error with an accompanying message. -- **Name:** IncludesChain, **Display Name:** Store Includes Chain, **Type:** Bool, **Default Value:** false. This custom field is **not required**. Default value if not present is 'false'. If 'true' the full certificate chain, if sent by Keyfactor Command, will be stored in the file. The order of appearance is always assumed to be 1) end entity certificate, 2) issuing CA certificate, and 3) root certificate. If additional CA tiers are applicable, the order will be end entity certificate up to the root CA certificate. if set to 'false', only the end entity certificate and private key will be stored in this store. This setting is only valid when IsTrustStore = false. -- **Name:** SeparatePrivateKeyFilePath, **Display Name:** Separate Private Key File Location, **Type:** String, **Default Value:** empty. This custom field is **not required**. If empty, or not provided, it will be assumed that the private key for the certificate stored in this file will be inside the same file as the certificate. If the full path AND file name is put here, that location will be used to store the private key as an external file. This setting is only valid when IsTrustStore = false. -- **Name:** IsRSAPrivateKey, **Display Name:** Is RSA Private Key, **Type:** Bool, **Default Value:** false. This custom field is **not required**. Default value if not present is 'false'. If 'true' it will be assumed that the private key for the certificate is a PKCS#1 RSA formatted private key (BEGIN RSA PRIVATE KEY). If 'false' (default), encrypted/non-encrypted PKCS#8 (BEGIN [ENCRYPTED] PRIVATE KEY) is assumed If set to 'true' the store password **must** be set to "no password", as PKCS#1 does not support encrypted keys. This setting is only valid when IsTrustStore = false. -- **Name:** IgnorePrivateKeyOnInventory, **Display Name:** Ignore Private Key On Inventory, **Type:** Bool, **Default Value:** false. This custom field is **not required**. Default value if not present is 'false'. If 'true', inventory for this certificate store will be performed without accessing the certificate's private key or the store password. This will functionally make the store INVENTORY ONLY, as all certificates will be returned with "Private Key Entry" = false. Also, no certificate chain relationships will be maintained, and all certificates will be considered separate entries (basically a trust store). This may be useful in situations where the client does not know the store password at inventory run time, but would still like the certificates to be imported into Keyfactor Command. Once the correct store password is entered for the store, the client may de-select this option (change the value to False), schedule an inventory job, and then the appropriate private key entry and chain information should be properly stored in the Keyfactor Command location, allowing for renewal/removal of the certificate at a later time. +
-Entry Parameters Tab: -- no additional entry parameters +
+DefaultOwnerOnStoreCreation (Applicable for Linux hosted certificate stores only) + +* When a Management job is run to remotely create the physical certificate store on a remote server, by default the file owner and group will be set to the user name associated with the Keyfactor certificate store. Setting DefaultOwnerOnStoreCreation to an alternative valid Linux user name will set that as the owner/group instead. If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please make sure that the user associated with the certificate store will have valid permissions to chown the certificate store file to this alernative owner. The optional "Linux File Owner on Store Creation" custom parameter setting for a specific certificate store can override this value for a specific store. See the [Creating Certificate Store Types](#creating-certificate-store-types) section for more information on creating RemoteFile certificate store types. +* Allowed values - Any valid user id that the destination Linux server will recognize +* Default Value - blank (the ID associated with the Keyfactor certificate store will be used). + +
  -  -************************************** -**RFDER Certificate Store Type** -************************************** +## Creating Certificate Store Types -The RFDER store type can be used to manage DER encoded files. +Below are the various certificate store types that the RemoteFile Orchestator Extension manages. To create a new Certificate Store Type in Keyfactor Command, first click on settings (the gear icon on the top right) => Certificate Store Types => Add. Next, follow the incstructions under each store type you wish to set up. -Use cases supported: -1. Single certificate stores with private key in an external file. -5. Single certificate stores with no private key. +
+RFPkcs12 - Pkcs12 formatted certificate file (including java keystores of type PKCS12) -**Specific Certificate Store Type Values** -*Basic Tab:* -- **Short Name** – Required. Suggested value - **RFDER**. If you choose to use a different value you must make the corresponding modification to the manifest.json file (see "Remote File Orchestrator Extension Installation", step 6 above). +- Basic Tab: -*Advanced Tab:* -- **Supports Custom Alias** - Forbidden. -- **Private Key Handling** - Optional. + - **Name** – Required. The display name you wish to use for the new Certificate Store Type. + - **Short Name** – Required. Suggested value - **RFPkcs12**. If you choose to use a different value you must make the corresponding modification to the manifest.json file. See [Remote File Orchestrator Extension Installation](#remote-file-orchestrator-extension-installation), step 7 above. + - **Custom Capability** - Unchecked + - **Supported Job Types** - Inventory, Add, Remove, Create, and Discovery should all be checked. + - **Needs Server** - Checked + - **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. + - **Uses PowerShell** - Unchecked + - **Requires Store Password** - Checked. NOTE: This does not require that a certificate store have a password, but merely ensures that a user who creates a Keyfactor Command Certificate Store MUST click the Store Password button and either enter a password or check No Password. Certificate stores with no passwords are still possible for certain certificate store types when checking this option. + - **Supports Entry Password** - Unchecked. -*Custom Fields Tab:* -- **Name:** SeparatePrivateKeyFilePath, **Display Name:** Separate Private Key File Location, **Type:** String, **Default Value:** empty. This custom field is **not required**. If empty, or not provided, it will be assumed that there is no private key associated with this DER store. If the full path AND file name is entered here, that location will be used to store the private key as an external file in DER format. +- Advanced Tab: -Entry Parameters Tab: -- no additional entry parameters + - **Store Path Type** - Freeform + - **Supports Custom Alias** - Required. + - **Private Key Handling** - Optional. + - **PFX Password Style** - Default -  -  -************************************** -**RFKDB Certificate Store Type** -************************************** +- Custom Fields Tab: -The RFKDB store type can be used to manage IBM Key Database Files (KDB) files. The IBM utility, GSKCAPICMD, is used to read and write certificates from and to the target store and is therefore required to be installed on the server where each KDB certificate store being managed resides, and its location MUST be in the system $Path. + - **Name:** LinuxFilePermissionsOnStoreCreation, **Display Name:** Linux File Permissions on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultLinuxPermissionsOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, must be 3 digits all between 0-7. This represents the Linux file permissions that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". + - **Name:** LinuxFileOwnerOnStoreCreation, **Display Name:** Linux File Owner on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultOwnerOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, represents the alternate Linux file owner/group that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please confirm that the user name associated with this Keyfactor certificate store has valid permissions to chown the certificate file to this owner. + - **Name:** SudoImpersonatedUser, **Display Name:** Sudo Impersonated User Id, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultSudoImpersonatedUser setting in config.json (see Configuration File Setup section above). Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is empty, and nothing is set for DefaultSudoImpersonatedUser in your config.json, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see Configuration File Setup section above) as well as permissions to execute the commands listed in the "Security Considerations" section above. -Use cases supported: -1. One-to-many trust entries - A single certificate without a private key in a certificate store. Each certificate identified with a custom alias or certificate thumbprint. -2. One-to-many key entries - One-to-many certificates with private keys and optionally the full certificate chain. Each certificate identified with a custom alias or certificate thumbprint. -3. A mix of trust and key entries. +- Entry Parameters Tab: -**Specific Certificate Store Type Values** -*Basic Tab:* -- **Short Name** – Required. Suggested value - **RFKDB**. If you choose to use a different value you must make the corresponding modification to the manifest.json file (see "Remote File Orchestrator Extension Installation", step 6 above). + - no additional entry parameters -*Advanced Tab:* -- **Supports Custom Alias** - Required. -- **Private Key Handling** - Optional. +
-*Custom Fields Tab:* -- no adittional custom fields/parameters +
+RFJKS - Java keystore -Entry Parameters Tab: -- no additional entry parameters +- Basic Tab: -  -  -************************************** -**RFORA Certificate Store Type** -************************************** + - **Name** – Required. The display name you wish to use for the new Certificate Store Type. + - **Short Name** – Required. Suggested value - **RFJKS**. If you choose to use a different value you must make the corresponding modification to the manifest.json file. See [Remote File Orchestrator Extension Installation](#remote-file-orchestrator-extension-installation), step 7 above. + - **Custom Capability** - Unchecked + - **Supported Job Types** - Inventory, Add, Remove, Create, and Discovery should all be checked. + - **Needs Server** - Checked + - **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. + - **Uses PowerShell** - Unchecked + - **Requires Store Password** - Checked. NOTE: This does not require that a certificate store have a password, but merely ensures that a user who creates a Keyfactor Command Certificate Store MUST click the Store Password button and either enter a password or check No Password. Certificate stores with no passwords are still possible for certain certificate store types when checking this option. + - **Supports Entry Password** - Unchecked. -The RFORA store type can be used to manage Pkcs2 Oracle Wallets. Please note that while this should work for Pkcs12 Oracle Wallets installed on both Windows and Linux servers, this has only been tested on wallets installed on Windows. Please note, when entering the Store Path for an Oracle Wallet in Keyfactor Command, make sure to INCLUDE the eWallet.p12 file name that by convention is the name of the Pkcs12 wallet file that gets created. +- Advanced Tab: -Use cases supported: -1. One-to-many trust entries - A single certificate without a private key in a certificate store. Each certificate identified with a custom alias or certificate thumbprint. -2. One-to-many key entries - One-to-many certificates with private keys and optionally the full certificate chain. Each certificate identified with a custom alias or certificate thumbprint. -3. A mix of trust and key entries. + - **Store Path Type** - Freeform + - **Supports Custom Alias** - Required. + - **Private Key Handling** - Optional. + - **PFX Password Style** - Default -**Specific Certificate Store Type Values** -*Basic Tab:* -- **Short Name** – Required. Suggested value - **RFORA**. If you choose to use a different value you must make the corresponding modification to the manifest.json file (see "Remote File Orchestrator Extension Installation", step 6 above). +- Custom Fields Tab: + + - **Name:** LinuxFilePermissionsOnStoreCreation, **Display Name:** Linux File Permissions on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultLinuxPermissionsOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, must be 3 digits all between 0-7. This represents the Linux file permissions that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". + - **Name:** LinuxFileOwnerOnStoreCreation, **Display Name:** Linux File Owner on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultOwnerOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, represents the alternate Linux file owner/group that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please confirm that the user name associated with this Keyfactor certificate store has valid permissions to chown the certificate file to this owner. + - **Name:** SudoImpersonatedUser, **Display Name:** Sudo Impersonated User Id, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultSudoImpersonatedUser setting in config.json (see Configuration File Setup section above). Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is empty, and nothing is set for DefaultSudoImpersonatedUser in your config.json, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see Configuration File Setup section above) as well as permissions to execute the commands listed in the "Security Considerations" section above. -*Advanced Tab:* -- **Supports Custom Alias** - Required. -- **Private Key Handling** - Optional. +- Entry Parameters Tab: -*Custom Fields Tab:* -- **Name:** WorkFolder, **Display Name:** Work Folder, **Type:** String, **Default Value:** empty. This custom field is **required**. This required field should contain the path on the managed server where temporary work files can be created during Inventory and Management jobs. These files will be removed at the end of each job Please make sure that user id you have assigned to this certificate store will have access to create, modify, and delete files from this folder. + - no additional entry parameters -Entry Parameters Tab: -- no additional entry parameters +
+ +
+RFPEM - PEM formatted certificate file + +- Basic Tab: + + - **Name** – Required. The display name you wish to use for the new Certificate Store Type. + - **Short Name** – Required. Suggested value - **RFPEM**. If you choose to use a different value you must make the corresponding modification to the manifest.json file. See [Remote File Orchestrator Extension Installation](#remote-file-orchestrator-extension-installation), step 7 above. + - **Custom Capability** - Unchecked + - **Supported Job Types** - Inventory, Add, Remove, Create, and Discovery should all be checked. + - **Needs Server** - Checked + - **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. + - **Uses PowerShell** - Unchecked + - **Requires Store Password** - Checked. NOTE: This does not require that a certificate store have a password, but merely ensures that a user who creates a Keyfactor Command Certificate Store MUST click the Store Password button and either enter a password or check No Password. Certificate stores with no passwords are still possible for certain certificate store types when checking this option. + - **Supports Entry Password** - Unchecked. + +- Advanced Tab: + + - **Store Path Type** - Freeform + - **Supports Custom Alias** - Forbidden. + - **Private Key Handling** - Optional. + - **PFX Password Style** - Default + +- Custom Fields Tab: + + - **Name:** LinuxFilePermissionsOnStoreCreation, **Display Name:** Linux File Permissions on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultLinuxPermissionsOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, must be 3 digits all between 0-7. This represents the Linux file permissions that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". + - **Name:** LinuxFileOwnerOnStoreCreation, **Display Name:** Linux File Owner on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultOwnerOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, represents the alternate Linux file owner/group that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please confirm that the user name associated with this Keyfactor certificate store has valid permissions to chown the certificate file to this owner. + - **Name:** SudoImpersonatedUser, **Display Name:** Sudo Impersonated User Id, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultSudoImpersonatedUser setting in config.json (see Configuration File Setup section above). Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is empty, and nothing is set for DefaultSudoImpersonatedUser in your config.json, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see Configuration File Setup section above) as well as permissions to execute the commands listed in the "Security Considerations" section above. + - **Name:** IsTrustStore, **Display Name:** Trust Store, **Type:** Bool, **Default Value:** false. This custom field is **not required**. Default value if not present is 'false'. If 'true', this store will be identified as a trust store. Any certificates attempting to be added via a Management-Add job that contain a private key will raise an error with an accompanying message. Multiple certificates may be added to the store in this use case. If set to 'false', this store can only contain a single certificate with chain and private key. Management-Add jobs attempting to add a certificate without a private key to a store marked as IsTrustStore = 'false' will raise an error with an accompanying message. + - **Name:** IncludesChain, **Display Name:** Store Includes Chain, **Type:** Bool, **Default Value:** false. This custom field is **not required**. Default value if not present is 'false'. If 'true' the full certificate chain, if sent by Keyfactor Command, will be stored in the file. The order of appearance is always assumed to be 1) end entity certificate, 2) issuing CA certificate, and 3) root certificate. If additional CA tiers are applicable, the order will be end entity certificate up to the root CA certificate. if set to 'false', only the end entity certificate and private key will be stored in this store. This setting is only valid when IsTrustStore = false. + - **Name:** SeparatePrivateKeyFilePath, **Display Name:** Separate Private Key File Location, **Type:** String, **Default Value:** empty. This custom field is **not required**. If empty, or not provided, it will be assumed that the private key for the certificate stored in this file will be inside the same file as the certificate. If the full path AND file name is put here, that location will be used to store the private key as an external file. This setting is only valid when IsTrustStore = false. + - **Name:** IsRSAPrivateKey, **Display Name:** Is RSA Private Key, **Type:** Bool, **Default Value:** false. This custom field is **not required**. Default value if not present is 'false'. If 'true' it will be assumed that the private key for the certificate is a PKCS#1 RSA formatted private key (BEGIN RSA PRIVATE KEY). If 'false' (default), encrypted/non-encrypted PKCS#8 (BEGIN [ENCRYPTED] PRIVATE KEY) is assumed If set to 'true' the store password **must** be set to "no password", as PKCS#1 does not support encrypted keys. This setting is only valid when IsTrustStore = false. + - **Name:** IgnorePrivateKeyOnInventory, **Display Name:** Ignore Private Key On Inventory, **Type:** Bool, **Default Value:** false. This custom field is **not required**. Default value if not present is 'false'. If 'true', inventory for this certificate store will be performed without accessing the certificate's private key or the store password. This will functionally make the store INVENTORY ONLY, as all certificates will be returned with "Private Key Entry" = false. Also, no certificate chain relationships will be maintained, and all certificates will be considered separate entries (basically a trust store). This may be useful in situations where the client does not know the store password at inventory run time, but would still like the certificates to be imported into Keyfactor Command. Once the correct store password is entered for the store, the client may de-select this option (change the value to False), schedule an inventory job, and then the appropriate private key entry and chain information should be properly stored in the Keyfactor Command location, allowing for renewal/removal of the certificate at a later time. + +- Entry Parameters Tab: + + - no additional entry parameters + +
+ +
+RFDER - DER formatted certificate file + +- Basic Tab: + + - **Name** – Required. The display name you wish to use for the new Certificate Store Type. + - **Short Name** – Required. Suggested value - **RFDER**. If you choose to use a different value you must make the corresponding modification to the manifest.json file. See [Remote File Orchestrator Extension Installation](#remote-file-orchestrator-extension-installation), step 7 above. + - **Custom Capability** - Unchecked + - **Supported Job Types** - Inventory, Add, Remove, Create, and Discovery should all be checked. + - **Needs Server** - Checked + - **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. + - **Uses PowerShell** - Unchecked + - **Requires Store Password** - Checked. NOTE: This does not require that a certificate store have a password, but merely ensures that a user who creates a Keyfactor Command Certificate Store MUST click the Store Password button and either enter a password or check No Password. Certificate stores with no passwords are still possible for certain certificate store types when checking this option. + - **Supports Entry Password** - Unchecked. + +- Advanced Tab: + + - **Store Path Type** - Freeform + - **Supports Custom Alias** - Forbidden. + - **Private Key Handling** - Optional. + - **PFX Password Style** - Default + +- Custom Fields Tab: + + - **Name:** LinuxFilePermissionsOnStoreCreation, **Display Name:** Linux File Permissions on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultLinuxPermissionsOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, must be 3 digits all between 0-7. This represents the Linux file permissions that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". + - **Name:** LinuxFileOwnerOnStoreCreation, **Display Name:** Linux File Owner on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultOwnerOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, represents the alternate Linux file owner/group that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please confirm that the user name associated with this Keyfactor certificate store has valid permissions to chown the certificate file to this owner. + - **Name:** SudoImpersonatedUser, **Display Name:** Sudo Impersonated User Id, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultSudoImpersonatedUser setting in config.json (see Configuration File Setup section above). Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is empty, and nothing is set for DefaultSudoImpersonatedUser in your config.json, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see Configuration File Setup section above) as well as permissions to execute the commands listed in the "Security Considerations" section above. + - **Name:** SeparatePrivateKeyFilePath, **Display Name:** Separate Private Key File Location, **Type:** String, **Default Value:** empty. This custom field is **not required**. If empty, or not provided, it will be assumed that there is no private key associated with this DER store. If the full path AND file name is entered here, that location will be used to store the private key as an external file in DER format. + +- Entry Parameters Tab: + + - no additional entry parameters + +
+ +
+RFKDB - IBM Key Database File + +- Basic Tab: + + - **Name** – Required. The display name you wish to use for the new Certificate Store Type. + - **Short Name** – Required. Suggested value - **RFKDB**. If you choose to use a different value you must make the corresponding modification to the manifest.json file. See [Remote File Orchestrator Extension Installation](#remote-file-orchestrator-extension-installation), step 7 above. + - **Custom Capability** - Unchecked + - **Supported Job Types** - Inventory, Add, Remove, Create, and Discovery should all be checked. + - **Needs Server** - Checked + - **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. + - **Uses PowerShell** - Unchecked + - **Requires Store Password** - Checked. NOTE: This does not require that a certificate store have a password, but merely ensures that a user who creates a Keyfactor Command Certificate Store MUST click the Store Password button and either enter a password or check No Password. Certificate stores with no passwords are still possible for certain certificate store types when checking this option. + - **Supports Entry Password** - Unchecked. + +- Advanced Tab: + + - **Store Path Type** - Freeform + - **Supports Custom Alias** - Required. + - **Private Key Handling** - Optional. + - **PFX Password Style** - Default + +- Custom Fields Tab: + + - **Name:** LinuxFilePermissionsOnStoreCreation, **Display Name:** Linux File Permissions on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultLinuxPermissionsOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, must be 3 digits all between 0-7. This represents the Linux file permissions that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". + - **Name:** LinuxFileOwnerOnStoreCreation, **Display Name:** Linux File Owner on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultOwnerOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, represents the alternate Linux file owner/group that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please confirm that the user name associated with this Keyfactor certificate store has valid permissions to chown the certificate file to this owner. + - **Name:** SudoImpersonatedUser, **Display Name:** Sudo Impersonated User Id, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultSudoImpersonatedUser setting in config.json (see Configuration File Setup section above). Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is empty, and nothing is set for DefaultSudoImpersonatedUser in your config.json, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see Configuration File Setup section above) as well as permissions to execute the commands listed in the "Security Considerations" section above. + +- Entry Parameters Tab: + + - no additional entry parameters + +
+ +
+RFORA - Oracle Wallet + +- Basic Tab: + + - **Name** – Required. The display name you wish to use for the new Certificate Store Type. + - **Short Name** – Required. Suggested value - **RFORA**. If you choose to use a different value you must make the corresponding modification to the manifest.json file. See [Remote File Orchestrator Extension Installation](#remote-file-orchestrator-extension-installation), step 7 above. + - **Custom Capability** - Unchecked + - **Supported Job Types** - Inventory, Add, Remove, Create, and Discovery should all be checked. + - **Needs Server** - Checked + - **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. + - **Uses PowerShell** - Unchecked + - **Requires Store Password** - Checked. NOTE: This does not require that a certificate store have a password, but merely ensures that a user who creates a Keyfactor Command Certificate Store MUST click the Store Password button and either enter a password or check No Password. Certificate stores with no passwords are still possible for certain certificate store types when checking this option. + - **Supports Entry Password** - Unchecked. + +- Advanced Tab: + + - **Store Path Type** - Freeform + - **Supports Custom Alias** - Required. + - **Private Key Handling** - Optional. + - **PFX Password Style** - Default + +- Custom Fields Tab: + + - **Name:** LinuxFilePermissionsOnStoreCreation, **Display Name:** Linux File Permissions on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultLinuxPermissionsOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, must be 3 digits all between 0-7. This represents the Linux file permissions that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". + - **Name:** LinuxFileOwnerOnStoreCreation, **Display Name:** Linux File Owner on Store Creation, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultOwnerOnStoreCreation setting in config.json (see Configuration File Setup section above). This value, applicable to certificate stores hosted on Linux orchestrated servers only, represents the alternate Linux file owner/group that will be set for this certificate store if created via a Management Create job or a Management Add job where the config.json option CreateStoreOnAddIsMissing is set to "Y". If the group and owner need to be different values, use a ":" as a delimitter between the owner and group values, such as ownerId:groupId. Please confirm that the user name associated with this Keyfactor certificate store has valid permissions to chown the certificate file to this owner. + - **Name:** SudoImpersonatedUser, **Display Name:** Sudo Impersonated User Id, **Type:** String, **Default Value:** none. This custom field is **not required**. If not present, value reverts back to the DefaultSudoImpersonatedUser setting in config.json (see Configuration File Setup section above). Used in conjunction with UseSudo="Y", this optional setting can be used to set an alternate user id you wish to impersonate with sudo. If this option does not exist or is empty, and nothing is set for DefaultSudoImpersonatedUser in your config.json, the default user of "root" will be used. Any user id used here must have permissions to SCP/SFTP files to/from each certificate store location OR the SeparateUploadFilePath (see Configuration File Setup section above) as well as permissions to execute the commands listed in the "Security Considerations" section above. + - **Name:** WorkFolder, **Display Name:** Work Folder, **Type:** String, **Default Value:** empty. This custom field is **required**. This required field should contain the path on the managed server where temporary work files can be created during Inventory and Management jobs. These files will be removed at the end of each job Please make sure that user id you have assigned to this certificate store will have access to create, modify, and delete files from this folder. + +- Entry Parameters Tab: + + - no additional entry parameters + +
  -  -## Creating Certificate Stores and Scheduling Discovery Jobs +## Certificate Stores and Discovery Jobs + +When creating new certificate stores or scheduling discovery jobs in Keyfactor Command, there are a few fields that are important to highlight here: + +
+Client Machine (certificate stores and discovery jobs) + +For Linux orchestrated servers, "Client Machine" should be the DNS name or IP address of the remote orchestrated server, while for Windows orchestratred servers, it should be the following URL format: protocol://dns-or-ip:port, where +* protocol is http or https, whatever your WinRM configuration uses +* dns-or-ip is the DNS name or IP address of the server +* port is the port WinRM is running under, usually 5985 for http and 5986 for https. + +Example: https://myserver.mydomain.com:5986 + +If running as an agent (accessing stores on the server where the Universal Orchestrator Services is installed ONLY), Client Machine can be entered as stated above, OR you can bypass SSH/WinRM and access the local file system directly by adding "|LocalMachine" to the end of your value for Client Machine, for example "1.1.1.1|LocalMachine". In this instance the value to the left of the pipe (|) is ignored. It is important to make sure the values for Client Machine and Store Path together are unique for each certificate store created, as Keyfactor Command requires the Store Type you select, along with Client Machine, and Store Path together must be unique. To ensure this, it is good practice to put the full DNS or IP Address to the left of the | character when setting up a cerificate store that will accessed without a WinRM/SSH connection. + +
+ +
+Store Path (certificate stores only) + +For Linux orchestrated servers, "StorePath" will begin with a forward slash (/) and contain the full path and file name, including file extension if one exists (i.e. /folder/path/storename.ext). For Windows orchestrated servers, it should be the full path and file name, including file extension if one exists, beginning with a drive letter (i.e. c:\folder\path\storename.ext). + +
+ +
+Server Username/Password (certificate stores and discovery jobs) + +A username and password (or valid PAM key if the username and/or password is stored in a KF Command configured PAM integration). The password can be an SSH private key if connecting via SSH to a server using SSH private key authentication. If acting as an *agent* using local file access, just check "No Value" for the username and password. + +
+
+Directories to Search (discovery jobs only) + +Enter one or more comma delimitted file paths to search (please reference the Keyfactor Command Reference Guide for more information), but there is also a special value that can be used on Windows orchestrated servers instead - "fullscan". Entering fullscan in this field will tell the RemoteFile discovery job to search all available drive letters at the root and recursively search all of them for files matching the other search criteria. -Please refer to the Keyfactor Command Reference Guide for information on creating certificate stores and scheduling Discovery jobs in Keyfactor Command. However, there are a few fields that are important to highlight here - Client Machine, Store Path (Creating Certificate Stores), and Directories to search (Discovery jobs) and Extensions (Discovery jobs). For Linux orchestrated servers, "Client Machine" should be the DNS or IP address of the remote orchestrated server while "Store Path" is the full path and file name of the file based store, beginning with a forward slash (/). For Windows orchestrated servers, "Client Machine" should be of the format {protocol}://{dns-or-ip}:{port} where {protocol} is either http or https, {dns-or-ip} is the DNS or IP address of the remote orchestrated server, and {port} is the port where WinRM is listening, by convention usually 5985 for http and 5986 for https. Alternately, entering the keyword "localhost" for "Client Machine" will point to the server where the orchestrator service is installed and WinRM WILL NOT be required. "Store Path" is the full path and file name of the file based store, beginning with a drive letter (i.e. c:\). For example valid values for Client Machine and Store Path for Linux and Windows managed servers may look something like: +
-Linux: Client Machine - 127.0.0.1 or MyLinuxServerName; Store Path - /home/folder/path/storename.ext -Windows: Client Machine - https://My.Server.Domain:5986; Store Path - c:\folder\path\storename.ext +
+Extensions (discovery jobs only) -Credentials **must** be entered: a user id and either a password or valid PAM key if the password is stored in a KF Command configured PAM integration. Alternatively, this password can be an SSH private key if connecting to a Linux server using SSH private key authentication. +In addition to entering one or more comma delimitted extensions to search for (please reference the Keyfactor Command Reference Guide for more information), a reserved value of "noext" can be used that will cause the RemoteFile discovery job to search for files that do not have an extension. This value can be chained with other extensions using the comma delimiter. For example, entering pem,jks,noext will cause the RemoteFile discovery job to return file locations with extensions of "pem", "jks", *and* files that do not have extensions. -For "Directories to search", you can chain paths with a comma delimiter as documented in the Keyfactor Command Reference Guide, but there is also a special value that can be used instead - fullscan. Entering fullscan in this field will tell the RemoteFile discovery job to search all available drive letters and recursively search all of them for files matching the other search criteria. +
-For "Extensions", a reserved value of noext will cause the RemoteFile discovery job to search for files that do not have an extension. This value can be chained with other extensions using a comma delimiter. For example, entering pem,jks,noext will cause the RemoteFile discovery job to search for files with extensions of PEM or JKS or files that do not have extensions. +Please refer to the Keyfactor Command Reference Guide for complete information on creating certificate stores and scheduling discovery jobs in Keyfactor Command.     ## Developer Notes @@ -319,7 +517,7 @@ Steps to create a new supported file based certificate store type: 8. After compiling, move all compiled files, including the config.json and manifest.json to {Keyfactor Orchestrator Installation Folder}\Extensions\RemoteFile. 9. Create the certificate store type in Keyfactor Command 10. Add a new CURL script to build the proper Keyfactor Command certificate store type and place it under "Certificate Store Type CURL Scripts". The name of the file should match the ShortName you are using for the new store type. -11. Update the documenation in readme_source.md by adding a new section under "Certificate Store Types" for this new supported file based store type. Include a pointer to the CURL script created in step 10. +11. Update the documenation in readme_source.md by adding a new section under [Creating Certificate Store Types](#creating-certificate-store-types) for this new supported file based store type. Include a pointer to the CURL script created in step 10.     ## License