Merge pull request #2589 from mulesoft/feature/W-14557165

W-14557165: Updated User flows for overriding security configuration through file

sftp/2.1/modules/ROOT/pages/sftp-connector-troubleshooting.adoc

@@ -24,7 +24,7 @@ To resolve this error:
 
 * Try to replicate the issue using an SFTP client, for example, Cyberduck or Filezilla. If the issue also occurs with these clients, then it is likely that the issue is not related to the Mule app.
 
-* Get better and more detailed logs on the Mule app side by enabling verbose logging for SFTP Connector and for the JSCH driver:
+* Get better and more detailed logs on the Mule app side by enabling verbose logging for SFTP Connector and for the library Apache Mina:
 +
 . Access Anypoint Studio and navigate to the *Package Explorer* view.
 . Open your application's project name.
@@ -35,7 +35,7 @@ To resolve this error:
 [source,xml,linenums]
 ----
     <AsyncLogger name=“org.mule.extension.sftp” level=“TRACE”/>
-    <AsyncLogger name=“com.jcraft.jsch” level=“DEBUG”/>
+    <AsyncLogger name=“org.apache.sshd” level=“DEBUG”/>
 ----
 [start=6]
 . Add the following argument to your run configuration:
@@ -97,7 +97,11 @@ Here is a list of common throws messages and how to interpret them.
 
  The app made too many failed login attempts to a server. This can result from multiple causes, but the most common one is invalid credentials.
 
- * FILE_DOESNT_EXIST
+* SFTP:KEY_EXCHANGE_FAILED
+
+ The app tried to make an SSH connection to the server, but failed in the key exchange step. Failure may occur during the negotiation or later steps in the key exchange.
+
+* FILE_DOESNT_EXIST
 
   The file to write was deleted.
 

sftp/2.1/modules/ROOT/pages/sftp-connector-upgrade-guide.adoc

@@ -15,11 +15,11 @@ Upgrade Anypoint Connector for SFTP (SFTP Connector) to version 2.x.x.
 This release contains the following changes:
 
 * The system property `mule.sftp.useHomeDirectory` was removed. SFTP Connector now uses the default home directory.
-* SFTP Connector 2.0.0 no longer supports the `jcraft library`. The connector now uses the `apache mina sshd` library.
-* Apache Mina does not support S3 SFTP Server on SFTP Connector 2.0.0.
+* SFTP Connector 2.x.x no longer supports the `jcraft library`. The connector now uses the `apache mina sshd` library.
+* Apache Mina does not support S3 SFTP Server on SFTP Connector 2.x.x.
 * The *List* operation no longer fetches the content of each file. Now, the payload of each list item contains the complete path to the found file or directory. 
 * The SFTP *Regular Size* file attribute is renamed to *Regular File* because its behavior is not related to size. The file attribute value can be a file (`true`) or a directory (`false`).
-* SFTP Connector 2.0.0 does not support ciphers `3des-ctr` and `arcfour`. For more information, refer to <<supported-ciphers,Supported Ciphers project>>.
+* SFTP Connector 2.x.x does not support ciphers `3des-ctr` and `arcfour`. For more information, refer to <<supported-ciphers,Supported Ciphers project>>.
 * The SFTP proxy protocol works only with HTTP and SOCKS5.
 * SFTP Connector no longer uses `javax.activation` to resolve the media types of the files. The connector now uses `Apache Tika`, which can result in different media file interpretations.
 * The connector changed the classes to manage the date from `LocalDateTime` to `ZonedDateTime`.
@@ -98,7 +98,7 @@ Follow these steps to perform the upgrade:
 . In *Add Dependencies to Project*, enter `SFTP` in the search field.
 . In *Available modules*, select *SFTP Connector* and click *Add*.
 . Click *Finish*.
-. Verify that the SFTP Connector `mule-sftp-connector` version is `2.0.0` in the `pom.xml` file in the Mule project.
+. Verify that the SFTP Connector `mule-sftp-connector` version is `2.x.x` in the `pom.xml` file in the Mule project.
 
 Studio upgrades the connector automatically.
 
@@ -154,14 +154,47 @@ For details, review the following table:
 | Not supported. |`cc20p1305_openssh`
 |===
 
+[[supported-cryptographic-entities]]
+== Other Supported Cryptographic Entities
+
+[%header]
+|===
+|Kex Algorithms|Host Key Algorithms|MACs
+|`curve25519-sha256`*|`[email protected]`|`[email protected]`
+|`[email protected]`*|`[email protected]`|`[email protected]`
+|`curve448-sha512`*|`[email protected]`|`[email protected]`
+|`ecdh-sha2-nistp521`|`[email protected]`|`hmac-sha2-256`
+|`ecdh-sha2-nistp384`|`[email protected]`|`hmac-sha2-512`
+|`ecdh-sha2-nistp256`|`[email protected]`|`hmac-sha1`
+|`diffie-hellman-group-exchange-sha256`|`ecdsa-sha2-nistp256`|`hmac-md5` (Deprecated)
+|`diffie-hellman-group18-sha512`|`ecdsa-sha2-nistp384`|`hmac-md5-96` (Deprecated)
+|`diffie-hellman-group17-sha512`|`ecdsa-sha2-nistp521`|`hmac-sha1-96` (Deprecated)
+|`diffie-hellman-group16-sha512`|`ssh-ed25519`**|
+|`diffie-hellman-group15-sha512`|`[email protected]`|
+|`diffie-hellman-group14-sha256`|`[email protected]`**|
+|`diffie-hellman-group1-sha1` (Deprecated)|`rsa-sha2-512`|
+|`diffie-hellman-group14-sha1` (Deprecated)|`rsa-sha2-256`|
+|`diffie-hellman-group-exchange-sha1` (Deprecated)|`ssh-rsa`|
+||`ssh-dss` (Deprecated)|
+||`[email protected]` (Deprecated)|
+||`[email protected]` (Deprecated)|
+|===
+
+`*` These algorithms require Bouncy Castle on Java versions before Java 11. +
+
+`**` These algorithms require externally EdDSA (Edwards-curve Digital Signature Algorithm) library.
+
 == Troubleshooting
 
 // If there are common known issues and errors that occur when upgrading, give troubleshooting tips.
 
 === Reverting the Upgrade
 
-If you need to revert to the previous version of SFTP Connector, go to Anypoint Studio and in the project’s `pom.xml` file, change the `mule-sftp-connector` dependency version 2.0.0 to the previous version.
+If you need to revert to the previous version of SFTP Connector, go to Anypoint Studio and in the project’s `pom.xml` file, change the `mule-sftp-connector` dependency version 2.x.x to the previous version.
+
+=== Override SSH Connection Security Configuration
 
+If you face SSH connection issues due to unsupported ciphers, macs, hostKeyAlgorithms or kexAlgorithms, then change the priority or enable deprecated ciphers and algorithms forcefully. Although using this method may introduce additional risk. Refer to xref:sftp-security-configuration-override.adoc[Configure Security Parameters of SSH Connection] and xref:sftp-documentation.adoc[SFTP Connector Reference].
 
 == See Also
 

sftp/2.1/modules/ROOT/pages/sftp-documentation.adoc

@@ -92,6 +92,7 @@ ssh-keygen's OpenSSH PKI format is not accepted. You can use argument "-m PEM".
 * SHA1PRNG
 * NativePRNGBlocking
 * NativePRNGNonBlocking |  The Pseudo Random Number Generator Algorithm to use. |  AUTOSELECT |
+| Security Configuration a| <<SecurityConfiguration>> | Provides support to override security related configurations like Ciphers, MACs, Kex Algorithms, etc. |  |
 | Reconnection a| <<Reconnection>> |  When the application is deployed, a connectivity test is performed on all connectors. If set to `true`, deployment fails if the test doesn't pass after exhausting the associated reconnection strategy. |  |
 | Pooling Profile a| <<PoolingProfile>> |  Characteristics of the connection pool. |  |
 |===
@@ -517,6 +518,29 @@ You can disable this feature by omitting a value.  |  |
 * SOCKS5 |  |  | x
 |===
 
+[[SecurityConfiguration]]
+=== Security Configuration
+
+Configuring security settings using the SSH Config Override File means you accept the https://docs.mulesoft.com/connectors/introduction/connectors-shared-responsibilities[shared responsibilities] documentation.
+
+[%header,cols="20s,25a,30a,15a,10a"]
+|===
+| Field | Type | Description | Default Value | Required
+| SSH Config Override File a| String | Path to the file with the SSH override configurations. It supports the following configs:
+
+* `KexAlgorithms` +
+Specifies the comma separated list of key exchange algorithms.
+* `Ciphers` +
+Specifies the comma separated list of symmetric ciphers.
+* `HostKeyAlgorithms` +
+Specifies the comma separated list of host key signature algorithms.
+* `MACs` +
+Specifies the comma separated list of message authentication codes.
+
+You define the keys in the file you need to override, defaults are taken for the remaining keys.
+|  |
+|===
+
 [[Reconnection]]
 === Reconnection
 

sftp/2.1/modules/ROOT/pages/sftp-examples.adoc

@@ -22,6 +22,8 @@ Configure SFTP Connector to connect dynamically to multiple servers.
 Disable connection pooling in SFTP Connector configuration to make sure no connection is active if there is nothing to transfer.
 * xref:sftp-preferred-authentication.adoc[Configure Preferred Authentication ] +
 Configure the preferred authentication for the SFTP Connection.
+* xref:sftp-security-configuration-override.adoc[Configure Security Parameters of SSH Connection] +
+Override default security configuration of SSH Connection.
 
 == See Also
 

sftp/2.1/modules/ROOT/pages/sftp-security-configuration-override.adoc

@@ -0,0 +1,64 @@
+= Configure Security Parameters of SSH Connection
+
+The following example shows how to configure the Anypoint Connector for SFTP (SFTP Connector) to override security parameters using Anypoint Studio.
+
+== Create a Configuration Override File
+
+Follow these steps to create the file:
+
+. Navigate to your `src/main/resources` folder.
+. Create a config file, for example, `mule_sshd_config` with the following SSHD content. The file follows the format of an `sshd_config` file:
++
+[source,xml,linenums]
+----
+KexAlgorithms ecdh-sha2-nistp521,ecdh-sha2-nistp384,ecdh-sha2-nistp256,diffie-hellman-group18-sha512,diffie-hellman-group17-sha512,diffie-hellman-group16-sha512,diffie-hellman-group14-sha256
+Ciphers aes128-cbc,aes128-ctr,aes192-cbc,aes192-ctr,aes256-cbc,aes256-ctr
+HostKeyAlgorithms ssh-rsa,rsa-sha2-256,rsa-sha2-512
+MACs hmac-sha1,hmac-sha2-256,hmac-sha2-512
+----
+image::sftp-override-config-file-contents.png[Contents of the override config file]
+
+[start=3]
+. Configure the keys and values accordingly. If you do not provide a key, then default values are used.
+
+The following example shows the location of the config file within  the `src/main/resources` folder:
+
+image::sftp-override-config-file-location.png[Location of the override config file]
+
+== Configure the Override File in Anypoint Studio
+
+Follow these steps to configure the override file:
+
+. In Studio, navigate to the *Global Elements* tab.
+. In the Choose Global Type window, type `sftp` in the search bar.
+. Select *SFTP Config*.
+. Click *OK*.
+. Go to the *Advanced* tab.
+. Under *Security Configuration*, enter `ssh config override file`.
+. Enter the path to the file, for example: `${app.home}/mule_sshd_config`.
+. Complete the remaining connection fields.
+. Click *Test Connection...*.
+. Click *OK*.
+
+image::sftp-override-security-parameters.png[SFTP Configuration with preferred authentication field set to GSSAPI_WITH_MIC]
+
+In the *Configuration XML* editor window, the configuration looks like this:
+
+[source,xml,linenums]
+----
+<sftp:config name="SFTP_Config" doc:name="SFTP Config" >
+    <sftp:connection host="localhost" sshConfigOverride="${app.home}/mule_sshd_config">
+    </sftp:connection>
+</sftp:config>
+----
+
+== Verify the Override File Creation
+
+Consider the following points when verifying the file creation:
+
+* Search for the log `Read the config file` and verify that the filename and the configuration values fetched from the file are valid.
+* Find ignored configs with the log line `Config keys found but ignored`.
+* Check that if the connector is unable to locate the file, then it logs `Couldn't locate config file`.
+
+== See Also
+* xref:sftp-examples.adoc[]