GssPeerManager: libgsystemservice Reference Manual

GssPeerManager

GssPeerManager — D-Bus peer management and notification

Stability Level

Stable, unless otherwise indicated

Functions

void	gss_peer_manager_ensure_peer_credentials_async ()
gboolean	gss_peer_manager_ensure_peer_credentials_finish ()
const gchar *	gss_peer_manager_get_peer_argv0 ()
int	gss_peer_manager_get_peer_pidfd ()
uid_t	gss_peer_manager_get_peer_uid ()

Types and Values

	GssPeerManager
struct	GssPeerManagerInterface
enum	GssPeerManagerError

Includes

#include <libgsystemservice/peer-manager.h>

Description

A peer manager is an abstraction over the management of peers on a D-Bus connection, monitoring when they disappear, and allowing querying and caching of their credentials.

Currently, the only credential stored is the path to the peer’s executable, which can be used to identify that peer. In future, other credentials may be added (and the API will change accordingly).

The default implementation for production use is GssPeerManagerDBus, which uses the D-Bus daemon to get credentials. Unit tests will use a different implementation, allowing them to provide fake data to the service easily.

Functions

gss_peer_manager_ensure_peer_credentials_async ()

void
gss_peer_manager_ensure_peer_credentials_async
                               (GssPeerManager *self,
                                const gchar *sender,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Ensure the credentials for a peer are in the peer manager, querying them from the D-Bus daemon if needed.

Also start watching the sender , so that if it disappears from the bus, a “peer-vanished” signal will be emitted.

On failure, a GDBusError is returned if querying the D-Bus daemon failed, or GSS_PEER_MANAGER_ERROR_IDENTIFYING_PEER is returned if interpreting the information it returned failed.

Parameters

self	a GssPeerManager
sender	D-Bus unique name for the peer
cancellable	a GCancellable, or `NULL`.	[nullable]
callback	callback to call once the asynchronous operation is complete
user_data	data to pass to `callback`

Since: 0.1.0

gss_peer_manager_ensure_peer_credentials_finish ()

gboolean
gss_peer_manager_ensure_peer_credentials_finish
                               (GssPeerManager *self,
                                GAsyncResult *result,
                                GError **error);

Finish ensuring the credentials for a peer are in the peer manager. See gss_peer_manager_ensure_peer_credentials_async().

If this returns TRUE, the credentials can be queried from the cache using the accessor methods on GssPeerManager.

Parameters

self	a GssPeerManager
result	asynchronous operation result
error	return location for a GError

Returns

TRUE on success, FALSE otherwise

Since: 0.3.0

gss_peer_manager_get_peer_argv0 ()

const gchar *
gss_peer_manager_get_peer_argv0 (GssPeerManager *self,
                                 const gchar *sender);

Get the first argument from /proc/${pid}/cmdline for the given peer.

If no credentials are in the cache for sender , NULL will be returned.

Parameters

self	a GssPeerManager
sender	D-Bus unique name for the peer

Returns

path to the argv0 for the peer, or NULL if it’s unknown.

[nullable]

Since: 0.3.0

gss_peer_manager_get_peer_pidfd ()

int
gss_peer_manager_get_peer_pidfd (GssPeerManager *self,
                                 const gchar *sender);

Get a pidfd which references the given peer’s process.

If no credentials are in the cache for sender , -1 will be returned.

Parameters

self	a GssPeerManager
sender	D-Bus unique name for the peer

Returns

pidfd for the peer’s process, or -1 if it’s unknown.

[nullable]

Since: 0.3.0

gss_peer_manager_get_peer_uid ()

uid_t
gss_peer_manager_get_peer_uid (GssPeerManager *self,
                               const gchar *sender);

Get the Unix user ID running the given peer’s process.

If no credentials are in the cache for sender , (uid_t) -1 will be returned.

Parameters

self	a GssPeerManager
sender	D-Bus unique name for the peer

Returns

Unix user ID running the peer’s process, or (uid_t) -1 if it’s unknown.

[nullable]

Since: 0.3.0

Types and Values

GssPeerManager

typedef struct _GssPeerManager GssPeerManager;

An interface for D-Bus peer management. The typical production implementation of this is GssPeerManagerDBus; other implementations can be written to be used during testing, returning mock results.

Since: 0.1.0

struct GssPeerManagerInterface

struct GssPeerManagerInterface {
  GTypeInterface g_iface;

  void         (*ensure_peer_credentials_async)  (GssPeerManager       *manager,
                                                  const gchar          *sender,
                                                  GCancellable         *cancellable,
                                                  GAsyncReadyCallback   callback,
                                                  gpointer              user_data);
  gboolean     (*ensure_peer_credentials_finish) (GssPeerManager       *manager,
                                                  GAsyncResult         *result,
                                                  GError              **error);

  const gchar *(*get_peer_argv0)                 (GssPeerManager       *manager,
                                                  const gchar          *sender);
  int          (*get_peer_pidfd)                 (GssPeerManager       *manager,
                                                  const gchar          *sender);
  uid_t        (*get_peer_uid)                   (GssPeerManager       *manager,
                                                  const gchar          *sender);
};

An interface which exposes peers for the service (typically, D-Bus clients which are calling its methods) and allows querying of their credentials, and notification of when they disappear.

All virtual methods in this interface are mandatory to implement if the interface is implemented.

Members

`ensure_peer_credentials_async` ()	Query for the credentials of the given peer, and ensure they are in the peer manager’s cache.
`ensure_peer_credentials_finish` ()	Finish an asynchronous query operation started with `ensure_peer_credentials_async` . (Since: 0.3.0)
`get_peer_argv0` ()	Get argv0 credential for a peer out of the peer manager’s cache. If the peer is not known to the manager, return `NULL`. (Since: 0.3.0)
`get_peer_pidfd` ()	Get a pidfd for the peer’s process out of the peer manager’s cache. If the peer is not known to the manager, return `-1`. (Since: 0.3.0)
`get_peer_uid` ()	Get the Unix user ID running the peer’s process out of the peer manager’s cache. If the peer is not known to the manager, return `(uid_t) -1`. (Since: 0.3.0)

Since: 0.1.0

enum GssPeerManagerError

Errors which can be returned by GssPeerManager.

Members

GSS_PEER_MANAGER_ERROR_IDENTIFYING_PEER

A peer which was interacting with this service could not be identified.

Since: 0.1.0