/mandos/trunk

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/trunk
423 by Teddy Hogeborn
Documentation changes:
1
		   -*- mode: org; coding: utf-8 -*-
2
3
		    Mandos Server D-Bus Interface
4
5
This file documents the D-Bus interface to the Mandos server.
6
7
* Bus: System bus
24.1.186 by Björn Påhlsson
transitional stuff actually working
8
  Bus name: "se.recompile.Mandos"
423 by Teddy Hogeborn
Documentation changes:
9
10
11
* Object Paths:
12
  
13
  | Path                  | Object            |
14
  |-----------------------+-------------------|
15
  | "/"                   | The Mandos Server |
785 by Teddy Hogeborn
Support the standard org.freedesktop.DBus.ObjectManager interface.
16
17
  (To get a list of paths to client objects, use the standard D-Bus
18
  org.freedesktop.DBus.ObjectManager interface, which the server
19
  object supports.)
20
21
423 by Teddy Hogeborn
Documentation changes:
22
* Mandos Server Interface:
24.1.186 by Björn Påhlsson
transitional stuff actually working
23
  Interface name: "se.recompile.Mandos"
423 by Teddy Hogeborn
Documentation changes:
24
  
25
** Methods:
26
*** RemoveClient(o: ObjectPath)  nothing
27
    Removes a client
28
   
29
** Signals:
962 by Teddy Hogeborn
Add support for using raw public keys in TLS (RFC 7250)
30
*** ClientNotFound(s: KeyID, s: Address)
31
    A client connected from Address using KeyID, but was
32
    rejected because it was not found in the server.  The key ID
423 by Teddy Hogeborn
Documentation changes:
33
    is represented as a string of hexadecimal digits.  The address is
34
    an IPv4 or IPv6 address in its normal string format.
35
36
37
* Mandos Client Interface:
24.1.186 by Björn Påhlsson
transitional stuff actually working
38
  Interface name: "se.recompile.Mandos.Client"
423 by Teddy Hogeborn
Documentation changes:
39
  
40
** Methods
41
*** Approve(b: Approve)  nothing
42
    Approve or deny a connected client waiting for approval.  If
43
    denied, a client will not be sent its secret.
44
    
45
*** CheckedOK()  nothing
46
    Assert that this client has been checked and found to be alive.
47
    This will restart the timeout before disabling this client.  See
48
    also the "LastCheckedOK" property.
49
50
** Properties
51
   
52
   Note: Many of these properties directly correspond to a setting in
53
   "clients.conf", in which case they are fully documented in
54
   mandos-clients.conf(5).
55
   
442 by Teddy Hogeborn
* DBUS-API: Document new "LastApprovalRequest" client property.
56
   | Name                    | Type | Access     | clients.conf        |
57
   |-------------------------+------+------------+---------------------|
58
   | ApprovedByDefault       | b    | Read/Write | approved_by_default |
59
   | ApprovalDelay (a)       | t    | Read/Write | approval_delay      |
60
   | ApprovalDuration (a)    | t    | Read/Write | approval_duration   |
61
   | ApprovalPending (b)     | b    | Read       | N/A                 |
62
   | Checker                 | s    | Read/Write | checker             |
63
   | CheckerRunning (c)      | b    | Read/Write | N/A                 |
64
   | Created (d)             | s    | Read       | N/A                 |
65
   | Enabled (e)             | b    | Read/Write | N/A                 |
24.1.179 by Björn Påhlsson
New feature:
66
   | Expires (f)             | s    | Read       | N/A                 |
497 by Teddy Hogeborn
* DBUS-API: Document new "Expires" and "ExtendedTimeout" properties.
67
   | ExtendedTimeout (a)     | t    | Read/Write | extended_timeout    |
442 by Teddy Hogeborn
* DBUS-API: Document new "LastApprovalRequest" client property.
68
   | Fingerprint             | s    | Read       | fingerprint         |
962 by Teddy Hogeborn
Add support for using raw public keys in TLS (RFC 7250)
69
   | KeyID                   | s    | Read       | key_id              |
442 by Teddy Hogeborn
* DBUS-API: Document new "LastApprovalRequest" client property.
70
   | Host                    | s    | Read/Write | host                |
71
   | Interval (a)            | t    | Read/Write | interval            |
24.1.179 by Björn Påhlsson
New feature:
72
   | LastApprovalRequest (g) | s    | Read       | N/A                 |
73
   | LastCheckedOK (h)       | s    | Read/Write | N/A                 |
556 by Teddy Hogeborn
* DBUS-API (se.recompile.Mandos.Client.LastCheckerStatus): New
74
   | LastCheckerStatus (i)   | n    | Read       | N/A                 |
75
   | LastEnabled (j)         | s    | Read       | N/A                 |
442 by Teddy Hogeborn
* DBUS-API: Document new "LastApprovalRequest" client property.
76
   | Name                    | s    | Read       | (Section name)      |
556 by Teddy Hogeborn
* DBUS-API (se.recompile.Mandos.Client.LastCheckerStatus): New
77
   | Secret (k)              | ay   | Write      | secret (or secfile) |
442 by Teddy Hogeborn
* DBUS-API: Document new "LastApprovalRequest" client property.
78
   | Timeout (a)             | t    | Read/Write | timeout             |
423 by Teddy Hogeborn
Documentation changes:
79
   
80
   a) Represented as milliseconds.
81
   
82
   b) An approval is currently pending.
83
   
781 by Teddy Hogeborn
Deprecate some D-Bus methods in favor of D-Bus properties.
84
   c) Changing this property can either start a new checker or abort a
85
      running one.
423 by Teddy Hogeborn
Documentation changes:
86
   
477 by Teddy Hogeborn
* DBUS-API: Fix grammar.
87
   d) The creation time of this client object, as an RFC 3339 string.
423 by Teddy Hogeborn
Documentation changes:
88
   
781 by Teddy Hogeborn
Deprecate some D-Bus methods in favor of D-Bus properties.
89
   e) Changing this property enables or disables a client.
423 by Teddy Hogeborn
Documentation changes:
90
   
24.1.179 by Björn Påhlsson
New feature:
91
   f) The date and time this client will be disabled, as an RFC 3339
518.2.3 by Teddy Hogeborn
Make "enabled" a client config option.
92
      string, or an empty string if this is not scheduled.
24.1.179 by Björn Påhlsson
New feature:
93
   
497 by Teddy Hogeborn
* DBUS-API: Document new "Expires" and "ExtendedTimeout" properties.
94
   g) The date and time of the last approval request, as an RFC 3339
95
      string, or an empty string if this has not happened.
96
   
97
   h) The date and time a checker was last successful, as an RFC 3339
98
      string, or an empty string if this has not happened.  Setting
99
      this property is equivalent to calling CheckedOK(), i.e. the
100
      current time is set, regardless of the string sent.  Please
101
      always use an empty string when setting this property, to allow
102
      for possible future expansion.
103
   
556 by Teddy Hogeborn
* DBUS-API (se.recompile.Mandos.Client.LastCheckerStatus): New
104
   i) The exit status of the last checker, -1 if it did not exit
105
      cleanly, -2 if a checker has not yet returned.
106
   
107
   j) The date and time this client was last enabled, as an RFC 3339
497 by Teddy Hogeborn
* DBUS-API: Document new "Expires" and "ExtendedTimeout" properties.
108
      string, or an empty string if this has not happened.
423 by Teddy Hogeborn
Documentation changes:
109
   
556 by Teddy Hogeborn
* DBUS-API (se.recompile.Mandos.Client.LastCheckerStatus): New
110
   k) A raw byte array, not hexadecimal digits.
423 by Teddy Hogeborn
Documentation changes:
111
112
** Signals
783 by Teddy Hogeborn
Revert change to D-Bus API.
113
*** CheckerCompleted(n: Exitcode, x: Waitstatus, s: Command)
423 by Teddy Hogeborn
Documentation changes:
114
    A checker (Command) has completed.  Exitcode is either the exit
783 by Teddy Hogeborn
Revert change to D-Bus API.
115
    code or -1 for abnormal exit.  In any case, the full Waitstatus
116
    (as from wait(2)) is also available.
423 by Teddy Hogeborn
Documentation changes:
117
    
118
*** CheckerStarted(s: Command)
119
    A checker command (Command) has just been started.
120
    
121
*** GotSecret()
122
    This client has been sent its secret.
123
    
124
*** NeedApproval(t: Timeout, b: ApprovedByDefault)
125
    This client will be approved or denied in exactly Timeout
126
    milliseconds, depending on ApprovedByDefault.  Approve() can now
127
    usefully be called on this client object.
477 by Teddy Hogeborn
* DBUS-API: Fix grammar.
128
    
423 by Teddy Hogeborn
Documentation changes:
129
*** Rejected(s: Reason)
130
    This client was not given its secret for a specified Reason.
131
444 by Teddy Hogeborn
Update copyright year to "2010" wherever appropriate.
132
* Copyright
133
969 by Teddy Hogeborn
Update copyright year to 2019
134
    Copyright © 2010-2019 Teddy Hogeborn
135
    Copyright © 2010-2019 Björn Påhlsson
444 by Teddy Hogeborn
Update copyright year to "2010" wherever appropriate.
136
  
137
** License:
907 by Teddy Hogeborn
Alter copyright notices slightly. Actual license is unchanged!
138
139
   This file is part of Mandos.
140
141
   Mandos is free software: you can redistribute it and/or modify it
142
   under the terms of the GNU General Public License as published by
143
   the Free Software Foundation, either version 3 of the License, or
144
   (at your option) any later version.
145
146
   Mandos is distributed in the hope that it will be useful, but
444 by Teddy Hogeborn
Update copyright year to "2010" wherever appropriate.
147
   WITHOUT ANY WARRANTY; without even the implied warranty of
148
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
149
   General Public License for more details.
150
151
   You should have received a copy of the GNU General Public License
907 by Teddy Hogeborn
Alter copyright notices slightly. Actual license is unchanged!
152
   along with Mandos.  If not, see <http://www.gnu.org/licenses/>.
444 by Teddy Hogeborn
Update copyright year to "2010" wherever appropriate.
153
423 by Teddy Hogeborn
Documentation changes:
154

155
#+STARTUP: showall