CAMEL-25644: camel-ssh - match known_hosts entries by exact host pattern

catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/components/ssh.json

@@ -47,11 +47,11 @@
     "certResource": { "index": 19, "kind": "property", "displayName": "Cert Resource", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Sets the resource path of the certificate to use for Authentication. Will use ResourceHelperKeyPairProvider to resolve file based certificate, and depends on keyType setting." },
     "certResourcePassword": { "index": 20, "kind": "property", "displayName": "Cert Resource Password", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": true, "security": "secret", "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Sets the password to use in loading certResource, if certResource is an encrypted key." },
     "ciphers": { "index": 21, "kind": "property", "displayName": "Ciphers", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Comma-separated list of allowed\/supported ciphers in their order of preference." },
-    "failOnUnknownHost": { "index": 22, "kind": "property", "displayName": "Fail On Unknown Host", "group": "security", "label": "security", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "security": "insecure:ssl", "insecureValue": "false", "defaultValue": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Specifies whether a connection to an unknown SSH server host key should fail. When false, host keys that are not present in the known_hosts resource are accepted." },
+    "failOnUnknownHost": { "index": 22, "kind": "property", "displayName": "Fail On Unknown Host", "group": "security", "label": "security", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "security": "insecure:ssl", "insecureValue": "false", "defaultValue": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Specifies whether a connection to a server whose host has no entry without a marker in the known_hosts resource should fail. When false, such a server is accepted. A server whose host has entries without a marker is always rejected when it presents a key that none of them lists, and a key listed in a matching revoked entry is always rejected." },
     "kex": { "index": 23, "kind": "property", "displayName": "Kex", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Comma-separated list of allowed\/supported key exchange algorithms in their order of preference." },
     "keyPairProvider": { "index": 24, "kind": "property", "displayName": "Key Pair Provider", "group": "security", "label": "security", "required": false, "type": "object", "javaType": "org.apache.sshd.common.keyprovider.KeyPairProvider", "deprecated": false, "autowired": false, "secret": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Sets the KeyPairProvider reference to use when connecting using Certificates to the remote SSH Server." },
     "keyType": { "index": 25, "kind": "property", "displayName": "Key Type", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Sets the key type to pass to the KeyPairProvider as part of authentication. KeyPairProvider.loadKey(...) will be passed this value. From Camel 3.0.0 \/ 2.25.0, by default Camel will select the first available KeyPair that is loaded. Prior to this, a KeyType of 'ssh-rsa' was enforced by default." },
-    "knownHostsResource": { "index": 26, "kind": "property", "displayName": "Known Hosts Resource", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "security": "insecure:ssl", "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Sets the resource path for a known_hosts file used to verify the SSH server host key. When not set, the client does not verify the server host key against a known_hosts file." },
+    "knownHostsResource": { "index": 26, "kind": "property", "displayName": "Known Hosts Resource", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "security": "insecure:ssl", "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Sets the resource path for a known_hosts file used to verify the SSH server host key. The file uses the OpenSSH known_hosts format, and its entries are matched against the host and port configured on the endpoint. A resource that cannot be read, or that has a line that cannot be read, makes every connection fail. When not set, the client does not verify the server host key against a known_hosts file." },
     "macs": { "index": 27, "kind": "property", "displayName": "Macs", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Comma-separated list of allowed\/supported message authentication code algorithms in their order of preference. The MAC algorithm is used for data integrity protection." },
     "password": { "index": 28, "kind": "property", "displayName": "Password", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": true, "security": "secret", "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Sets the password to use in connecting to remote SSH server. Requires keyPairProvider to be set to null." },
     "signatures": { "index": 29, "kind": "property", "displayName": "Signatures", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Comma-separated list of allowed\/supported signature algorithms in their order of preference." },
@@ -102,11 +102,11 @@
     "certResource": { "index": 35, "kind": "parameter", "displayName": "Cert Resource", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Sets the resource path of the certificate to use for Authentication. Will use ResourceHelperKeyPairProvider to resolve file based certificate, and depends on keyType setting." },
     "certResourcePassword": { "index": 36, "kind": "parameter", "displayName": "Cert Resource Password", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": true, "security": "secret", "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Sets the password to use in loading certResource, if certResource is an encrypted key." },
     "ciphers": { "index": 37, "kind": "parameter", "displayName": "Ciphers", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Comma-separated list of allowed\/supported ciphers in their order of preference." },
-    "failOnUnknownHost": { "index": 38, "kind": "parameter", "displayName": "Fail On Unknown Host", "group": "security", "label": "security", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "security": "insecure:ssl", "insecureValue": "false", "defaultValue": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Specifies whether a connection to an unknown SSH server host key should fail. When false, host keys that are not present in the known_hosts resource are accepted." },
+    "failOnUnknownHost": { "index": 38, "kind": "parameter", "displayName": "Fail On Unknown Host", "group": "security", "label": "security", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "security": "insecure:ssl", "insecureValue": "false", "defaultValue": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Specifies whether a connection to a server whose host has no entry without a marker in the known_hosts resource should fail. When false, such a server is accepted. A server whose host has entries without a marker is always rejected when it presents a key that none of them lists, and a key listed in a matching revoked entry is always rejected." },
     "kex": { "index": 39, "kind": "parameter", "displayName": "Kex", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Comma-separated list of allowed\/supported key exchange algorithms in their order of preference." },
     "keyPairProvider": { "index": 40, "kind": "parameter", "displayName": "Key Pair Provider", "group": "security", "label": "security", "required": false, "type": "object", "javaType": "org.apache.sshd.common.keyprovider.KeyPairProvider", "deprecated": false, "autowired": false, "secret": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Sets the KeyPairProvider reference to use when connecting using Certificates to the remote SSH Server." },
     "keyType": { "index": 41, "kind": "parameter", "displayName": "Key Type", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Sets the key type to pass to the KeyPairProvider as part of authentication. KeyPairProvider.loadKey(...) will be passed this value. From Camel 3.0.0 \/ 2.25.0, by default Camel will select the first available KeyPair that is loaded. Prior to this, a KeyType of 'ssh-rsa' was enforced by default." },
-    "knownHostsResource": { "index": 42, "kind": "parameter", "displayName": "Known Hosts Resource", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "security": "insecure:ssl", "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Sets the resource path for a known_hosts file used to verify the SSH server host key. When not set, the client does not verify the server host key against a known_hosts file." },
+    "knownHostsResource": { "index": 42, "kind": "parameter", "displayName": "Known Hosts Resource", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "security": "insecure:ssl", "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Sets the resource path for a known_hosts file used to verify the SSH server host key. The file uses the OpenSSH known_hosts format, and its entries are matched against the host and port configured on the endpoint. A resource that cannot be read, or that has a line that cannot be read, makes every connection fail. When not set, the client does not verify the server host key against a known_hosts file." },
     "macs": { "index": 43, "kind": "parameter", "displayName": "Macs", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Comma-separated list of allowed\/supported message authentication code algorithms in their order of preference. The MAC algorithm is used for data integrity protection." },
     "password": { "index": 44, "kind": "parameter", "displayName": "Password", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": true, "security": "secret", "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Sets the password to use in connecting to remote SSH server. Requires keyPairProvider to be set to null." },
     "signatures": { "index": 45, "kind": "parameter", "displayName": "Signatures", "group": "security", "label": "security", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "configurationClass": "org.apache.camel.component.ssh.SshConfiguration", "configurationField": "configuration", "description": "Comma-separated list of allowed\/supported signature algorithms in their order of preference." },

catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/ssh-component.adoc

@@ -163,6 +163,72 @@ YAML::
 An example of using Public Key authentication is provided in
 `examples/camel-example-ssh-security`.
 
+=== Server host key verification
+
+The SSH Component verifies the host key of the SSH server only when the `knownHostsResource` option
+is set. It refers to a file in the OpenSSH `known_hosts` format, such as the output of `ssh-keyscan`.
+Set `failOnUnknownHost` to `true` as well, so that a server without any entry in that file is rejected.
+When it is `false` (the default), such a server is accepted and a warning is logged.
+
+The entries are matched as OpenSSH matches them:
+
+* Each host pattern of an entry is compared, ignoring case, with the host name or address the client
+connects to: the host configured on the endpoint, or the `HostName` that `~/.ssh/config` gives for it.
+It is written `host` for port 22 and `[host]:port` for another port. `*` and `?` are wildcards, a
+pattern starting with `!` excludes the hosts it matches, and hashed entries are supported. So
+`db.example.com` only applies to port 22, `[db.example.com]:2222` to port 2222, and `*` to every host
+and port. The host is never resolved: an endpoint configured with an address only uses the entries for
+that address, and an IPv6 address such as `::1` is not expanded.
+* The server is accepted when an entry of its host lists the key it presents. A host can be listed
+with several keys, one per line.
+* The server is rejected when the key it presents is listed in a matching `@revoked` entry, or when
+its host has entries without a marker but none of them lists that key, whatever the value of
+`failOnUnknownHost`. That option only decides for a host without such an entry: `@revoked` and
+`@cert-authority` entries do not list a host.
+* `@cert-authority` entries (OpenSSH host certificates) are not supported and are ignored.
+* A `known_hosts` resource that cannot be read, or that has a line that cannot be read (for example
+an unknown `@` marker, a missing key, or a key that is not valid base64), makes every connection fail.
+
+The following route verifies the host key of a server listening on port 2222 against a
+`known_hosts` file that contains the line `[db.example.com]:2222 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5...`.
+
+[tabs]
+====
+Java::
++
+[source,java]
+----
+from("direct:status")
+    .to("ssh://scott@db.example.com:2222?certResource=classpath:test_rsa&knownHostsResource=file:/etc/camel/known_hosts&failOnUnknownHost=true");
+----
+
+XML::
++
+[source,xml]
+----
+<route>
+  <from uri="direct:status"/>
+  <to uri="ssh://scott@db.example.com:2222?certResource=classpath:test_rsa&amp;knownHostsResource=file:/etc/camel/known_hosts&amp;failOnUnknownHost=true"/>
+</route>
+----
+
+YAML::
++
+[source,yaml]
+----
+- route:
+    from:
+      uri: direct:status
+      steps:
+        - to:
+            uri: ssh://scott@db.example.com:2222
+            parameters:
+              certResource: "classpath:test_rsa"
+              knownHostsResource: "file:/etc/camel/known_hosts"
+              failOnUnknownHost: true
+----
+====
+
 [[SSH-CertificateDependencies]]
 === Certificate Dependencies