This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new de262aec3902 camel-ftp: document sftp paths relative to the login
directory, private keys, legacy algorithms per endpoint and connection errors
(#30056)
de262aec3902 is described below
commit de262aec3902756db29f37c26155623f84feb51e
Author: Federico Mariani <[email protected]>
AuthorDate: Sun Nov 15 19:05:25 2026 +0100
camel-ftp: document sftp paths relative to the login directory, private
keys, legacy algorithms per endpoint and connection errors (#30056)
Co-authored-by: Claude <[email protected]>
---
.../apache/camel/catalog/docs/ftp-component.adoc | 3 +-
.../apache/camel/catalog/docs/sftp-component.adoc | 103 ++++++++++++++++++++-
.../camel/component/file/remote/FtpUtils.java | 8 +-
.../camel-ftp/src/main/docs/ftp-component.adoc | 3 +-
.../camel-ftp/src/main/docs/sftp-component.adoc | 103 ++++++++++++++++++++-
5 files changed, 208 insertions(+), 12 deletions(-)
diff --git
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/ftp-component.adoc
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/ftp-component.adoc
index cb25b8cec464..5e51f1f747a1 100644
---
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/ftp-component.adoc
+++
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/ftp-component.adoc
@@ -41,7 +41,8 @@ ftps://[username@]hostname[:port]/directoryname[?options]
----
Where `directoryname` represents the underlying directory. The directory
-name is a relative path. Absolute path is *not* supported. The
+name is a path relative to the directory the user logs in to, usually its home
directory.
+Absolute path is *not* supported. The
relative path can contain nested folders, such as /inbox/us.
[NOTE]
diff --git
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/sftp-component.adoc
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/sftp-component.adoc
index c611cb9ac867..11169ab95760 100644
---
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/sftp-component.adoc
+++
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/sftp-component.adoc
@@ -36,6 +36,31 @@ include::partial$component-endpoint-headers.adoc[]
== Usage
+=== URI format and paths
+
+----
+sftp://[username@]hostname[:port]/directoryname[?options]
+----
+
+The `directoryname` is relative to the directory the user logs in to, usually
its home directory. For example,
+`sftp://admin@host/inbox` uses the `inbox` directory in the home directory of
`admin`.
+
+Absolute paths are not supported. The component removes the leading slashes,
also from `sftp://host//data/inbox`, and
+logs a WARN: that endpoint uses `data/inbox` under the login directory, not
`/data/inbox`. As both the consumer and the
+producer create a missing directory (`autoCreate=true`, the default), a wrong
path does not fail: the files are read
+from, or written to, a new directory under the login directory.
+
+To use a directory outside the login directory, either:
+
+* create a symbolic link to it in the login directory, and use the link as
`directoryname`, or
+* go up with leading `../` segments, such as `sftp://host/../shared/inbox`,
and set `jailStartingDirectory=false`. With
+ the default `jailStartingDirectory=true`, the consumer skips every file of
such a directory, and the producer refuses
+ to write to it.
+
+For the producer, `directoryname` is the directory to write to, and the file
name comes from the `CamelFileName` header
+or the `fileName` option. A file name that leaves the directory with `../` is
refused unless
+`jailStartingDirectory=false`.
+
=== Security Best Practices: Host Key Verification
WARNING: By default, the SFTP component has `strictHostKeyChecking=no`, which
disables host key verification and makes connections vulnerable to
man-in-the-middle (MITM) attacks. For production environments, you should
enable strict host key checking to ensure you are connecting to the expected
server.
@@ -195,6 +220,26 @@ YAML::
NOTE: When `strictHostKeyChecking=yes` is enabled, Camel's security policy
enforcement framework will not flag this as a security violation. The default
`strictHostKeyChecking=no` may trigger warnings or failures depending on your
configured security policy.
+=== Providing the private key
+
+For public key authentication, set the private key with one of these options:
+
+[cols="1,3"]
+|===
+|Option |Value
+
+|`privateKeyFile` |A path on the file system, such as
`/home/camel/.ssh/id_rsa`.
+|`privateKeyUri` |A resource, loaded from the classpath by default, or from
the file system with the `file:` prefix.
+|`privateKey` |The key as a `byte[]`, usually a bean reference such as
`privateKey=#myKey`.
+|`keyPair` |A `java.security.KeyPair` bean, such as `keyPair=#myKeyPair`.
+|===
+
+Set `privateKeyPassphrase` when the key is encrypted. It applies to
`privateKeyFile`, `privateKeyUri` and `privateKey`.
+
+The key must keep its line breaks. A key whose line breaks were replaced, for
example with spaces when it was copied
+into a one-line property or environment variable, fails with `invalid
privatekey`. Load such a key from a file instead,
+or from a bean that holds the original bytes.
+
=== OpenSSH Certificate Authentication
Camel supports OpenSSH certificate-based authentication for SFTP connections,
where a user's public key is signed by a Certificate Authority (CA) rather than
being individually authorized on the server. This is common in enterprise
environments using tools like HashiCorp Vault or custom CA infrastructure.
@@ -318,9 +363,32 @@ option for the proposal: the `jsch.kex` system property
sets it for the whole JV
=== Restoring Deprecated Key Types and Algorithms
-As of Camel 3.17.0, key types and algorithms that use SHA1 have been
deprecated. These can be restored, if necessary, by setting JSch configuration
directly. E.g.:
+As of Camel 3.17.0, key types and algorithms that use SHA1 are disabled by
default: JSch no longer proposes the `ssh-rsa`
+and `ssh-dss` host keys, `ssh-rsa` signatures for public key authentication,
or SHA1 key exchanges such as
+`diffie-hellman-group14-sha1`. If your server needs them, set them on the
endpoint with these options:
-._Java-only: restoring deprecated JSch key types and algorithms_
+[cols="1,2"]
+|===
+|Option |Algorithms (JSch configuration key)
+
+|`serverHostKeys` |Host keys (`server_host_key`)
+|`publicKeyAcceptedAlgorithms` |Signatures for public key authentication
(`PubkeyAcceptedAlgorithms`)
+|`keyExchangeProtocols` |Key exchange (`kex`)
+|`ciphers` |Ciphers (`cipher.c2s` and `cipher.s2c`)
+|===
+
+Each option replaces the default list of JSch for that endpoint, so list every
algorithm the endpoint may use, the
+preferred one first. For example, for a server that has an RSA host key and
only accepts `ssh-rsa` signatures:
+
+[source,text]
+----
+sftp://host/inbox?username=admin&privateKeyFile=/path/to/id_rsa&serverHostKeys=rsa-sha2-512,rsa-sha2-256,ssh-rsa&publicKeyAcceptedAlgorithms=rsa-sha2-512,rsa-sha2-256,ssh-rsa
+----
+
+The options apply to that endpoint only. Setting the JSch configuration
directly changes the defaults of the whole JVM,
+so of every SFTP endpoint without these options:
+
+._Java-only: restoring deprecated JSch key types and algorithms for the whole
JVM_
[source,java]
----
JSch.setConfig("server_host_key", JSch.getConfig("server_host_key") +
",ssh-rsa");
@@ -335,7 +403,36 @@ command to inspect your server's configuration:
ssh -vvv <server_address>
----
-As of Camel 3.18.1, these values can also be set on SFTP endpoints by setting
the corresponding URI parameters.
+=== Connection errors
+
+When the connection fails, the exception is a
`GenericFileOperationFailedException` with the message
+`Cannot connect to sftp://user@host:port`. The message of its cause, from
JSch, tells what failed:
+
+[cols="2,3"]
+|===
+|Message of the cause |What to check
+
+|`reject HostKey: <host>`
+|With `strictHostKeyChecking=yes`, the known hosts have no key for the server.
Set `knownHostsFile`, `knownHostsUri` or
+`knownHosts` with an entry for the host and port, for example from
`ssh-keyscan -p <port> <host>`. For a port other
+than 22, the entry starts with `[host]:port`.
+
+|`Algorithm negotiation fail: algorithmName="..." jschProposal="..."
serverProposal="..."`
+|JSch and the server have no algorithm in common. Add one that the server
proposes with `serverHostKeys` for
+`server_host_key`, `keyExchangeProtocols` for `kex`, or `ciphers` for
`cipher.c2s` and `cipher.s2c`. See
+<<_restoring_deprecated_key_types_and_algorithms,Restoring Deprecated Key
Types and Algorithms>>.
+
+|`Auth fail for methods '...'`
+|The server refused the credentials: check the username, password or key. With
an RSA key and a server that only
+accepts `ssh-rsa` signatures, add `ssh-rsa` to `publicKeyAcceptedAlgorithms`.
+
+|`invalid privatekey`
+|JSch cannot read the key, for example because its line breaks were lost. See
<<_providing_the_private_key,Providing the private key>>.
+
+|`Incorrect passphrase provided.`
+|`privateKeyPassphrase` does not decrypt the key. In a URI, set a passphrase
with characters such as `+` or `&` as
+`RAW(...)`, see
xref:manual::endpoint.adoc#_configuring_parameter_values_using_raw_values_such_as_passwords[raw
values].
+|===
=== Symbolic links and the starting directory
diff --git
a/components/camel-ftp-common/src/main/java/org/apache/camel/component/file/remote/FtpUtils.java
b/components/camel-ftp-common/src/main/java/org/apache/camel/component/file/remote/FtpUtils.java
index 607651b1bfaf..45f616b3d1ca 100644
---
a/components/camel-ftp-common/src/main/java/org/apache/camel/component/file/remote/FtpUtils.java
+++
b/components/camel-ftp-common/src/main/java/org/apache/camel/component/file/remote/FtpUtils.java
@@ -123,16 +123,16 @@ public final class FtpUtils {
}
/**
- * Checks whether directory used in ftp/ftps/sftp endpoint URI is
relative. Absolute path will be converted to
- * relative path and a WARN will be printed.
+ * Checks whether directory used in ftp/ftps/sftp endpoint URI is
relative. Absolute path will be converted to a
+ * path relative to the login directory and a WARN will be printed.
*
* @see <a href="http://camel.apache.org/ftp2.html">FTP/SFTP/FTPS
Component</a>
*/
public static void ensureRelativeFtpDirectory(Component ftpComponent,
RemoteFileConfiguration configuration) {
if (FileUtil.hasLeadingSeparator(configuration.getDirectoryName())) {
String relativePath =
FileUtil.stripLeadingSeparator(configuration.getDirectoryName());
- LOG.warn("{} doesn't support absolute paths, \"{}\" will be
converted to \"{}\". "
- + "After Camel 2.16, absolute paths will be invalid.",
+ LOG.warn("{} doesn't support absolute paths, \"{}\" will be
converted to \"{}\", "
+ + "which is relative to the login directory.",
ftpComponent.getClass().getSimpleName(),
configuration.getDirectoryName(), relativePath);
configuration.setDirectory(relativePath);
configuration.setDirectoryName(relativePath);
diff --git a/components/camel-ftp/src/main/docs/ftp-component.adoc
b/components/camel-ftp/src/main/docs/ftp-component.adoc
index cb25b8cec464..5e51f1f747a1 100644
--- a/components/camel-ftp/src/main/docs/ftp-component.adoc
+++ b/components/camel-ftp/src/main/docs/ftp-component.adoc
@@ -41,7 +41,8 @@ ftps://[username@]hostname[:port]/directoryname[?options]
----
Where `directoryname` represents the underlying directory. The directory
-name is a relative path. Absolute path is *not* supported. The
+name is a path relative to the directory the user logs in to, usually its home
directory.
+Absolute path is *not* supported. The
relative path can contain nested folders, such as /inbox/us.
[NOTE]
diff --git a/components/camel-ftp/src/main/docs/sftp-component.adoc
b/components/camel-ftp/src/main/docs/sftp-component.adoc
index c611cb9ac867..11169ab95760 100644
--- a/components/camel-ftp/src/main/docs/sftp-component.adoc
+++ b/components/camel-ftp/src/main/docs/sftp-component.adoc
@@ -36,6 +36,31 @@ include::partial$component-endpoint-headers.adoc[]
== Usage
+=== URI format and paths
+
+----
+sftp://[username@]hostname[:port]/directoryname[?options]
+----
+
+The `directoryname` is relative to the directory the user logs in to, usually
its home directory. For example,
+`sftp://admin@host/inbox` uses the `inbox` directory in the home directory of
`admin`.
+
+Absolute paths are not supported. The component removes the leading slashes,
also from `sftp://host//data/inbox`, and
+logs a WARN: that endpoint uses `data/inbox` under the login directory, not
`/data/inbox`. As both the consumer and the
+producer create a missing directory (`autoCreate=true`, the default), a wrong
path does not fail: the files are read
+from, or written to, a new directory under the login directory.
+
+To use a directory outside the login directory, either:
+
+* create a symbolic link to it in the login directory, and use the link as
`directoryname`, or
+* go up with leading `../` segments, such as `sftp://host/../shared/inbox`,
and set `jailStartingDirectory=false`. With
+ the default `jailStartingDirectory=true`, the consumer skips every file of
such a directory, and the producer refuses
+ to write to it.
+
+For the producer, `directoryname` is the directory to write to, and the file
name comes from the `CamelFileName` header
+or the `fileName` option. A file name that leaves the directory with `../` is
refused unless
+`jailStartingDirectory=false`.
+
=== Security Best Practices: Host Key Verification
WARNING: By default, the SFTP component has `strictHostKeyChecking=no`, which
disables host key verification and makes connections vulnerable to
man-in-the-middle (MITM) attacks. For production environments, you should
enable strict host key checking to ensure you are connecting to the expected
server.
@@ -195,6 +220,26 @@ YAML::
NOTE: When `strictHostKeyChecking=yes` is enabled, Camel's security policy
enforcement framework will not flag this as a security violation. The default
`strictHostKeyChecking=no` may trigger warnings or failures depending on your
configured security policy.
+=== Providing the private key
+
+For public key authentication, set the private key with one of these options:
+
+[cols="1,3"]
+|===
+|Option |Value
+
+|`privateKeyFile` |A path on the file system, such as
`/home/camel/.ssh/id_rsa`.
+|`privateKeyUri` |A resource, loaded from the classpath by default, or from
the file system with the `file:` prefix.
+|`privateKey` |The key as a `byte[]`, usually a bean reference such as
`privateKey=#myKey`.
+|`keyPair` |A `java.security.KeyPair` bean, such as `keyPair=#myKeyPair`.
+|===
+
+Set `privateKeyPassphrase` when the key is encrypted. It applies to
`privateKeyFile`, `privateKeyUri` and `privateKey`.
+
+The key must keep its line breaks. A key whose line breaks were replaced, for
example with spaces when it was copied
+into a one-line property or environment variable, fails with `invalid
privatekey`. Load such a key from a file instead,
+or from a bean that holds the original bytes.
+
=== OpenSSH Certificate Authentication
Camel supports OpenSSH certificate-based authentication for SFTP connections,
where a user's public key is signed by a Certificate Authority (CA) rather than
being individually authorized on the server. This is common in enterprise
environments using tools like HashiCorp Vault or custom CA infrastructure.
@@ -318,9 +363,32 @@ option for the proposal: the `jsch.kex` system property
sets it for the whole JV
=== Restoring Deprecated Key Types and Algorithms
-As of Camel 3.17.0, key types and algorithms that use SHA1 have been
deprecated. These can be restored, if necessary, by setting JSch configuration
directly. E.g.:
+As of Camel 3.17.0, key types and algorithms that use SHA1 are disabled by
default: JSch no longer proposes the `ssh-rsa`
+and `ssh-dss` host keys, `ssh-rsa` signatures for public key authentication,
or SHA1 key exchanges such as
+`diffie-hellman-group14-sha1`. If your server needs them, set them on the
endpoint with these options:
-._Java-only: restoring deprecated JSch key types and algorithms_
+[cols="1,2"]
+|===
+|Option |Algorithms (JSch configuration key)
+
+|`serverHostKeys` |Host keys (`server_host_key`)
+|`publicKeyAcceptedAlgorithms` |Signatures for public key authentication
(`PubkeyAcceptedAlgorithms`)
+|`keyExchangeProtocols` |Key exchange (`kex`)
+|`ciphers` |Ciphers (`cipher.c2s` and `cipher.s2c`)
+|===
+
+Each option replaces the default list of JSch for that endpoint, so list every
algorithm the endpoint may use, the
+preferred one first. For example, for a server that has an RSA host key and
only accepts `ssh-rsa` signatures:
+
+[source,text]
+----
+sftp://host/inbox?username=admin&privateKeyFile=/path/to/id_rsa&serverHostKeys=rsa-sha2-512,rsa-sha2-256,ssh-rsa&publicKeyAcceptedAlgorithms=rsa-sha2-512,rsa-sha2-256,ssh-rsa
+----
+
+The options apply to that endpoint only. Setting the JSch configuration
directly changes the defaults of the whole JVM,
+so of every SFTP endpoint without these options:
+
+._Java-only: restoring deprecated JSch key types and algorithms for the whole
JVM_
[source,java]
----
JSch.setConfig("server_host_key", JSch.getConfig("server_host_key") +
",ssh-rsa");
@@ -335,7 +403,36 @@ command to inspect your server's configuration:
ssh -vvv <server_address>
----
-As of Camel 3.18.1, these values can also be set on SFTP endpoints by setting
the corresponding URI parameters.
+=== Connection errors
+
+When the connection fails, the exception is a
`GenericFileOperationFailedException` with the message
+`Cannot connect to sftp://user@host:port`. The message of its cause, from
JSch, tells what failed:
+
+[cols="2,3"]
+|===
+|Message of the cause |What to check
+
+|`reject HostKey: <host>`
+|With `strictHostKeyChecking=yes`, the known hosts have no key for the server.
Set `knownHostsFile`, `knownHostsUri` or
+`knownHosts` with an entry for the host and port, for example from
`ssh-keyscan -p <port> <host>`. For a port other
+than 22, the entry starts with `[host]:port`.
+
+|`Algorithm negotiation fail: algorithmName="..." jschProposal="..."
serverProposal="..."`
+|JSch and the server have no algorithm in common. Add one that the server
proposes with `serverHostKeys` for
+`server_host_key`, `keyExchangeProtocols` for `kex`, or `ciphers` for
`cipher.c2s` and `cipher.s2c`. See
+<<_restoring_deprecated_key_types_and_algorithms,Restoring Deprecated Key
Types and Algorithms>>.
+
+|`Auth fail for methods '...'`
+|The server refused the credentials: check the username, password or key. With
an RSA key and a server that only
+accepts `ssh-rsa` signatures, add `ssh-rsa` to `publicKeyAcceptedAlgorithms`.
+
+|`invalid privatekey`
+|JSch cannot read the key, for example because its line breaks were lost. See
<<_providing_the_private_key,Providing the private key>>.
+
+|`Incorrect passphrase provided.`
+|`privateKeyPassphrase` does not decrypt the key. In a URI, set a passphrase
with characters such as `+` or `&` as
+`RAW(...)`, see
xref:manual::endpoint.adoc#_configuring_parameter_values_using_raw_values_such_as_passwords[raw
values].
+|===
=== Symbolic links and the starting directory