diff --git a/CHANGELOG.md b/CHANGELOG.md index ef53e061..da2afb13 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,6 @@ v1.1 -- Add support for IBM Key Database (KDB) files +- Added support for IBM Key Database (KDB) files +- Extended error messaging for SSH/SFTP/SCP connection issues v1.0 - Initial Version diff --git a/README.md b/README.md index 495e8726..9db4327f 100644 --- a/README.md +++ b/README.md @@ -6,16 +6,18 @@ The Remote File Orchestrator allows for the remote management of file-based cert ## About the Keyfactor Universal Orchestrator Capability -This repository contains a Universal Orchestrator Extension which is a plugin to the Keyfactor Universal Orchestrator. Within the Keyfactor Platform, Orchestrators are used to manage “certificate stores” — collections of certificates and roots of trust that are found within and used by various applications. +This repository contains a Universal Orchestrator Capability which is a plugin to the Keyfactor Universal Orchestrator. Within the Keyfactor Platform, Orchestrators are used to manage “certificate stores” — collections of certificates and roots of trust that are found within and used by various applications. The Universal Orchestrator is part of the Keyfactor software distribution and is available via the Keyfactor customer portal. For general instructions on installing Capabilities, see the “Keyfactor Command Orchestrator Installation and Configuration Guide” section of the Keyfactor documentation. For configuration details of this specific Capability, see below in this readme. The Universal Orchestrator is the successor to the Windows Orchestrator. This Capability plugin only works with the Universal Orchestrator and does not work with the Windows Orchestrator. ---- +--- + + ## Platform Specific Notes @@ -33,7 +35,8 @@ The Keyfactor Universal Orchestrator may be installed on either Windows or Linux --- - + + ## 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 @@ -54,12 +57,12 @@ This orchestrator extension makes use of an SSH connection to communicate remote   ## Versioning -The version number of a the Remote File Orchestrator Extension can be verified by right clicking on the n the Extensions/RemoteFile installation folder, selecting Properties, and then clicking on the Details tab. +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.     ## Keyfactor Version Supported -The Remote File Orchestrator Extension has been tested against Keyfactor Universal Orchestrator version 9.5, but should work against earlier or later versions of the Keyfactor Universal Orchestrator. +The Remote File Orchestrator Extension has been tested against Keyfactor Universal Orchestrator version 9.9, but should work against earlier or later versions of the Keyfactor Universal Orchestrator.     ## Security Considerations @@ -80,6 +83,8 @@ The Remote File Orchestrator Extension has been tested against Keyfactor Univers 2. When creating/configuring a certificate store in Keyfactor Command, you will see a "Change Credentials" link after entering in the destination client machine (IP or DNS). This link **must** be clicked on to present the credentials dialog. However, it is not required that you enter separate credentials. Simply click SAVE in the resulting dialog without entering in credentials to use the credentials that the Keyfactor Orchestrator Service is running under. Alternatively, you may enter separate credentials into this dialog and use those to connect to the orchestrated server. +Please consult with your company's system administrator for more information on configuring SSH/SFTP/SCP or WinRM in your environment. + **SSH Key-Based Authentiation** 1. 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.   @@ -171,7 +176,7 @@ Entry Parameters Tab: - no additional entry parameters   -CURL script to automate certificate store type creation can be found [here](https://github.com/Keyfactor/remote-file-orchestrator/blob/initial-version/Certificate%20Store%20Type%20CURL%20Scripts/PKCS12.curl) +CURL script to automate certificate store type creation can be found [here](Certificate%20Store%20Type%20CURL%20Scripts/PKCS12.curl)     @@ -201,7 +206,7 @@ Entry Parameters Tab: - no additional entry parameters   -CURL script to automate certificate store type creation can be found [here](https://github.com/Keyfactor/remote-file-orchestrator/blob/initial-version/Certificate%20Store%20Type%20CURL%20Scripts/JKS.curl) +CURL script to automate certificate store type creation can be found [here](Certificate%20Store%20Type%20CURL%20Scripts/JKS.curl)     @@ -235,7 +240,7 @@ Entry Parameters Tab: - no additional entry parameters   -CURL script to automate certificate store type creation can be found [here](https://github.com/Keyfactor/remote-file-orchestrator/blob/initial-version/Certificate%20Store%20Type%20CURL%20Scripts/PEM.curl) +CURL script to automate certificate store type creation can be found [here](Certificate%20Store%20Type%20CURL%20Scripts/PEM.curl)     @@ -265,7 +270,7 @@ Entry Parameters Tab: - no additional entry parameters   -CURL script to automate certificate store type creation can be found [here](https://github.com/Keyfactor/remote-file-orchestrator/blob/initial-version/Certificate%20Store%20Type%20CURL%20Scripts/KDB.curl) +CURL script to automate certificate store type creation can be found [here](Certificate%20Store%20Type%20CURL%20Scripts/KDB.curl)     diff --git a/RemoteFile/ApplicationSettings.cs b/RemoteFile/ApplicationSettings.cs index a39f043c..a4d78407 100644 --- a/RemoteFile/ApplicationSettings.cs +++ b/RemoteFile/ApplicationSettings.cs @@ -7,7 +7,7 @@ using Keyfactor.Logging; -namespace Keyfactor.Extensions.Orchestrator.RemoteFile +namespace Keyfactor.Extensions.Orchestrator.RemoteFile { class ApplicationSettings { diff --git a/RemoteFile/Discovery.cs b/RemoteFile/Discovery.cs index e26b0248..1f2bbc82 100644 --- a/RemoteFile/Discovery.cs +++ b/RemoteFile/Discovery.cs @@ -32,7 +32,7 @@ public JobResult ProcessJob(DiscoveryJobConfiguration config, SubmitDiscoveryUpd logger.LogDebug($" {keyValue.Key}: {keyValue.Value}"); } - string[] directoriesToSearch = config.JobProperties["dirs"].ToString().Split(new char[] { ',' }, StringSplitOptions.RemoveEmptyEntries); + string[] directoriesToSearch = config.JobProperties["dirs"].ToString().Split(new char[] { ',' }, StringSplitOptions.RemoveEmptyEntries); string[] extensionsToSearch = config.JobProperties["extensions"].ToString().Split(new char[] { ',' }, StringSplitOptions.RemoveEmptyEntries); string[] ignoredDirs = config.JobProperties["ignoreddirs"].ToString().Split(new char[] { ',' }, StringSplitOptions.RemoveEmptyEntries); string[] filesTosearch = config.JobProperties["patterns"].ToString().Split(new char[] { ',' }, StringSplitOptions.RemoveEmptyEntries); @@ -44,6 +44,7 @@ public JobResult ProcessJob(DiscoveryJobConfiguration config, SubmitDiscoveryUpd try { + certificateStore.Initialize(); ApplicationSettings.Initialize(this.GetType().Assembly.Location); if (directoriesToSearch.Length == 0) diff --git a/RemoteFile/InventoryBase.cs b/RemoteFile/InventoryBase.cs index 94f20a8a..de371977 100644 --- a/RemoteFile/InventoryBase.cs +++ b/RemoteFile/InventoryBase.cs @@ -38,6 +38,7 @@ public JobResult ProcessJob(InventoryJobConfiguration config, SubmitInventoryUpd { ApplicationSettings.Initialize(this.GetType().Assembly.Location); certificateStore = new RemoteCertificateStore(config.CertificateStoreDetails.ClientMachine, config.ServerUsername, config.ServerPassword, config.CertificateStoreDetails.StorePath, config.CertificateStoreDetails.StorePassword, config.JobProperties); + certificateStore.Initialize(); certificateStore.LoadCertificateStore(certificateStoreSerializer, config.CertificateStoreDetails.Properties); List collections = certificateStore.GetCertificateChains(); diff --git a/RemoteFile/ManagementBase.cs b/RemoteFile/ManagementBase.cs index 73991502..9c374ce8 100644 --- a/RemoteFile/ManagementBase.cs +++ b/RemoteFile/ManagementBase.cs @@ -48,6 +48,7 @@ public JobResult ProcessJob(ManagementJobConfiguration config) ApplicationSettings.Initialize(this.GetType().Assembly.Location); certificateStore = new RemoteCertificateStore(config.CertificateStoreDetails.ClientMachine, config.ServerUsername, config.ServerPassword, config.CertificateStoreDetails.StorePath, config.CertificateStoreDetails.StorePassword, config.JobProperties); + certificateStore.Initialize(); PathFile storePathFile = RemoteCertificateStore.SplitStorePathFile(config.CertificateStoreDetails.StorePath); @@ -128,4 +129,4 @@ private void CreateStore(ManagementJobConfiguration config) certificateStore.CreateCertificateStore(config.CertificateStoreDetails.StorePath, linuxFilePermissions); } } -} \ No newline at end of file +} diff --git a/RemoteFile/RemoteCertificateStore.cs b/RemoteFile/RemoteCertificateStore.cs index 7eb691b5..6ca4712a 100644 --- a/RemoteFile/RemoteCertificateStore.cs +++ b/RemoteFile/RemoteCertificateStore.cs @@ -79,8 +79,6 @@ internal RemoteCertificateStore(string server, string serverId, string serverPas } logger.LogDebug("Store path valid"); - Initialize(); - logger.MethodExit(LogLevel.Debug); } @@ -94,8 +92,6 @@ internal RemoteCertificateStore(string server, string serverId, string serverPas ServerPassword = serverPassword ?? string.Empty; ServerType = serverType; - Initialize(); - logger.MethodExit(LogLevel.Debug); } @@ -326,7 +322,7 @@ internal static PathFile SplitStorePathFile(string pathFileName) } } - private void Initialize() + internal void Initialize() { logger.MethodEntry(LogLevel.Debug); diff --git a/RemoteFile/RemoteHandlers/SSHHandler.cs b/RemoteFile/RemoteHandlers/SSHHandler.cs index a6b77b00..f756385c 100644 --- a/RemoteFile/RemoteHandlers/SSHHandler.cs +++ b/RemoteFile/RemoteHandlers/SSHHandler.cs @@ -67,9 +67,16 @@ internal SSHHandler(string server, string serverLogin, string serverPassword) public override void Initialize() { _logger.MethodEntry(LogLevel.Debug); - - sshClient = new SshClient(Connection); - sshClient.Connect(); + + try + { + sshClient = new SshClient(Connection); + sshClient.Connect(); + } + catch (Exception ex) + { + 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); } @@ -163,7 +170,7 @@ public override void UploadCertificateFile(string path, string fileName, byte[] if (ApplicationSettings.FileTransferProtocol == ApplicationSettings.FileTransferProtocolEnum.Both) _logger.LogDebug($"SCP upload failed. Attempting with SFTP protocol..."); else - throw ex; + throw new RemoteFileException("Error attempting SCP file transfer to {Connection.Host} using login {Connection.Username} and connection method {Connection.AuthenticationMethods[0].Name}. Please contact your company's system administrator to verify connection and permission settings.", ex); } finally { @@ -190,7 +197,7 @@ public override void UploadCertificateFile(string path, string fileName, byte[] { _logger.LogError("Exception during SFTP upload..."); _logger.LogError($"Upload Exception: {RemoteFileException.FlattenExceptionMessages(ex, ex.Message)}"); - throw ex; + throw new RemoteFileException("Error attempting SFTP file transfer to {Connection.Host} using login {Connection.Username} and connection method {Connection.AuthenticationMethods[0].Name}. Please contact your company's system administrator to verify connection and permission settings.", ex); } finally { @@ -235,7 +242,7 @@ public override byte[] DownloadCertificateFile(string path) { try { - _logger.LogDebug($"SCP connection attempt to {Connection.Host} using login {Connection.Username} and connection method {Connection.AuthenticationMethods[0].Name}"); + _logger.LogDebug($"SCP connection attempt from {Connection.Host} using login {Connection.Username} and connection method {Connection.AuthenticationMethods[0].Name}"); client.Connect(); using (MemoryStream stream = new MemoryStream()) @@ -252,7 +259,7 @@ public override byte[] DownloadCertificateFile(string path) if (ApplicationSettings.FileTransferProtocol == ApplicationSettings.FileTransferProtocolEnum.Both) _logger.LogDebug($"SCP download failed. Attempting with SFTP protocol..."); else - throw ex; + throw new RemoteFileException($"Error attempting SCP file transfer from {Connection.Host} using login {Connection.Username} and connection method {Connection.AuthenticationMethods[0].Name}. Please contact your company's system administrator to verify connection and permission settings.", ex); } finally { @@ -267,7 +274,7 @@ public override byte[] DownloadCertificateFile(string path) { try { - _logger.LogDebug($"SFTP connection attempt to {Connection.Host} using login {Connection.Username} and connection method {Connection.AuthenticationMethods[0].Name}"); + _logger.LogDebug($"SFTP connection attempt from {Connection.Host} using login {Connection.Username} and connection method {Connection.AuthenticationMethods[0].Name}"); client.Connect(); using (MemoryStream stream = new MemoryStream()) @@ -280,7 +287,7 @@ public override byte[] DownloadCertificateFile(string path) { _logger.LogError("Exception during SFTP download..."); _logger.LogError($"Download Exception: {RemoteFileException.FlattenExceptionMessages(ex, ex.Message)}"); - throw ex; + throw new RemoteFileException($"Error attempting SFTP file transfer from {Connection.Host} using login {Connection.Username} and connection method {Connection.AuthenticationMethods[0].Name}. Please contact your company's system administrator to verify connection and permission settings.", ex); } finally { diff --git a/readme_source.md b/readme_source.md index 98ae3a2d..83234d98 100644 --- a/readme_source.md +++ b/readme_source.md @@ -1,4 +1,4 @@ - + ## 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 @@ -19,12 +19,12 @@ This orchestrator extension makes use of an SSH connection to communicate remote   ## Versioning -The version number of a the Remote File Orchestrator Extension can be verified by right clicking on the n the Extensions/RemoteFile installation folder, selecting Properties, and then clicking on the Details tab. +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.     ## Keyfactor Version Supported -The Remote File Orchestrator Extension has been tested against Keyfactor Universal Orchestrator version 9.5, but should work against earlier or later versions of the Keyfactor Universal Orchestrator. +The Remote File Orchestrator Extension has been tested against Keyfactor Universal Orchestrator version 9.9, but should work against earlier or later versions of the Keyfactor Universal Orchestrator.     ## Security Considerations @@ -45,6 +45,8 @@ The Remote File Orchestrator Extension has been tested against Keyfactor Univers 2. When creating/configuring a certificate store in Keyfactor Command, you will see a "Change Credentials" link after entering in the destination client machine (IP or DNS). This link **must** be clicked on to present the credentials dialog. However, it is not required that you enter separate credentials. Simply click SAVE in the resulting dialog without entering in credentials to use the credentials that the Keyfactor Orchestrator Service is running under. Alternatively, you may enter separate credentials into this dialog and use those to connect to the orchestrated server. +Please consult with your company's system administrator for more information on configuring SSH/SFTP/SCP or WinRM in your environment. + **SSH Key-Based Authentiation** 1. 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.   @@ -136,7 +138,7 @@ Entry Parameters Tab: - no additional entry parameters   -CURL script to automate certificate store type creation can be found [here](https://github.com/Keyfactor/remote-file-orchestrator/blob/initial-version/Certificate%20Store%20Type%20CURL%20Scripts/PKCS12.curl) +CURL script to automate certificate store type creation can be found [here](Certificate%20Store%20Type%20CURL%20Scripts/PKCS12.curl)     @@ -166,7 +168,7 @@ Entry Parameters Tab: - no additional entry parameters   -CURL script to automate certificate store type creation can be found [here](https://github.com/Keyfactor/remote-file-orchestrator/blob/initial-version/Certificate%20Store%20Type%20CURL%20Scripts/JKS.curl) +CURL script to automate certificate store type creation can be found [here](Certificate%20Store%20Type%20CURL%20Scripts/JKS.curl)     @@ -200,7 +202,7 @@ Entry Parameters Tab: - no additional entry parameters   -CURL script to automate certificate store type creation can be found [here](https://github.com/Keyfactor/remote-file-orchestrator/blob/initial-version/Certificate%20Store%20Type%20CURL%20Scripts/PEM.curl) +CURL script to automate certificate store type creation can be found [here](Certificate%20Store%20Type%20CURL%20Scripts/PEM.curl)     @@ -230,7 +232,7 @@ Entry Parameters Tab: - no additional entry parameters   -CURL script to automate certificate store type creation can be found [here](https://github.com/Keyfactor/remote-file-orchestrator/blob/initial-version/Certificate%20Store%20Type%20CURL%20Scripts/KDB.curl) +CURL script to automate certificate store type creation can be found [here](Certificate%20Store%20Type%20CURL%20Scripts/KDB.curl)