<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>org.freedesktop.NetworkManager.SecretAgent: NetworkManager Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="NetworkManager Reference Manual">
<link rel="up" href="dbus-secret-agent.html" title="Secret agents">
<link rel="prev" href="dbus-secret-agent.html" title="Secret agents">
<link rel="next" href="vpn-plugins.html" title="Part V. VPN Plugin D-Bus API Reference">
<meta name="generator" content="GTK-Doc V1.33.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts">
<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span>
<a href="#gdbus-org.freedesktop.NetworkManager.SecretAgent.description" class="shortcut">Description</a></span>
</td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="dbus-secret-agent.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="dbus-secret-agent.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="vpn-plugins.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="gdbus-org.freedesktop.NetworkManager.SecretAgent"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="gdbus-interface-org-freedesktop-NetworkManager-SecretAgent.top_of_page"></a>org.freedesktop.NetworkManager.SecretAgent</span></h2>
<p>org.freedesktop.NetworkManager.SecretAgent — User Secret Agent</p>
</td>
<td class="gallery_image" valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<h2>Methods</h2>
<pre class="synopsis">
<a class="link" href="gdbus-org.freedesktop.NetworkManager.SecretAgent.html#gdbus-method-org-freedesktop-NetworkManager-SecretAgent.GetSecrets" title="The GetSecrets() method">GetSecrets</a> (IN a{sa{sv}} connection,
IN o connection_path,
IN s setting_name,
IN as hints,
IN u flags,
OUT a{sa{sv}} secrets);
<a class="link" href="gdbus-org.freedesktop.NetworkManager.SecretAgent.html#gdbus-method-org-freedesktop-NetworkManager-SecretAgent.CancelGetSecrets" title="The CancelGetSecrets() method">CancelGetSecrets</a> (IN o connection_path,
IN s setting_name);
<a class="link" href="gdbus-org.freedesktop.NetworkManager.SecretAgent.html#gdbus-method-org-freedesktop-NetworkManager-SecretAgent.SaveSecrets" title="The SaveSecrets() method">SaveSecrets</a> (IN a{sa{sv}} connection,
IN o connection_path);
<a class="link" href="gdbus-org.freedesktop.NetworkManager.SecretAgent.html#gdbus-method-org-freedesktop-NetworkManager-SecretAgent.DeleteSecrets" title="The DeleteSecrets() method">DeleteSecrets</a> (IN a{sa{sv}} connection,
IN o connection_path);
</pre>
</div>
<div class="refsect1">
<a name="gdbus-interface-org-freedesktop-NetworkManager-SecretAgent"></a><h2>Description</h2>
<p> Private D-Bus interface used by secret agents that store and provide
secrets to NetworkManager. If an agent provides secrets to NetworkManager
as part of connection creation, and the some of those secrets are "agent
owned" the agent should store those secrets itself and should not expect
its SaveSecrets() method to be called. SaveSecrets() will be called eg if
some program other than the agent itself (like a connection editor)
changes the secrets out of band. The agent should implement this D-Bus
interface on an object with the path
/org/freedesktop/NetworkManager/SecretAgent.
</p>
</div>
<div class="refsect1">
<a name="gdbus-methods-org.freedesktop.NetworkManager.SecretAgent"></a><h2>Method Details</h2>
<div class="refsect2">
<a name="gdbus-method-org-freedesktop-NetworkManager-SecretAgent.GetSecrets"></a><h3>The GetSecrets() method</h3>
<pre class="programlisting">
GetSecrets (IN a{sa{sv}} connection,
IN o connection_path,
IN s setting_name,
IN as hints,
IN u flags,
OUT a{sa{sv}} secrets);
</pre>
<p> Retrieve and return stored secrets, if any, or request new secrets from
the agent's user. If user interaction is allowed and the user enters new
secrets, the agent is expected to save the new secrets to persistent
storage (if the secret's flags include AGENT_OWNED) as NetworkManager will
not send these secrets back to the same agent via a SaveSecrets() call. If
the user canceled any interaction, the agent should return the
UserCanceled error (see below).
</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><code class="literal">IN a{sa{sv}} <em class="parameter"><code>connection</code></em></code>:</span></p></td>
<td><p>Nested settings maps containing the connection for which secrets are being requested. This may contain system-owned secrets if the agent has successfully authenticated to modify system network settings and the GetSecrets request flags allow user interaction.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="literal">IN o <em class="parameter"><code>connection_path</code></em></code>:</span></p></td>
<td><p>Object path of the connection for which secrets are being requested.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="literal">IN s <em class="parameter"><code>setting_name</code></em></code>:</span></p></td>
<td><p>Setting name for which secrets are being requested.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="literal">IN as <em class="parameter"><code>hints</code></em></code>:</span></p></td>
<td><p>Array of strings of key names in the requested setting for which NetworkManager thinks a secrets may be required, and/or well-known identifiers and data that may be useful to the client in processing the secrets request. Note that it's not always possible to determine which secret is required, so in some cases no hints may be given. The Agent should return any secrets it has, or that it thinks are required, regardless of what hints NetworkManager sends in this request. Some hints have special prefixes that provide information to the agent; for example, VPN requests may send server-specific messages prefixed with "x-vpn-message:".</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="literal">IN u <em class="parameter"><code>flags</code></em></code>:</span></p></td>
<td><p>(<a class="link" href="nm-dbus-types.html#NMSecretAgentGetSecretsFlags" title="enum NMSecretAgentGetSecretsFlags">NMSecretAgentGetSecretsFlags</a>) Flags which modify the behavior of the secrets request. If true, new secrets are assumed to be invalid or incorrect, and the agent should ask the user for new secrets. If false, existing secrets should be retrieved from storage and returned without interrupting the user.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="literal">OUT a{sa{sv}} <em class="parameter"><code>secrets</code></em></code>:</span></p></td>
<td><p>Nested settings maps containing secrets. Each setting MUST contain at least the 'name' field, containing the name of the setting, and one or more secrets.</p></td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="gdbus-method-org-freedesktop-NetworkManager-SecretAgent.CancelGetSecrets"></a><h3>The CancelGetSecrets() method</h3>
<pre class="programlisting">
CancelGetSecrets (IN o connection_path,
IN s setting_name);
</pre>
<p> Cancel a pending GetSecrets request for secrets of the given connection.
Any GetSecrets request with the same 'connection_path' and 'setting_name'
that are given in a CancelGetSecrets request should be canceled.
</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><code class="literal">IN o <em class="parameter"><code>connection_path</code></em></code>:</span></p></td>
<td><p>Object path of the connection for which, if secrets for the given 'setting_name' are being requested, the request should be canceled.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="literal">IN s <em class="parameter"><code>setting_name</code></em></code>:</span></p></td>
<td><p>Setting name for which secrets for this connection were originally being requested.</p></td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="gdbus-method-org-freedesktop-NetworkManager-SecretAgent.SaveSecrets"></a><h3>The SaveSecrets() method</h3>
<pre class="programlisting">
SaveSecrets (IN a{sa{sv}} connection,
IN o connection_path);
</pre>
<p> Save given secrets to backing storage.
</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><code class="literal">IN a{sa{sv}} <em class="parameter"><code>connection</code></em></code>:</span></p></td>
<td><p>Nested settings maps containing the entire connection (including secrets), for which the agent should save the secrets to backing storage. This method will not be called when the agent itself is the process creating or updating a connection; in that case the agent is assumed to have already saved those secrets since it had them already.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="literal">IN o <em class="parameter"><code>connection_path</code></em></code>:</span></p></td>
<td><p>Object path of the connection for which the agent should save secrets to backing storage.</p></td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="gdbus-method-org-freedesktop-NetworkManager-SecretAgent.DeleteSecrets"></a><h3>The DeleteSecrets() method</h3>
<pre class="programlisting">
DeleteSecrets (IN a{sa{sv}} connection,
IN o connection_path);
</pre>
<p> Delete secrets from backing storage.
</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><code class="literal">IN a{sa{sv}} <em class="parameter"><code>connection</code></em></code>:</span></p></td>
<td><p>Nested settings maps containing the connection properties (sans secrets), for which the agent should delete the secrets from backing storage.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="literal">IN o <em class="parameter"><code>connection_path</code></em></code>:</span></p></td>
<td><p>Object path of the connection for which the agent should delete secrets from backing storage.</p></td>
</tr>
</tbody>
</table></div>
</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.33.1</div>
</body>
</html>