https://github.com/sshtools/dbus-java-transport-ssh
An extension to dbus-java that allows connection to a remote DBus broker over SSH
https://github.com/sshtools/dbus-java-transport-ssh
Last synced: about 1 year ago
JSON representation
An extension to dbus-java that allows connection to a remote DBus broker over SSH
- Host: GitHub
- URL: https://github.com/sshtools/dbus-java-transport-ssh
- Owner: sshtools
- License: lgpl-2.1
- Created: 2022-07-21T21:35:32.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-03-06T14:11:19.000Z (over 1 year ago)
- Last Synced: 2025-04-15T20:14:18.820Z (about 1 year ago)
- Language: Java
- Size: 50.8 KB
- Stars: 3
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# dbus-java-transport-ssh
An extension to [DBus Java](https://github.com/hypfvieh/dbus-java) that allows connection to a remote [DBus](https://en.wikipedia.org/wiki/D-Bus) broker over [SSH](https://en.wikipedia.org/wiki/Secure_Shell). It supports both TCP and Unix domain sockets on the remote side. It uses [Maverick Synergy](https://jadaptive.com/en/products/open-source-java-ssh) for unix domain socket support directly. In this case, a real local domain socket file will not need to be created, eliminating another layer and further decreasing latency.
A DBus Java transport works with `SocketChannel`, so we must be able to access a `SocketChannel` from Maverick Synergy that is on the other end of the SSH session connected to a unix domain socket (or TCP socket) served by a DBus broker. This is achieved by extending Synergy's built in unix domain socket support to provide us with such a channel.
#### Usage
Simply add the `dbus-java-transport-ssh` module to your POM (or other build descriptor).
```xml
com.sshtools
dbus-java-transport-ssh
0.9.9
```
**For SNAPSHOT version, you will need to add the OSS SNapshots Repository**
```xml
oss-snapshots
https://oss.sonatype.org/content/repositories/snapshots
false
```
Now choose the appropriate Bus path.
```java
var address = "ssh:path=/path/to/dbus.socket,username=joeb,via=ssh.acme.com,viaPort=22,password=changeit";
var builder = DBusConnectionBuilder.forAddress(address);
// Add further configuration here, see below
var connection = builder.build();
```
The transport supports both TCP and Unix Domain Socket tunnels. The above syntax (with a `path` parameter) initiates a unix domain socket tunnel.
The supported parameters are :-
* `via`. The hostname or IP address of the SSH server to connect to.
* `viaPort`. The port on which the server is listening, if different from the default of 22.
* `path`. The path to the domain socket on the remote side. If this is provided, a unix domain socket tunnel will be used.
* `host`. The target host on the remote side where the DBus broker is running. This defaults to `localhost` (i.e. the remote host itself). If this is provided, a TCP socket tunnel will be used.
* `port`. The target port of the DBus broker on the remote side. Only relevant if `host` is provided.
* `username`. The username to authenticate as on the SSH server.
* `password`. The password to use for authentication. **Note, this is not recommended. See the Authentication section below.**
* `key`. The path to a private key file to use instead of a password.
* `passphrase`. If file pointed to by `key` above is passphrase protected, this parameter should specify the password. **Note, this is not recommended. See the Authentication section below.**
##### SSH Configuration
You may have further SSH configuration requirements, such as setting preferred ciphers, keys,
compression, host key authentication and more.
This is achieved by accessing the `SshClientContext` Synergy provides. You must pass in
the `TransportConfig` from the `DBusConnectionBuilder`.
```java
SshTransport.setContextConfigurator((ctx) -> {
ctx.setHostKeyVerification((host, key) -> {
// TODO Check 'key' here for validity for the host
return true;
});
return ctx;
}, builder.transportConfig());
```
See the Maverick Synergy [documentation](https://jadaptive.com/app/manpage/agent/category/1564757) for more information on configuration.
##### SSH Authentication
Rather than provide sensitive information such as passwords or passphrases in the address string,
you can again directly access the transport and configure a custom authenticator. You must pass in
the `TransportConfig` from the `DBusConnectionBuilder`.
```java
SshTransport.setAuthenticationConfigurator(
(auths) -> Arrays.asList(new PasswordAuthenticator(() -> "changeme")),
builder.transportConfig());
```
##### Providing Your Own Client
You can be in entirely in control of the creation of the client by using `SshTransport.setClient()`.
You must pass in the `TransportConfig` from the `DBusConnectionBuilder`.
```java
SshTransport.setClient(() -> {
return SshClientBuilder.create().
withTarget("yourhost", 22).
withUsername("joeb").
withSshContext(SshTransport.createClientContext()).
withAuthenticators(new PasswordAuthenticator("asecret")).
onConfigure((cctx) -> {
cctx.getForwardingPolicy().allowForwarding();
cctx.getForwardingPolicy().add(ForwardingPolicy.UNIX_DOMAIN_SOCKET_FORWARDING);
}).
build();
}, builder.transportConfig());
```
See the Maverick Synergy [documentation](https://jadaptive.com/app/manpage/agent/category/1564757) for more information on authentication.
##### DBus Authentication
DBus itself has it's own authentication layer that uses [SASL](https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer).
The SSH transport uses the `EXTERNAL` mechanism. Part of the SASL handshake includes the **UID** of the calling user. The DBus broker checks if the UID matches that of the connection it accepted, and will reject the connection if they do not match.
In the case of an SSH connection, the UID of the local user may be totally different to the UID of the remote user. To overcome this, you must know up-front the UID of the remote user, and provide it when configuring the local DBus connection.
```java
builder.transportConfig().configureSasl().withSaslUid(1000);
```