mirror of
https://gitlab.freedesktop.org/NetworkManager/NetworkManager
synced 2024-07-22 02:35:25 +00:00
c1ec829099
Note that the name "NMSecretAgentOld" comes from when libnm was forked from libnm-glib. There was a plan to rework the secret agent API and replace it by a better one. That didn't happen (yet), instead our one and only agent implementation is still lacking. Don't add a new API, instead try to improve the existing one, without breaking existing users. Just get over the fact that the name "NMSecretAgentOld" is ugly. Also note how nm-applet uses NMSecretAgentOld. It subtypes a class AppletAgent. The constructor applet_agent_new() is calling the synchronous g_initable_init() initialization with auto-register enabled. As it was, g_initable_init() would call nm_secret_agent_old_register(), and if the "Register" call failed, initialization failed for good. There are even unit tests that test this behavior. This is bad behavior. It means, when you start nm-applet without NetworkManager running, it will fail to create the AppletAgent instance. It would hence be the responsibility of the applet to recover from this situation (e.g. by retrying after timeout or watching the D-Bus name owner). Of course, nm-applet doesn't do that and won't recover from such a failure. NMSecretAgentOld must try hard not to fail and recover automatically. The user of the API is not interested in implementing the registration, unregistration and retry handling. Instead, it should just work best effort and transparently to the user of the API. Differences: - no longer use gdbus-codegen generate bindings. Use GDBusConnection directly instead. These generated proxies complicate the code by introducing an additional, stateful layer. - properly handle GMainContext and synchronous initialization by using an internal GMainContext. With this NMSecretAgentOld can be used in a multi threaded context with separate GMainContext. This does not mean that the object itself became thread safe, but that the GMainContext gives the means to coordinate multi-threaded access. - there are no more blocking calls except g_initiable_init() which iterates an internal GMainContext until initialization completes. - obtaining the Unix user ID with "GetConnectionUnixUser" to authenticate the server is now done asynchronously and only once per name-owner. - NMSecretAgentOld will now register/export the Agent D-Bus object already during initialization and stay registered as long as the instance is alive. This is because usually registering a D-Bus object would not fail, unless the D-Bus path is already taken. Such an error would mean that another agent is registered for the same GDBusConnection, that likely would be a bug in the caller. Hence, such an issue is truly non-recoverable and should be reported early to the user. There is a change in behavior compared to before, where previously the D-Bus object would only be registered while the instance is enabled. This makes a difference if the user intended to keep the NMSecretAgentOld instance around in an unregistered state. Note that nm_secret_agent_old_destroy() was added to really unregister the D-Bus object. A destroyed instance can no longer be registered. - the API no longer fully exposes the current registration state. The user either enables or disables the agent. Then, in the background NMSecretAgentOld will register, and serve requests as they come. It will also always automatically re-register and it can de-facto no longer fail. That is, there might be a failure to register, or the NetworkManager peer might not be authenticated (non-root) or there might be some other error, or NetworkManager might not be running. But such errors are not exposed to the user. The instance is just not able to provide the secrets in those cases, but it may recover if the problem can be resolved. - In particular, it makes no sense that nm_secret_agent_old_register*() fails, returns an error, or waits until registration is complete. This API is now only to enable/disable the agent. It is idempotent and won't fail (there is a catch, see next point). In particular, nm_secret_agent_old_unregister*() cannot fail anymore. - However, with the previous point there is a problem/race. When you create a NMSecretAgentOld instance and immediately afterwards activate a profile, then you want to be sure that the registration is complete first. Otherwise, NetworkManager might fail the activation because no secret agent registered yet. A partial solution for this is that g_initiable_init()/g_async_initable_init_async() will block until registration is complete (or with or without success). That means, if NetworkManager is running, initializing the NMSecretAgentOld will wait until registration is complete (or failed). However, that does not solve the race if NetworkManager was not running when creating the instance. To solve that race, the user may call nm_secret_agent_old_register_async() and wait for the command to finish before starting activating. While async registration no longer fails (in the sense of leaving the agent permanently disconnected), it will try to ensure that we are successfully registered and ready to serve requests. By using this API correctly, a race can be avoided and the user can know that the instance is now ready to serve request.
265 lines
12 KiB
C
265 lines
12 KiB
C
// SPDX-License-Identifier: LGPL-2.1+
|
|
/*
|
|
* Copyright (C) 2010 - 2011 Red Hat, Inc.
|
|
*/
|
|
|
|
#ifndef __NM_SECRET_AGENT_OLD_H__
|
|
#define __NM_SECRET_AGENT_OLD_H__
|
|
|
|
#include "nm-types.h"
|
|
|
|
G_BEGIN_DECLS
|
|
|
|
#define NM_TYPE_SECRET_AGENT_OLD (nm_secret_agent_old_get_type ())
|
|
#define NM_SECRET_AGENT_OLD(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), NM_TYPE_SECRET_AGENT_OLD, NMSecretAgentOld))
|
|
#define NM_SECRET_AGENT_OLD_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), NM_TYPE_SECRET_AGENT_OLD, NMSecretAgentOldClass))
|
|
#define NM_IS_SECRET_AGENT_OLD(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), NM_TYPE_SECRET_AGENT_OLD))
|
|
#define NM_IS_SECRET_AGENT_OLD_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), NM_TYPE_SECRET_AGENT_OLD))
|
|
#define NM_SECRET_AGENT_OLD_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), NM_TYPE_SECRET_AGENT_OLD, NMSecretAgentOldClass))
|
|
|
|
#define NM_SECRET_AGENT_OLD_IDENTIFIER "identifier"
|
|
#define NM_SECRET_AGENT_OLD_AUTO_REGISTER "auto-register"
|
|
#define NM_SECRET_AGENT_OLD_REGISTERED "registered"
|
|
#define NM_SECRET_AGENT_OLD_CAPABILITIES "capabilities"
|
|
#define NM_SECRET_AGENT_OLD_DBUS_CONNECTION "dbus-connection"
|
|
|
|
/**
|
|
* NMSecretAgentOld:
|
|
*/
|
|
typedef struct {
|
|
GObject parent;
|
|
} NMSecretAgentOld;
|
|
|
|
/**
|
|
* NMSecretAgentOldGetSecretsFunc:
|
|
* @agent: the secret agent object
|
|
* @connection: (transfer none): the connection for which secrets were requested,
|
|
* note that this object will be unrefed after the callback has returned, use
|
|
* g_object_ref()/g_object_unref() if you want to use this object after the callback
|
|
* has returned
|
|
* @secrets: the #GVariant of type %NM_VARIANT_TYPE_CONNECTION containing the requested
|
|
* secrets (as created by nm_connection_to_dbus() for example). Each key in @secrets
|
|
* should be the name of a #NMSetting object (like "802-11-wireless-security")
|
|
* and each value should be an %NM_VARIANT_TYPE_SETTING variant. The sub-dicts
|
|
* map string:value, where the string is the setting property name (like "psk")
|
|
* and the value is the secret
|
|
* @error: if the secrets request failed, give a descriptive error here
|
|
* @user_data: caller-specific data to be passed to the function
|
|
*
|
|
* Called as a result of a request by NM to retrieve secrets. When the
|
|
* #NMSecretAgentOld subclass has finished retrieving secrets and is ready to
|
|
* return them, or to return an error, this function should be called with
|
|
* those secrets or the error.
|
|
*
|
|
* To easily create the dictionary to return the Wi-Fi PSK, you could do
|
|
* something like this:
|
|
* <example>
|
|
* <title>Creating a secrets dictionary</title>
|
|
* <programlisting>
|
|
* NMConnection *secrets;
|
|
* NMSettingWirelessSecurity *s_wsec;
|
|
* GVariant *secrets_dict;
|
|
*
|
|
* secrets = nm_simple_connection_new ();
|
|
* s_wsec = (NMSettingWirelessSecurity *) nm_setting_wireless_security_new ();
|
|
* g_object_set (G_OBJECT (s_wsec),
|
|
* NM_SETTING_WIRELESS_SECURITY_PSK, "my really cool PSK",
|
|
* NULL);
|
|
* nm_connection_add_setting (secrets, NM_SETTING (s_wsec));
|
|
* secrets_dict = nm_connection_to_dbus (secrets, NM_CONNECTION_SERIALIZE_ALL);
|
|
*
|
|
* (call the NMSecretAgentOldGetSecretsFunc with secrets_dict)
|
|
*
|
|
* g_object_unref (secrets);
|
|
* g_variant_unref (secrets_dict);
|
|
* </programlisting>
|
|
* </example>
|
|
*/
|
|
typedef void (*NMSecretAgentOldGetSecretsFunc) (NMSecretAgentOld *agent,
|
|
NMConnection *connection,
|
|
GVariant *secrets,
|
|
GError *error,
|
|
gpointer user_data);
|
|
|
|
/**
|
|
* NMSecretAgentOldSaveSecretsFunc:
|
|
* @agent: the secret agent object
|
|
* @connection: (transfer none): the connection for which secrets were to be saved,
|
|
* note that this object will be unrefed after the callback has returned, use
|
|
* g_object_ref()/g_object_unref() if you want to use this object after the callback
|
|
* has returned
|
|
* @error: if the saving secrets failed, give a descriptive error here
|
|
* @user_data: caller-specific data to be passed to the function
|
|
*
|
|
* Called as a result of a request by NM to save secrets. When the
|
|
* #NMSecretAgentOld subclass has finished saving the secrets, this function
|
|
* should be called.
|
|
*/
|
|
typedef void (*NMSecretAgentOldSaveSecretsFunc) (NMSecretAgentOld *agent,
|
|
NMConnection *connection,
|
|
GError *error,
|
|
gpointer user_data);
|
|
|
|
/**
|
|
* NMSecretAgentOldDeleteSecretsFunc:
|
|
* @agent: the secret agent object
|
|
* @connection: (transfer none): the connection for which secrets were to be deleted,
|
|
* note that this object will be unrefed after the callback has returned, use
|
|
* g_object_ref()/g_object_unref() if you want to use this object after the callback
|
|
* has returned
|
|
* @error: if the deleting secrets failed, give a descriptive error here
|
|
* @user_data: caller-specific data to be passed to the function
|
|
*
|
|
* Called as a result of a request by NM to delete secrets. When the
|
|
* #NMSecretAgentOld subclass has finished deleting the secrets, this function
|
|
* should be called.
|
|
*/
|
|
typedef void (*NMSecretAgentOldDeleteSecretsFunc) (NMSecretAgentOld *agent,
|
|
NMConnection *connection,
|
|
GError *error,
|
|
gpointer user_data);
|
|
|
|
typedef struct {
|
|
GObjectClass parent;
|
|
|
|
/* Virtual methods for subclasses */
|
|
|
|
/* Called when the subclass should retrieve and return secrets. Subclass
|
|
* must copy or reference any arguments it may require after returning from
|
|
* this method, as the arguments will freed (except for 'self', 'callback',
|
|
* and 'user_data' of course).
|
|
*
|
|
* Before version 1.24, if the request is canceled, the callback
|
|
* should still be called, but with the NM_SECRET_AGENT_ERROR_AGENT_CANCELED
|
|
* error. Since 1.24, invoking the callback has no effect during cancellation
|
|
* and may be omitted.
|
|
*/
|
|
void (*get_secrets) (NMSecretAgentOld *self,
|
|
NMConnection *connection,
|
|
const char *connection_path,
|
|
const char *setting_name,
|
|
const char **hints,
|
|
NMSecretAgentGetSecretsFlags flags,
|
|
NMSecretAgentOldGetSecretsFunc callback,
|
|
gpointer user_data);
|
|
|
|
/* Called when the subclass should cancel an outstanding request to
|
|
* get secrets for a given connection.
|
|
*
|
|
* Before version 1.24, canceling the request MUST call the callback that was
|
|
* passed along with the initial get_secrets call, sending the NM_SECRET_AGENT_ERROR/
|
|
* NM_SECRET_AGENT_ERROR_AGENT_CANCELED error to that callback. Since 1.24,
|
|
* the get_secrets callback will be ignored during cancellation and may be omitted.
|
|
*/
|
|
void (*cancel_get_secrets) (NMSecretAgentOld *self,
|
|
const char *connection_path,
|
|
const char *setting_name);
|
|
|
|
/* Called when the subclass should save the secrets contained in the
|
|
* connection to backing storage. Subclass must copy or reference any
|
|
* arguments it may require after returning from this method, as the
|
|
* arguments will freed (except for 'self', 'callback', and 'user_data'
|
|
* of course).
|
|
*/
|
|
void (*save_secrets) (NMSecretAgentOld *self,
|
|
NMConnection *connection,
|
|
const char *connection_path,
|
|
NMSecretAgentOldSaveSecretsFunc callback,
|
|
gpointer user_data);
|
|
|
|
/* Called when the subclass should delete the secrets contained in the
|
|
* connection from backing storage. Subclass must copy or reference any
|
|
* arguments it may require after returning from this method, as the
|
|
* arguments will freed (except for 'self', 'callback', and 'user_data'
|
|
* of course).
|
|
*/
|
|
void (*delete_secrets) (NMSecretAgentOld *self,
|
|
NMConnection *connection,
|
|
const char *connection_path,
|
|
NMSecretAgentOldDeleteSecretsFunc callback,
|
|
gpointer user_data);
|
|
|
|
/*< private >*/
|
|
gpointer padding[8];
|
|
} NMSecretAgentOldClass;
|
|
|
|
GType nm_secret_agent_old_get_type (void);
|
|
|
|
NM_AVAILABLE_IN_1_24
|
|
GDBusConnection *nm_secret_agent_old_get_dbus_connection (NMSecretAgentOld *self);
|
|
|
|
NM_AVAILABLE_IN_1_24
|
|
GMainContext *nm_secret_agent_old_get_main_context (NMSecretAgentOld *self);
|
|
|
|
NM_AVAILABLE_IN_1_24
|
|
GObject *nm_secret_agent_old_get_context_busy_watcher (NMSecretAgentOld *self);
|
|
|
|
NM_AVAILABLE_IN_1_24
|
|
const char *nm_secret_agent_old_get_dbus_name_owner (NMSecretAgentOld *self);
|
|
|
|
gboolean nm_secret_agent_old_get_registered (NMSecretAgentOld *self);
|
|
|
|
/*****************************************************************************/
|
|
|
|
NM_AVAILABLE_IN_1_24
|
|
void nm_secret_agent_old_enable (NMSecretAgentOld *self,
|
|
gboolean enable);
|
|
|
|
void nm_secret_agent_old_register_async (NMSecretAgentOld *self,
|
|
GCancellable *cancellable,
|
|
GAsyncReadyCallback callback,
|
|
gpointer user_data);
|
|
gboolean nm_secret_agent_old_register_finish (NMSecretAgentOld *self,
|
|
GAsyncResult *result,
|
|
GError **error);
|
|
|
|
NM_AVAILABLE_IN_1_24
|
|
void nm_secret_agent_old_destroy (NMSecretAgentOld *self);
|
|
|
|
/*****************************************************************************/
|
|
|
|
NM_DEPRECATED_IN_1_24_FOR (nm_secret_agent_old_enable)
|
|
gboolean nm_secret_agent_old_register (NMSecretAgentOld *self,
|
|
GCancellable *cancellable,
|
|
GError **error);
|
|
|
|
NM_DEPRECATED_IN_1_24_FOR (nm_secret_agent_old_enable)
|
|
gboolean nm_secret_agent_old_unregister (NMSecretAgentOld *self,
|
|
GCancellable *cancellable,
|
|
GError **error);
|
|
|
|
NM_DEPRECATED_IN_1_24_FOR (nm_secret_agent_old_enable)
|
|
void nm_secret_agent_old_unregister_async (NMSecretAgentOld *self,
|
|
GCancellable *cancellable,
|
|
GAsyncReadyCallback callback,
|
|
gpointer user_data);
|
|
|
|
NM_DEPRECATED_IN_1_24_FOR (nm_secret_agent_old_enable)
|
|
gboolean nm_secret_agent_old_unregister_finish (NMSecretAgentOld *self,
|
|
GAsyncResult *result,
|
|
GError **error);
|
|
|
|
/*****************************************************************************/
|
|
|
|
void nm_secret_agent_old_get_secrets (NMSecretAgentOld *self,
|
|
NMConnection *connection,
|
|
const char *setting_name,
|
|
const char **hints,
|
|
NMSecretAgentGetSecretsFlags flags,
|
|
NMSecretAgentOldGetSecretsFunc callback,
|
|
gpointer user_data);
|
|
|
|
void nm_secret_agent_old_save_secrets (NMSecretAgentOld *self,
|
|
NMConnection *connection,
|
|
NMSecretAgentOldSaveSecretsFunc callback,
|
|
gpointer user_data);
|
|
|
|
void nm_secret_agent_old_delete_secrets (NMSecretAgentOld *self,
|
|
NMConnection *connection,
|
|
NMSecretAgentOldDeleteSecretsFunc callback,
|
|
gpointer user_data);
|
|
|
|
G_END_DECLS
|
|
|
|
#endif /* __NM_SECRET_AGENT_OLD_H__ */
|