/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:
30
*** ClientNotFound(s: Fingerprint, s: Address)
31
    A client connected from Address using Fingerprint, but was
32
    rejected because it was not found in the server.  The fingerprint
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         |
69
   | Host                    | s    | Read/Write | host                |
70
   | Interval (a)            | t    | Read/Write | interval            |
24.1.179 by Björn Påhlsson
New feature:
71
   | LastApprovalRequest (g) | s    | Read       | N/A                 |
72
   | LastCheckedOK (h)       | s    | Read/Write | N/A                 |
556 by Teddy Hogeborn
* DBUS-API (se.recompile.Mandos.Client.LastCheckerStatus): New
73
   | LastCheckerStatus (i)   | n    | Read       | N/A                 |
74
   | LastEnabled (j)         | s    | Read       | N/A                 |
442 by Teddy Hogeborn
* DBUS-API: Document new "LastApprovalRequest" client property.
75
   | Name                    | s    | Read       | (Section name)      |
556 by Teddy Hogeborn
* DBUS-API (se.recompile.Mandos.Client.LastCheckerStatus): New
76
   | Secret (k)              | ay   | Write      | secret (or secfile) |
442 by Teddy Hogeborn
* DBUS-API: Document new "LastApprovalRequest" client property.
77
   | Timeout (a)             | t    | Read/Write | timeout             |
423 by Teddy Hogeborn
Documentation changes:
78
   
79
   a) Represented as milliseconds.
80
   
81
   b) An approval is currently pending.
82
   
781 by Teddy Hogeborn
Deprecate some D-Bus methods in favor of D-Bus properties.
83
   c) Changing this property can either start a new checker or abort a
84
      running one.
423 by Teddy Hogeborn
Documentation changes:
85
   
477 by Teddy Hogeborn
* DBUS-API: Fix grammar.
86
   d) The creation time of this client object, as an RFC 3339 string.
423 by Teddy Hogeborn
Documentation changes:
87
   
781 by Teddy Hogeborn
Deprecate some D-Bus methods in favor of D-Bus properties.
88
   e) Changing this property enables or disables a client.
423 by Teddy Hogeborn
Documentation changes:
89
   
24.1.179 by Björn Påhlsson
New feature:
90
   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.
91
      string, or an empty string if this is not scheduled.
24.1.179 by Björn Påhlsson
New feature:
92
   
497 by Teddy Hogeborn
* DBUS-API: Document new "Expires" and "ExtendedTimeout" properties.
93
   g) The date and time of the last approval request, as an RFC 3339
94
      string, or an empty string if this has not happened.
95
   
96
   h) The date and time a checker was last successful, as an RFC 3339
97
      string, or an empty string if this has not happened.  Setting
98
      this property is equivalent to calling CheckedOK(), i.e. the
99
      current time is set, regardless of the string sent.  Please
100
      always use an empty string when setting this property, to allow
101
      for possible future expansion.
102
   
556 by Teddy Hogeborn
* DBUS-API (se.recompile.Mandos.Client.LastCheckerStatus): New
103
   i) The exit status of the last checker, -1 if it did not exit
104
      cleanly, -2 if a checker has not yet returned.
105
   
106
   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.
107
      string, or an empty string if this has not happened.
423 by Teddy Hogeborn
Documentation changes:
108
   
556 by Teddy Hogeborn
* DBUS-API (se.recompile.Mandos.Client.LastCheckerStatus): New
109
   k) A raw byte array, not hexadecimal digits.
423 by Teddy Hogeborn
Documentation changes:
110
111
** Signals
783 by Teddy Hogeborn
Revert change to D-Bus API.
112
*** CheckerCompleted(n: Exitcode, x: Waitstatus, s: Command)
423 by Teddy Hogeborn
Documentation changes:
113
    A checker (Command) has completed.  Exitcode is either the exit
783 by Teddy Hogeborn
Revert change to D-Bus API.
114
    code or -1 for abnormal exit.  In any case, the full Waitstatus
115
    (as from wait(2)) is also available.
423 by Teddy Hogeborn
Documentation changes:
116
    
117
*** CheckerStarted(s: Command)
118
    A checker command (Command) has just been started.
119
    
120
*** GotSecret()
121
    This client has been sent its secret.
122
    
123
*** NeedApproval(t: Timeout, b: ApprovedByDefault)
124
    This client will be approved or denied in exactly Timeout
125
    milliseconds, depending on ApprovedByDefault.  Approve() can now
126
    usefully be called on this client object.
477 by Teddy Hogeborn
* DBUS-API: Fix grammar.
127
    
423 by Teddy Hogeborn
Documentation changes:
128
*** Rejected(s: Reason)
129
    This client was not given its secret for a specified Reason.
130
444 by Teddy Hogeborn
Update copyright year to "2010" wherever appropriate.
131
* Copyright
132
749.1.1 by Teddy Hogeborn
mandos: Use multiprocessing module to run checkers.
133
    Copyright © 2010-2015 Teddy Hogeborn
134
    Copyright © 2010-2015 Björn Påhlsson
444 by Teddy Hogeborn
Update copyright year to "2010" wherever appropriate.
135
  
136
** License:
137
   
138
   This program is free software: you can redistribute it and/or
139
   modify it under the terms of the GNU General Public License as
140
   published by the Free Software Foundation, either version 3 of the
141
   License, or (at your option) any later version.
142
143
   This program is distributed in the hope that it will be useful, but
144
   WITHOUT ANY WARRANTY; without even the implied warranty of
145
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
146
   General Public License for more details.
147
148
   You should have received a copy of the GNU General Public License
149
   along with this program.  If not, see
150
   <http://www.gnu.org/licenses/>.
151
423 by Teddy Hogeborn
Documentation changes:
152

153
#+STARTUP: showall