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