Containers (#171): minimal, identification-only version
User story
Maintainers of xdg-desktop-portal want to identify whether a message comes from a sandboxed Flatpak/Snap/(etc.) app, so that they can present appropriate UI and apply appropriate restrictions.
(Other D-Bus services that offer portal-like functionality could have similar requests and should also be considered; x-d-p is just one example.)
Description
This is a subset of the Containers interface (#171) and was originally designed and implemented in:
The implementation was disabled in 505233a5 and 9d60676a before freezing 1.14.0, to avoid having to support an interface in which we might want to make incompatible changes. It was also removed from the spec in f8a2a03c.
APIs included in dbus 1.14.0
These are included in 1.14.0, so we cannot remove them, only deprecate them if necessary.
-
Add a new header field to messages, C macro
DBUS_HEADER_FIELD_CONTAINER_INSTANCE
, with value 10. C accessors in libdbus aredbus_bool_t dbus_message_set_container_instance(DBusMessage *, const char *)
andconst char *dbus_message_get_container_instance (DBusMessage *)
. It is documented as being an object path orNULL
. -
Add a new error, C macro
DBUS_ERROR_NOT_CONTAINER
, with valueorg.freedesktop.DBus.Error.NotContainer
.
APIs that were never in a stable release
This exists in dbus-daemon, but most of it is #if 0
since late 2021.
-
Container instances are identified by an object path, the instance ID, which is different from
/
. This is currently treated as opaque and has no interfaces. Most methods raiseNotContainer
if given an object path that is not a valid instance ID. -
New interface on
o.fd.DBus
:org.freedesktop.DBus.Containers1
- Implementation detail: this is only available on Unix, and only if enabled at compile time.
-
RequestHeader() -> ()
- After you call this method succesfully,
DBUS_HEADER_FIELD_CONTAINER_INSTANCE
will be added to messages delivered to you. Its value is the instance ID of the sender, or/
if the sender is on the main (non-contained) connection. -
DBUS_HEADER_FIELD_CONTAINER_INSTANCE
will be removed from all other messages, if present.
- After you call this method succesfully,
-
signal InstanceRemoved(o: instance_id)
- Emitted when a container instance vanishes.
-
StopListening(o: instance_id) -> ()
- Stop listening for new connections on the socket belonging to instance_id, but do not terminate existing connections.
- Only the same Unix uid that created instance_id can call this.
-
StopInstance(o: instance_id) -> ()
- Same as
StopListening
, but also disconnect any existing connections. - Only the same Unix uid that created instance_id can call this.
- Same as
-
GetInstanceInfo(o: instance_id) -> (a{sv}: creds, s: type, s: name, a{sv}: metadata)
-
creds is the result of calling
GetConnectionCredentials()
on the connection that created instance_id. -
type is a reversed-DNS-style name for the container manager, canonically
org.flatpak
orio.snapcraft
. -
name is what the container manager calls this app. I expect Flatpak to use reversed-DNS app IDs, but I expect Snap to use its own app IDs (which are simple strings like
firefox
andsteam
). - metadata is currently defined by the container manager, but should probably be changed to have some sort of standardization, with either a convention or a separate dict for container-manager-specific stuff.
-
creds is the result of calling
-
GetConnectionInstance(s: bus_name) -> (o: instance_id, a{sv}, s, s, a{sv})
- If bus_name is from a container instance, return its instance ID and the same information as for
GetInstanceInfo
. - Otherwise, raise
o.fd.DBus.Error.NotContainer
.
- If bus_name is from a container instance, return its instance ID and the same information as for
-
AddServer(s: type, s: name, a{sv}: metadata, a{sv}: kwargs) -> (o: instance_id, ay: socket_path, s: dbus_address)
- Create a new listening socket.
-
type
,name
,metadata
are the same as forGetInstanceInfo
. - When the caller disconnects from the bus, the equivalent of
StopListening
happens. #186 adds an opt-out for this behaviour but is not on the critical path. -
kwargs
is for future extension. Namespace management is the same as for Features.
-
property SupportedArguments: as, readable
- A list of keys you can put in the last parameter of
AddServer
.
- A list of keys you can put in the last parameter of
Other API surface area:
-
In
GetConnectionCredentials
, add one new field:org.freedesktop.DBus.Containers1.Instance
, which is the same object path asDBUS_HEADER_FIELD_CONTAINER_INSTANCE
. -
Connections to container sockets cannot call any "bus driver" method with
METHOD_FLAG_PRIVILEGED
orMETHOD_FLAG_NO_CONTAINERS
: currently this meansUpdateActivationEnvironment
,BecomeMonitor
and the dbus-daemon-specificEnableVerbose
, plus the newAddServer
,StopInstance
andStopListening
.
Acceptance
-
Decision on #210 (closed): either we switch the instance ID from an object path to an integer, or we leave it as an object path. Arbitrary deadline: if there is no movement on this and #478 by the end of September 2023, then @smcv considers the conclusion to be: we leave it as an object path. -
Decision on #189 (closed): what to do about extra-privileged methods. Arbitrary deadline: if there is no movement on this by the end of September 2023, then @smcv considers the conclusion to be: take no action, the initial implementation was fine. -
Decision on #479: how we represent metadata -
Re-enable Containers interface in development git branch, gated by -Dcontainers=true
(by reverting 505233a5 and 9d60676a) -
Document Containers interface in its current form in dbus-specification.xml (revert f8a2a03c and update) -
Unit tests pass and have good coverage -
Code review -
Merge to development branch
Deadline
Targeted for inclusion in dbus 1.16.0.
In the interests of having this not stall for another 5 years, @smcv is setting an arbitrary deadline of the end of 2023 for this. If anything is still under discussion at that point, then the version that got merged by then is what we will ship (and if someone doesn't like it then that's too bad); or if nothing was merged at that point, then @smcv will reinstate the version that was disabled in late 2021 on an as-is basis.
Nice to have
Nice-to-haves should be minimized, please. In an effort to avoid avoid a serious risk that this feature will never be available at all, @smcv would like to avoid it being delayed by anything that is not on the critical path for getting this feature finished, documented, tested and available to users.
Out of scope
- Obsoleting xdg-dbus-proxy by providing filtering/policy is #185 and all its various sub-tasks, and is out of scope for the purposes of this issue, to avoid having this never happen.
- The CMake build system does not have a way to enable this feature. We are moving towards Meson as the recommended (only?) build system for dbus on Unix, so this is not considered to be a blocker. If the Meson feature is switched to be enabled-by-default, then it can be added to CMake as enabled-by-default or enabled-on-Linux at that time.
- Stable release