Skip to content

Commit

Permalink
eclipse-ditto#985 document ssh tunneling feature
Browse files Browse the repository at this point in the history 
Signed-off-by: Dominik Guggemos <dominik.guggemos@bosch.io>
  • Loading branch information
@dguggemos
dguggemos committed Mar 26, 2021
1 parent f9e0203 commit d34a43d
Show file tree
Hide file tree
Showing 2 changed files with 188 additions and 1 deletion.
109 changes: 108 additions & 1 deletion documentation/src/main/resources/jsonschema/connection.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -466,7 +466,114 @@
}
},
"additionalProperties": false,
"required": [ "mappingEngine" ]
"required": [
"mappingEngine"
]
}
},
"sshTunnel": {
"$id": "/properties/sshTunnel",
"type": "object",
"additionalProperties": {
"type": "object",
"description": "The configuration of a local SSH port forwarding used to tunnel the connection to the actual endpoint.",
"properties": {
"enabled": {
"$id": "/properties/sshTunnel/properties/enabled",
"type": "boolean",
"title": "Whether the tunnel is enabled.",
"description": "This flag controls whether Ditto establishes an SSH tunnel before connecting to the actual endpoint."
},
"uri": {
"$id": "/properties/sshTunnel/properties/uri",
"type": "string",
"title": "SSH host",
"description": "The URI of the SSH host."
},
"credentials": {
"$id": "/properties/sshTunnel/properties/credentials",
"type": "object",
"title": "Credentials",
"description": "Credentials with which Ditto authenticates itself at the SSH host.",
"properties": {
"type": {
"$id": "/properties/sshTunnel/properties/credentials/properties/type",
"type": "string",
"enum": [
"password",
"public-key"
],
"title": "Type of credentials",
"description": "Type of credentials",
"examples": [
"password",
"public-key"
]
},
"username": {
"$id": "/properties/sshTunnel/properties/credentials/properties/username",
"type": "string",
"title": "The username user for authentication.",
"description": "A valid username.",
"examples": [
"tunnel-user"
]
},
"password": {
"$id": "/properties/sshTunnel/properties/credentials/properties/password",
"type": "string",
"title": "The password for authentication.",
"description": "A valid password. Only required for type `password`.",
"examples": [
"*****"
]
},
"publicKey": {
"$id": "/properties/sshTunnel/properties/credentials/properties/publicKey",
"type": "string",
"title": "Public key for credentials type `public-key`.",
"description": "Public key for type `public-key` in PEM-format.",
"examples": [
"-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"
]
},
"privateKey": {
"$id": "/properties/sshTunnel/properties/credentials/properties/privateKey",
"type": "string",
"title": "Private key for credentials type `public-key`.",
"description": "Unencrypted private key for type `public-key` as PKCS8 in PEM-format.",
"examples": [
"-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
]
}
}
},
"validateHost": {
"$id": "/properties/sshTunnel/properties/validateHost",
"type": "boolean",
"title": "Whether the SSH host is verified.",
"description": "This flag controls whether Ditto verifies the SSH host used for tunneling by chacking the public key provided by the host against the given public key fingerprints."
},
"knownHosts": {
"$id": "/properties/sshTunnel/properties/knownHosts",
"type": "array",
"title": "A list of accepted fingerprints.",
"description": "One of these fingerprints must match the fingerprint of the public key the SSH host provides.",
"uniqueItems": true,
"items": {
"$id": "/properties/sshTunnel/properties/knownHosts/items",
"type": "string",
"title": "Fingerprint",
"description": "A public key fingerprint in the format the command line tool `ssh-keygen` produces, e.g. `MD5:e0:3a:34:1c:68:ed:c6:bc:7c:ca:a8:67:c7:45:2b:19`. The fingerprint is prefixed with the hash algorithm used to calculate the fingerprint. Supported algorithms are `MD5`, `SHA1`, `SHA224`, `SHA256`, `SHA384` and `SHA512`"
},
"additionalProperties": false,
"required": [
"enabled",
"uri",
"credentials"
]
}
}
}
}
},
Expand Down
80 changes: 80 additions & 0 deletions documentation/src/main/resources/pages/ditto/basic-connections.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -486,3 +486,83 @@ Sending live commands and events to a target address that contains the thing's n
]
}
```

## SSH tunneling

A connection supports establishing an SSH tunnel which is then used to connect to the actual target endpoint. This
is useful when the target endpoint is not directly accessible but only via SSH. For this purpose the connection
configuration must specify the `sshTunnel` section, which contains the necessary
information to establish a local SSH port forwarding. The tunneling supports password and public key authentication and
host validation using public key fingerprints. If the tunnel is enabled the connection will establish an SSH
tunnel and afterwards use this tunnel to connect to the actual endpoint.

The example below establishes an SSH tunnel via `ssh-host:2222` to the remote endpoint
`tcp://mqtt. eclipseprojects.io:1883`, using plain authentication and enabled host validation:

```json
{
"name": "tunneled-connection",
"connectionType": "mqtt",
"uri": "tcp://mqtt.eclipseprojects.io:1883",
"sources": [{ ... }],
"sshTunnel": {
"enabled": true,
"uri": ,
"credentials": {
"type": "plain",
"username": "username",
"password": "password"
},
"validateHost": true,
"knownHosts": ["MD5:e0:3a:34:1c:68:ed:c6:bc:7c:ca:a8:67:c7:45:2b:19"]
}
}
```

### Public key authentication

An SSH tunnel can also be authenticated using public key authentication. The credentials provided in the SSH tunnel
configuration must then be of the type `public-key`:
```json
...
"credentials": {
"type": "public-key",
"username": "username",
"publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9.....\n-----END PUBLIC KEY-----",
"privateKey": "-----BEGIN PRIVATE KEY-----\nMIIEvAIBADANBgkqhki....\n-----END PRIVATE KEY-----"
}
...
```

The public key must be provided as PEM-encoded key in `X.509` format.
The private key must be provided as PEM-encoded key in unencrypted `PKCS8` format as specified by [RFC-7468](https://tools.ietf.org/html/rfc7468).

The following command can be used to convert a standard OpenSSL key in PKCS1 format to the PKCS8 format accepted by
Ditto:
```
openssl pkcs8 -topk8 -nocrypt -in client-private.pem.key -out client-private.pem.pk8
```

### SSH host validation

{% include note.html content="It is highly recommended enabling host validation for productive systems, it should
only be disabled for testing purposes." %}

The accepted fingerprints can be provided in the format the standard command line tool `ssh-keygen` produces.

Example:
```
MD5:e0:3a:34:1c:68:ed:c6:bc:7c:ca:a8:67:c7:45:2b:19
```
The fingerprints are prefixed with an alias of the hash algorithm that was used to calucate the fingerprint. Ditto
supports the following hash algorithms for public key fingerprints: `MD5`, `SHA1`, `SHA224`, `SHA256`, `SHA384` and `SHA512`.

Assuming the file `id_rsa.pub` contains the public key the following command produces a valid fingerprint that
can be used in the SSH tunnel configuration:
```
ssh-keygen -lf id_rsa.pub -E md5
```
Or in case the public key is given in PKCS8 format:
```
ssh-keygen -lf id_rsa.pub.pkcs8 -m PKCS8 -E md5
```

0 comments on commit d34a43d

Please sign in to comment.