summaryrefslogtreecommitdiffstats
path: root/secret-service/org.freedesktop.Secrets.xml
blob: cee47e9ec03933f3381890c00ca31e77a9e1b031 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">

<!--
 * This is the well known dbus service name for controlling the
 * entire daemon. The service manages collections of secrets. These
 * are analogous to the gnome-keyring 'keyrings'.
-->
<tp:spec xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
    <tp:title>Secret Service API Specification</tp:title>
    <tp:version>0.1</tp:version>
    <tp:copyright>
      Copyright (C) 2009 Stef Walter &lt;stef@memberwebs.com&gt;
    </tp:copyright>
    <tp:copyright>
      Copyright (C) 2009 Michael Leupold &lt;lemma@confuego.org&gt;
    </tp:copyright>

    <!--
     * ======================================================================================
     * ERROR CODES
     *
    -->

    <tp:errors namespace="org.freedesktop.Secret.Error">
        <tp:docstring>Errors returned by the Secret Service API.</tp:docstring>
        <tp:error name="IsLocked">
            <tp:docstring>The object must be unlocked before this action can be carried out.</tp:docstring>
        </tp:error>
        <tp:error name="NoSession">
            <tp:docstring>The session does not exist.</tp:docstring>
         </tp:error>
        <tp:error name="NoSuchObject">
            <tp:docstring>No such item or collection exists.</tp:docstring>
        </tp:error>
    </tp:errors>

    <!--
     * ======================================================================================
     * SECRET STRUCT
     * Signature: (oayays)
     *
    -->

    <tp:struct name="Secret">
        <tp:docstring>The Secret type holds a (possibly encoded) secret.</tp:docstring>
        <tp:member type="o" name="session">
            <tp:docstring>The session that was used to encode the secret.</tp:docstring>
        </tp:member>
        <tp:member type="ay" name="parameters">
            <tp:docstring>Algorithm dependent parameters for secret value encoding.</tp:docstring>
        </tp:member>
        <tp:member type="ay" name="value">
            <tp:docstring>Possibly encoded secret value</tp:docstring>
        </tp:member>
        <tp:member type="s" name="content_type">
            <tp:docstring>The content type of the secret. For example: 'text/plain; charset=utf8'</tp:docstring>
	</tp:member>
    </tp:struct>

    <tp:mapping name="ObjectPath_Secret_Map">
        <tp:docstring>A mapping from object-paths to Secret structs</tp:docstring>
        <tp:member type="o" name="Key">
            <tp:docstring>D-Bus object-path</tp:docstring>
        </tp:member>
        <tp:member type="(oayays)" name="Value" tp:type="Secret">
            <tp:docstring>A secret</tp:docstring>
        </tp:member>
    </tp:mapping>

    <!--
     * ======================================================================================
     * SERVICE INTERFACE
     *
    -->

    <node name="/org/freedesktop/Secrets">

        <interface name="org.freedesktop.Secret.Service">

            <tp:docstring>
                The Secret Service manages all the sessions and collections.
            </tp:docstring>

            <property name="Collections" type="ao" access="read">
                <tp:docstring>The object paths of all collections (ie: keyrings)</tp:docstring>
            </property>

            <method name="OpenSession">
                <tp:docstring>Open a unique session for the caller application.</tp:docstring>
                <arg name="algorithm" type="s" direction="in">
                    <tp:docstring>The algorithm the caller wishes to use.</tp:docstring>
                </arg>
                <arg name="input" type="v" direction="in">
                    <tp:docstring>Input arguments for the algorithm.</tp:docstring>
                </arg>
                <arg name="output" type="v" direction="out">
                    <tp:docstring>Output of the session algorithm negotiation.</tp:docstring>
                </arg>
                <arg name="result" type="o" direction="out">
                    <tp:docstring>The object path of the session, if session was created.</tp:docstring>
                </arg>
            </method>

            <method name="CreateCollection">
                <tp:docstring>Create a new collection with the specified properties.</tp:docstring>
                <arg name="properties" type="a{sv}" direction="in">
                    <tp:docstring xmlns:docbook="http://docbook.org/ns/docbook">
                        <para>
                            Properties for the new collection. This allows setting the new collection's
                            properties upon its creation. All READWRITE properties are useable. Specify
                            the property names in full interface.Property form.
                            <example>
                                <title>Example for properties</title>
                                <programlisting>
<![CDATA[
properties = { "org.freedesktop.Secret.Collection.Label": "MyCollection" }
]]>
                                </programlisting>
                            </example>
                        </para>
                    </tp:docstring>
                </arg>
                <arg name="alias" type="s" direction="in">
                    <tp:docstring xmlns:docbook="http://docbook.org/ns/docbook">
                        <para>
                            If creating this connection for a well known alias then a string like
                            <literal>default</literal>. If an collection with this well-known alias already
                            exists, then that collection will be returned instead of creating a new
                            collection. Any readwrite properties provided to this function will be set on
                            the collection.
                        </para>
                        <para>
                            Set this to an empty string if the new collection should not be associated with a
                            well known alias.
                        </para>
                    </tp:docstring>
                </arg>
                <arg name="collection" type="o" direction="out">
                    <tp:docstring>The new collection object, or '/' if prompting is necessary.</tp:docstring>
                </arg>
                <arg name="prompt" type="o" direction="out">
                    <tp:docstring>A prompt object if prompting is necessary, or '/' if no prompt was needed.</tp:docstring>
                </arg>
            </method>

            <method name="SearchItems">
                <tp:docstring>Find items in any collection.</tp:docstring>
                <arg name="attributes" type="a{ss}" direction="in">
                    <tp:docstring>Find secrets in any collection.</tp:docstring>
                </arg>
                <arg name="unlocked" type="ao" direction="out">
                    <tp:docstring>Items found.</tp:docstring>
                </arg>
                <arg name="locked" type="ao" direction="out">
                    <tp:docstring>Items found that require authentication.</tp:docstring>
                </arg>
            </method>

            <method name="Unlock">
                <tp:docstring>Unlock the specified objects.</tp:docstring>
                <arg name="objects" type="ao" direction="in">
                    <tp:docstring>Objects to unlock.</tp:docstring>
                </arg>
                <arg name="unlocked" type="ao" direction="out">
                    <tp:docstring>Objects that were unlocked without a prompt.</tp:docstring>
                </arg>
                <arg name="prompt" type="o" direction="out">
                    <tp:docstring>A prompt object which can be used to unlock the remaining objects, or the special value '/' when no prompt is necessary.</tp:docstring>
                </arg>
            </method>

            <method name="Lock">
                <tp:docstring>Lock the items.</tp:docstring>
                <arg name="objects" type="ao" direction="in">
                    <tp:docstring>Objects to lock.</tp:docstring>
                </arg>
                <arg name="locked" type="ao" direction="out">
                    <tp:docstring>Objects that were locked without a prompt.</tp:docstring>
                </arg>
                <arg name="Prompt" type="o" direction="out">
                    <tp:docstring>A prompt to lock the objects, or the special value '/' when no prompt is necessary.</tp:docstring>
                </arg>
            </method>

            <method name="GetSecrets">
                <tp:docstring>Retrieve multiple secrets from different items.</tp:docstring>
                <arg name="items" type="ao" direction="in">
                    <tp:docstring>Items to get secrets for.</tp:docstring>
                </arg>
                <arg name="session" type="o" direction="in">
                    <tp:docstring>The session to use to encode the secrets.</tp:docstring>
                </arg>
                <arg name="secrets" type="a{o(oayays)}" direction="out" tp:type="ObjectPath_Secret_Map">
                    <tp:docstring>Secrets for the items.</tp:docstring>
                </arg>
            </method>

            <method name="ReadAlias">
                <tp:docstring>Get the collection with the given alias.</tp:docstring>
                <arg name="name" type='s' direction='in'>
                    <tp:docstring>An alias, such as 'default'.</tp:docstring>
                </arg>
                <arg name="collection" type='o' direction='out'>
                    <tp:docstring>The collection or the the path '/' if no such collection exists.</tp:docstring>
                </arg>
            </method>

            <method name="SetAlias">
                <tp:docstring>Setup a collection alias.</tp:docstring>
                <arg name="name" type='s' direction='in'>
                    <tp:docstring>An alias, such as 'default'.</tp:docstring>
                </arg>
                <arg name="collection" type='o' direction='in'>
                    <tp:docstring>
                        The collection to make the alias point to. To remove an alias use the special value '/'.
                    </tp:docstring>
                </arg>
            </method>

            <signal name="CollectionCreated">
                <tp:docstring>A collection was created.</tp:docstring>
                <arg name="collection" type="o">
                    <tp:docstring>Collection that was created</tp:docstring>
                </arg>
            </signal>

            <signal name="CollectionDeleted">
                <tp:docstring>A collection was deleted.</tp:docstring>
                <arg name="collection" type="o">
                    <tp:docstring>Collection that was deleted.</tp:docstring>
                </arg>
            </signal>

            <signal name="CollectionChanged">
                <tp:docstring>A collection was changed.</tp:docstring>
                <arg name="collection" type="o">
                    <tp:docstring>Collection that was changed.</tp:docstring>
                </arg>
            </signal>

        </interface>

    </node>

    <!--
     * ======================================================================================
     * COLLECTION INTERFACE
     *
    -->

    <node name="/org/freedesktop/Secrets/collection/xxxx">

        <interface name="org.freedesktop.Secret.Collection">

            <tp:docstring>A collection of items containing secrets.</tp:docstring>

            <property name="Items" type="ao" access="read">
                <tp:docstring>Items in this collection.</tp:docstring>
            </property>

            <property name="Label" type="s" access="readwrite">
                <tp:docstring>The displayable label of this collection.</tp:docstring>
            </property>

            <property name="Locked" type="s" access="read">
                <tp:docstring>
                    Whether the collection is locked and must be authenticated by the client application.
                </tp:docstring>
            </property>

            <property name="Created" type="t" access="read">
                <tp:docstring>The unix time when the collection was created.</tp:docstring>
            </property>

            <property name="Modified" type="t" access="read">
                <tp:docstring>The unix time when the collection was last modified.</tp:docstring>
            </property>

            <method name="Delete">
                <tp:docstring>Delete this collection.</tp:docstring>
                <arg name="prompt" type="o" direction="out">
                    <tp:docstring>A prompt to delete the collection, or the special value '/' when no prompt is necessary.</tp:docstring>
                </arg>
            </method>

            <method name="SearchItems">
                <tp:docstring>Search for items in this collection matching the lookup attributes.</tp:docstring>
                <arg name="attributes" type="a{ss}" direction="in">
                    <tp:docstring>Attributes to match.</tp:docstring>
                </arg>
                <arg name="results" type="ao" direction="out">
                    <tp:docstring>Items that matched the attributes.</tp:docstring>
                </arg>
            </method>

            <method name="CreateItem">
                <tp:docstring>Create an item with the given attributes, secret and label. If replace is set, then it replaces an item already present with the same values for the attributes.</tp:docstring>
                <arg name="properties" type="a{sv}" direction="in">
                    <tp:docstring>The properties for the new item.</tp:docstring>
                    <tp:docstring xmlns:docbook="http://docbook.org/ns/docbook">
                        <para>
                            Properties for the new item. This allows setting the new item's
                            properties upon its creation. All READWRITE properties are useable.
                            Specify the property names in full interface.Property form.
                            <example>
                                <title>Example for properties</title>
                                <programlisting>
<![CDATA[
properties = {
               "org.freedesktop.Secret.Item.Label": "MyItem",
               "org.freedesktop.Secret.Item.Attributes": {
                          "Attribute1": "Value1",
                          "Attribute2": "Value2"
                    }
             }
]]>
                                </programlisting>
                            </example>
                            <note>
                                <para>
                                    Please note that there is a distinction between the terms
                                    <emphasis>Property</emphasis>, which refers to a D-Bus properties
                                    of an object, and <emphasis>Attribute</emphasis>, which refers to one
                                    of a secret item's string-valued attributes.
                                </para>
                            </note>
                        </para>
                    </tp:docstring>
                </arg>
                <arg name="secret" type="(oayays)" tp:type="Secret" direction="in">
                    <tp:docstring>The secret to store in the item, encoded with the included session.</tp:docstring>
                </arg>
                <arg name="replace" type="b" direction="in">
                    <tp:docstring>Whether to replace an item with the same attributes or not.</tp:docstring>
                </arg>
                <arg name="item" type="o" direction="out">
                    <tp:docstring>The item created, or the special value '/' if a prompt is necessary.</tp:docstring>
                </arg>
                <arg name="prompt" type="o" direction="out">
                    <tp:docstring>A prompt object, or the special value '/' if no prompt is necessary.</tp:docstring>
                </arg>
            </method>

            <signal name="ItemCreated">
                <tp:docstring>A new item in this collection was created.</tp:docstring>
                <arg name="item" type="o">
                    <tp:docstring>The item that was created.</tp:docstring>
                </arg>
            </signal>

            <signal name="ItemDeleted">
                <tp:docstring>An item in this collection was deleted.</tp:docstring>

                <arg name="item" type="o">
                    <tp:docstring>The item that was deleted.</tp:docstring>
                </arg>
            </signal>

            <signal name="ItemChanged">
                <tp:docstring>An item in this collection changed.</tp:docstring>

                <arg name="item" type="o">
                    <tp:docstring>The item that was changed.</tp:docstring>
                </arg>
            </signal>

        </interface>

    </node>

    <!--
     * ======================================================================================
     * ITEM INTERFACE
     *
    -->

    <node name="/org/freedesktop/Secret/collection/xxxx/iiii">

        <interface name="org.freedesktop.Secret.Item">

            <tp:docstring>An item contains a secret, lookup attributes and has a label.</tp:docstring>

            <property name="Locked" type="b" access="read">
                <tp:docstring>Whether the item is locked and requires authentication, or not.</tp:docstring>
            </property>

            <property name="Attributes" type="a{ss}" access="readwrite">
                <tp:docstring>The lookup attributes for this item.</tp:docstring>
            </property>

            <property name="Label" type="s" access="readwrite">
                <tp:docstring>The displayable label for this item.</tp:docstring>
            </property>

            <property name="Created" type="t" access="read">
                <tp:docstring>The unix time when the item was created.</tp:docstring>
            </property>

            <property name="Modified" type="t" access="read">
                <tp:docstring>The unix time when the item was last modified.</tp:docstring>
            </property>

            <method name="Delete">
                <tp:docstring>Delete this item.</tp:docstring>
                <arg name="Prompt" type="o" direction="out">
                     <tp:docstring>A prompt object, or the special value '/' if no prompt is necessary.</tp:docstring>
                </arg>
            </method>

            <method name="GetSecret">
                <tp:docstring>Retrieve the secret for this item.</tp:docstring>
                <arg name="session" type="o" direction="in">
                    <tp:docstring>The session to use to encode the secret.</tp:docstring>
                </arg>
                <arg name="secret" type="(oayays)" tp:type="Secret" direction="out">
                    <tp:docstring>The secret retrieved.</tp:docstring>
                </arg>
            </method>

            <method name="SetSecret">
                <tp:docstring>Set the secret for this item.</tp:docstring>
                <arg name="secret" type="(oayays)" tp:type="Secret" direction="in">
                    <tp:docstring>The secret to set, encoded for the included session.</tp:docstring>
                </arg>
            </method>

        </interface>

    </node>

    <!--
     * ======================================================================================
     * SESSION INTERFACE
     *
    -->

    <node name="/org/freedesktop/Secret/session/ssss">

        <interface name="org.freedesktop.Secret.Session">

            <tp:docstring>A session tracks state between the service and a client application.</tp:docstring>

            <method name="Close">
                <tp:docstring>Close this session.</tp:docstring>
            </method>

        </interface>

    </node>

    <!--
     * ======================================================================================
     * PROMPT INTERFACE
     *
    -->

    <node name="/org/freedesktop/Secret/prompts/pppp">

        <interface name="org.freedesktop.Secret.Prompt">
            <tp:docstring>A prompt necessary to complete an operation.</tp:docstring>

            <method name="Prompt">
                <tp:docstring>Perform the prompt.</tp:docstring>
                        <arg name="window-id" type="s" direction="in">
                            <tp:docstring>Platform specific window handle to use for
                    showing the prompt.</tp:docstring>
                        </arg>
            </method>

            <method name="Dismiss">
                <tp:docstring>Dismiss the prompt.</tp:docstring>
            </method>

            <signal name="Completed">
                <tp:docstring>The prompt and operation completed.</tp:docstring>
                <arg name="dismissed" type="b">
                    <tp:docstring>Whether the prompt and operation were dismissed or not.</tp:docstring>
                </arg>
                <arg name="result" type="v">
                    <tp:docstring>The possibly empty, operation specific,
                        result.</tp:docstring>
                </arg>
            </signal>

        </interface>

    </node>

</tp:spec>