Skip to content

Home

Jump to bottom
Ralph Plawetzki edited this page Dec 13, 2024 · 82 revisions

Welcome to the kdewallet wiki!

The wiki provides some additional information about kdewallet.

Compatibility

The KDE wallet functionality itself is provided by the kwallet back-end. This table lists, which version of kdewallet matches which version of kwallet, e.g. implements / deprecates features of kwallet.

kdewallet kwallet Changelog Backwards-compatible to v5.71.0
1.5.1 v5.246.0 / v6.4.0
  • Update to dbus-java 5.1.0
  • Update maven dependencies
 ✅
1.5.0 v5.114.0 / v5.248.0
  • Update to dbus-java 5.0.0
  • Update maven dependencies
 ✅
1.4.0 v5.113.0 / v5.246.0
  • Compatibility to KWallet Framework 6
  • Update maven dependencies
  • Update github workflow actions
 ✅
1.3.3 v5.111.0
  • Update to dbus-java 4.3.1
  • Update maven dependencies
 ✅
1.3.2 v5.108.0
  • Remove unneeded removing the SignalHandler from the connection on shutdown (#3020)
  • Update maven dependencies
 ✅
1.3.1 v5.106.0
  • Move D-Bus interface KWallet to org.purejava.kwallet to avoid 'split jar' problem
  • Update maven dependencies
 ✅
1.3.0 v5.105.0
  • Update to dbus-java 4.3.0
  • Add module-info.java to avoid 'split jar' problems
  • Update maven dependencies
 ✅
1.2.8 v5.101.0
  • Update to dbus-java 4.2.1
  • Update maven dependencies
  • Move to Java 19
  • Update github actions
 ✅
1.2.7 v5.94.0
  • Update to dbus-java 4.1.0
 ✅
1.2.6 v5.89.0
  • Fix handling of values gt 63 characters in helper class (#4)
 ✅
1.2.5 v5.89.0
  • Depend on dbus-java 4.4.0 with native-unixsocket and hence use Java 16+ native support for Unix Domain Sockets
  • Update maven dependencies
 ✅
1.2.4 v5.87.0
  • Code improvements
  • Handle null returned by MessageHandler.send (#2)
  • Move to Java 17
  • Update maven dependencies
 ✅
1.2.3 v5.83.0 ✅
1.2.2 v5.81.0
  • Introduce new walletClosedId signal
 ✅
1.2.1 v5.80.0
  • Update maven dependencies
  • Move to Java 11
  • Depend on dbus-java 3.3.0: DBusConnection.getConnection(DBusBusType _bustype) will no longer throw RuntimeException but DBusConnectionException if something went wrong establishing DBus connection (#128)
 ✅
1.2.0 v5.76.0
  • Complete re-design of the SignalHandler to handle signals asynchronously and make it more robust against timed out D-Bus calls
  • Improve log messages
 ✅
1.1.1 v5.74.0
  • Improve log messages
  • Fix availability check for kwallet deamon
 ✅
1.1.0 v5.73.0
  • Introduce three new methods that return all "entries" in a folder
  • Adopt MessageHandler improvements from secret-service 1.1.0 (#1)
 ✅
1.0.1 v5.71.0 Depend on dbus-java 3.2.3, that fixes issues when dealing with multiple signals of the same name but different signatures (#110) ✅
1.0.0 v5.71.0

There are in-between releases of kwallet, that are not mentioned in the table above. These do not introduce any new functionality or change the API and hence do not make a new release of kdewallet necessary. These kwallet releases are v5.72.0, v5.75.0, v5.77.0 to v5.79.0, v5.82.0 and v5.84.0 to v5.116.0 as well as v5.246.0 to v6.9.0.

Starting with release 1.4.0, kdewallet is compatible to kwallet framework 5 (as before) and kwallet framework 6 too.

Additional information on the kwallet releases mentioned above is available at the KDE Announcements. Look for "KDE Ships Frameworks x.xx.x".

API description

For the full API description, please read the KWallet API JavaDoc.

kdewallet 1.2.0 - asynchronous signal handling

This release introduces asynchronous signal handling, see below.

kdewallet 1.1.0 - entriesList, mapList and passwordList

This release introduces three new methods as a replacement for readEntryList, readMapList and readPasswordList. The latter basically allow "*" as a wildcard to get a list of all the "entries" in a folder. Therefore the new methods were added, to get rid of regular expression usage for matching a certain pattern.

Signal handling

From kdewallet 1.2.0

D-Bus signals are emitted on every change to a wallet, e.g. when it's opened asynchronously, closed etc.. Signal handling in ‪kdewallet versions < 1.2.0 does work well, but could be improved in some regards:

  • the SignalHandler#await method keeps the running application in a loop and waits for the signal to listen for until the signal was emitted or a timeout is reached
  • you cannot await a signal and execute the code that emits the signal afterwards
  • the SignalHandler does not support to catch signals asynchronously

kdewallet 1.2.0 solves this by providing a re-designed SignalHandler to handle signals asynchronously and make SignalHandler more robust against timed out D-Bus calls.

The signal handling was re-written to follow the PropertyChangeListener pattern. It decouples the kdewallet code from applications code using the kdewallet lib and works truly asynchronously. As kdewallet emits quite a number of signals on everything that is happening on the D-Bus with kdewallet, a simple method in the applications code is enough to handle these signals:

wallet.getSignalHandler().addPropertyChangeListener(this);

...

@Override
public void propertyChange(PropertyChangeEvent event) {
	switch (event.getPropertyName()) {
        	case "KWallet.walletAsyncOpened":
			...;
		default:
			...;
	}
}

Up to kdewallet 1.1.1

Fetching and handling of D-Bus signals can be done with the await method. Please note, that the await method got deprecated with kdewallet 1.2.1 and will be removed in future versions.

wallet.openAsync(Static.DEFAULT_WALLET, 0, APP_NAME, false);
wallet.getSignalHandler().await(KWallet.walletAsyncOpened.class, Static.ObjectPaths.SECRETS, () -> null);
handle = wallet.getSignalHandler().getLastHandledSignal(KWallet.walletAsyncOpened.class, Static.ObjectPaths.SECRETS).handle;

Please note, that order is important here: you cannot use the getLastHandledSignal method before the await method.

Different walletClosed signals (until kdewallet 1.2.1)

Pay attention to the walletClosed signals.

There are two walletClosed signals, that get emitted by kwallet every time a wallet is closed. They are defined as follows:

<signal name="walletClosed">
  <arg name="wallet" type="s" direction="out"/>
</signal>
<signal name="walletClosed">
  <arg name="handle" type="i" direction="out"/>
</signal>

This is what dbus-monitor tells about them:

signal time=1594906367.214555 sender=:1.79 -> destination=(null destination) serial=16981 path=/modules/kwalletd5; interface=org.kde.KWallet; member=walletClosed
   int32 1765833520
signal time=1594906367.214570 sender=:1.79 -> destination=(null destination) serial=16982 path=/modules/kwalletd5; interface=org.kde.KWallet; member=walletClosed
   string "kdewallet"

With kdewallet you can either listen on / catch walletClosed (contains the name of the closed wallet) or walletClosedInt (contains the handle of the closed wallet), but not both at the same time.

See issue #110 @ dbus-java.

Since kwallet v5.81.0 a new signal walletClosedId was introduced that is defined the same way as walletClosed (the one that contains the handle of the closed wallet):

<signal name="walletClosedId">
  <arg name="handle" type="i" direction="out"/>
</signal>

walletClosed (containing the handle of the closed wallet) has been deprecated and will be removed in future versions of kwallet in favor of walletClosedId. So with kwallet v5.81.0 the underlying kwallet provides two different signals: walletClosed and walletClosedId and it's possible to listen on both of them at the same time.

A note on opening a wallet

wallet.openAsync does return an int value, which is a sequential transaction id. To read a secret from the opened wallet, you'll need the handle to the wallet, that is contained in the walletAsyncOpened signal, that get's emitted, either when the wallet was opened or the unlock dialog (on a locked wallet) got dismissed.

wallet.open does return the handle to the wallet directly as an int value.

Testing kdewallet

Creating a new wallet presents a dialog / wizard to create the wallet.

Additionally unlocking an existing wallet prompts you with a modal dialog to enter the password for the wallet.

Due to this, testing kdewallet on CI is not possible. On a KDE desktop environment, testing kdewallet can be done like this:

mvn '-Dtest=org.purejava.*Test*' test
Clone this wiki locally