GNOME.org

NMSecretAgent

NMSecretAgent

Functions

#define NM_SECRET_AGENT_ERROR
GQuark nm_secret_agent_error_quark ()
void (*NMSecretAgentGetSecretsFunc) ()
void (*NMSecretAgentSaveSecretsFunc) ()
void (*NMSecretAgentDeleteSecretsFunc) ()
gboolean nm_secret_agent_register ()
gboolean nm_secret_agent_unregister ()
gboolean nm_secret_agent_get_registered ()
void nm_secret_agent_get_secrets ()
void nm_secret_agent_save_secrets ()
void nm_secret_agent_delete_secrets ()

Properties

gboolean auto-register Read / Write / Construct
NMSecretAgentCapabilities capabilities Read / Write / Construct
gchar * identifier Read / Write / Construct Only
gboolean registered Read

Signals

void registration-result Run First

Types and Values

enum NMSecretAgentError
enum NMSecretAgentCapabilities
enum NMSecretAgentGetSecretsFlags
#define NM_SECRET_AGENT_IDENTIFIER
#define NM_SECRET_AGENT_AUTO_REGISTER
#define NM_SECRET_AGENT_REGISTERED
#define NM_SECRET_AGENT_CAPABILITIES
#define NM_SECRET_AGENT_REGISTRATION_RESULT

Object Hierarchy

    GObject
    ╰── NMSecretAgent

Description

Functions

NM_SECRET_AGENT_ERROR

#define NM_SECRET_AGENT_ERROR         (nm_secret_agent_error_quark ())

nm_secret_agent_error_quark ()

GQuark
nm_secret_agent_error_quark (void);

Returns

NMSecretAgentGetSecretsFunc ()

void
(*NMSecretAgentGetSecretsFunc) (NMSecretAgent *agent,
                                NMConnection *connection,
                                GHashTable *secrets,
                                GError *error,
                                gpointer user_data);

Called as a result of a request by NM to retrieve secrets. When the NMSecretAgent 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 hash table to return the Wi-Fi PSK, you could do something like this:

Example 1. Creating a secrets hash

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
NMConnection *secrets;
NMSettingWirelessSecurity *s_wsec;
GHashTable *secrets_hash;

secrets = nm_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_hash = nm_connection_to_hash (secrets, NM_SETTING_HASH_FLAG_ALL);

(call the NMSecretAgentGetSecretsFunc with secrets_hash)

g_object_unref (secrets);
g_hash_table_unref (secrets_hash);


Parameters

agent

the secret agent object

  

connection

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.

[transfer none]

secrets

the GHashTable containing the requested secrets in the same format as an NMConnection hash (as created by nm_connection_to_hash() for example). Each key in secrets should be the name of a NMSetting object (like "802-11-wireless-security") and each value should be a GHashTable. The sub-hashes map string:GValue where the string is the setting property name (like "psk") and the value is the secret.

[element-type utf8 GLib.HashTable]

error

if the secrets request failed, give a descriptive error here

  

user_data

caller-specific data to be passed to the function

  

NMSecretAgentSaveSecretsFunc ()

void
(*NMSecretAgentSaveSecretsFunc) (NMSecretAgent *agent,
                                 NMConnection *connection,
                                 GError *error,
                                 gpointer user_data);

Called as a result of a request by NM to save secrets. When the NMSecretAgent subclass has finished saving the secrets, this function should be called.

Parameters

agent

the secret agent object

  

connection

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.

[transfer none]

error

if the saving secrets failed, give a descriptive error here

  

user_data

caller-specific data to be passed to the function

  

NMSecretAgentDeleteSecretsFunc ()

void
(*NMSecretAgentDeleteSecretsFunc) (NMSecretAgent *agent,
                                   NMConnection *connection,
                                   GError *error,
                                   gpointer user_data);

Called as a result of a request by NM to delete secrets. When the NMSecretAgent subclass has finished deleting the secrets, this function should be called.

Parameters

agent

the secret agent object

  

connection

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.

[transfer none]

error

if the deleting secrets failed, give a descriptive error here

  

user_data

caller-specific data to be passed to the function

  

nm_secret_agent_register ()

gboolean
nm_secret_agent_register (NMSecretAgent *self);

Registers the NMSecretAgent with the NetworkManager secret manager, indicating to NetworkManager that the agent is able to provide and save secrets for connections on behalf of its user. Registration is an asynchronous operation and its success or failure is indicated via the 'registration-result' signal.

Parameters

self

a NMSecretAgent

  

Returns

a new TRUE if registration was successfully requested (this does not mean registration itself was successful), FALSE if registration was not successfully requested.

nm_secret_agent_unregister ()

gboolean
nm_secret_agent_unregister (NMSecretAgent *self);

Unregisters the NMSecretAgent with the NetworkManager secret manager, indicating to NetworkManager that the agent is will no longer provide or store secrets on behalf of this user.

Parameters

self

a NMSecretAgent

  

Returns

a new TRUE if unregistration was successful, FALSE if it was not.

nm_secret_agent_get_registered ()

gboolean
nm_secret_agent_get_registered (NMSecretAgent *self);

Parameters

self

a NMSecretAgent

  

Returns

a TRUE if the agent is registered, FALSE if it is not.

nm_secret_agent_get_secrets ()

void
nm_secret_agent_get_secrets (NMSecretAgent *self,
                             NMConnection *connection,
                             const char *setting_name,
                             const char **hints,
                             NMSecretAgentGetSecretsFlags flags,
                             NMSecretAgentGetSecretsFunc callback,
                             gpointer user_data);

Asyncronously retrieve secrets belonging to connection for the setting setting_name . flags indicate specific behavior that the secret agent should use when performing the request, for example returning only existing secrets without user interaction, or requesting entirely new secrets from the user.

Virtual: get_secrets

Parameters

self

a NMSecretAgent

  

connection

the NMConnection for which we're asked secrets

  

setting_name

the name of the secret setting

  

hints

hints to the agent.

[array zero-terminated=1]

flags

flags that modify the behavior of the request

  

callback

a callback, to be invoked when the operation is done.

[scope async]

user_data

caller-specific data to be passed to callback .

[closure]

nm_secret_agent_save_secrets ()

void
nm_secret_agent_save_secrets (NMSecretAgent *self,
                              NMConnection *connection,
                              NMSecretAgentSaveSecretsFunc callback,
                              gpointer user_data);

Asyncronously ensure that all secrets inside connection are stored to disk.

Virtual: save_secrets

Parameters

self

a NMSecretAgent

  

connection

a NMConnection

  

callback

a callback, to be invoked when the operation is done.

[scope async]

user_data

caller-specific data to be passed to callback .

[closure]

nm_secret_agent_delete_secrets ()

void
nm_secret_agent_delete_secrets (NMSecretAgent *self,
                                NMConnection *connection,
                                NMSecretAgentDeleteSecretsFunc callback,
                                gpointer user_data);

Asynchronously ask the agent to delete all saved secrets belonging to connection .

Virtual: delete_secrets

Parameters

self

a NMSecretAgent

  

connection

a NMConnection

  

callback

a callback, to be invoked when the operation is done.

[scope async]

user_data

caller-specific data to be passed to callback .

[closure]

Types and Values

enum NMSecretAgentError

NMSecretAgentError values are passed by secret agents back to NetworkManager when they encounter problems retrieving secrets on behalf of NM.

Members

NM_SECRET_AGENT_ERROR_NOT_AUTHORIZED

the caller (ie, NetworkManager) is not authorized to make this request

  

NM_SECRET_AGENT_ERROR_INVALID_CONNECTION

the connection for which secrets were requested could not be found

  

NM_SECRET_AGENT_ERROR_USER_CANCELED

the request was canceled by the user

  

NM_SECRET_AGENT_ERROR_AGENT_CANCELED

the agent canceled the request because it was requested to do so by NetworkManager

  

NM_SECRET_AGENT_ERROR_INTERNAL_ERROR

some internal error in the agent caused the request to fail

  

NM_SECRET_AGENT_ERROR_NO_SECRETS

the agent cannot find any secrets for this connection

  

enum NMSecretAgentCapabilities

NMSecretAgentCapabilities indicate various capabilities of the agent.

Members

NM_SECRET_AGENT_CAPABILITY_NONE

the agent supports no special capabilities

  

NM_SECRET_AGENT_CAPABILITY_VPN_HINTS

the agent supports sending hints given by the get_secrets class method to VPN plugin authentication dialogs.

  

NM_SECRET_AGENT_CAPABILITY_LAST

bounds checking value; should not be used.

  

Since 0.9.10

enum NMSecretAgentGetSecretsFlags

NMSecretAgentGetSecretsFlags values modify the behavior of a GetSecrets request.

Members

NM_SECRET_AGENT_GET_SECRETS_FLAG_NONE

no special behavior; by default no user interaction is allowed and requests for secrets are fulfilled from persistent storage, or if no secrets are available an error is returned.

  

NM_SECRET_AGENT_GET_SECRETS_FLAG_ALLOW_INTERACTION

allows the request to interact with the user, possibly prompting via UI for secrets if any are required, or if none are found in persistent storage.

  

NM_SECRET_AGENT_GET_SECRETS_FLAG_REQUEST_NEW

explicitly prompt for new secrets from the user. This flag signals that NetworkManager thinks any existing secrets are invalid or wrong. This flag implies that interaction is allowed.

  

NM_SECRET_AGENT_GET_SECRETS_FLAG_USER_REQUESTED

set if the request was initiated by user-requested action via the D-Bus interface, as opposed to automatically initiated by NetworkManager in response to (for example) scan results or carrier changes.

  

NM_SECRET_AGENT_IDENTIFIER

#define NM_SECRET_AGENT_IDENTIFIER          "identifier"

NM_SECRET_AGENT_AUTO_REGISTER

#define NM_SECRET_AGENT_AUTO_REGISTER       "auto-register"

NM_SECRET_AGENT_REGISTERED

#define NM_SECRET_AGENT_REGISTERED          "registered"

NM_SECRET_AGENT_CAPABILITIES

#define NM_SECRET_AGENT_CAPABILITIES        "capabilities"

NM_SECRET_AGENT_REGISTRATION_RESULT

#define NM_SECRET_AGENT_REGISTRATION_RESULT "registration-result"

Property Details

The “auto-register” property

  “auto-register”            gboolean

Flags: Read / Write / Construct

Default value: TRUE

The “capabilities” property

  “capabilities”             NMSecretAgentCapabilities

Flags: Read / Write / Construct

The “identifier” property

  “identifier”               gchar *

Flags: Read / Write / Construct Only

Default value: NULL

The “registered” property

  “registered”               gboolean

Flags: Read

Default value: FALSE

Signal Details

The “registration-result” signal

void
user_function (NMSecretAgent *agent,
               gpointer       error,
               gpointer       user_data)

Flags: Run First

Generated by GTK-Doc V1.21