-
Notifications
You must be signed in to change notification settings - Fork 9
/
Copy pathkcaldav.in.8
411 lines (411 loc) · 11.9 KB
/
kcaldav.in.8
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
.\" Copyright (c) Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt KCALDAV 8
.Os
.Sh NAME
.Nm kcaldav
.Nd simple CalDAV server
.\" .Sh LIBRARY
.\" For sections 2, 3, and 9 only.
.\" Not used in OpenBSD.
.Sh SYNOPSIS
.Nm kcaldav
.Sh DESCRIPTION
.Nm
is a CGI program that minimally implements CalDAV.
It interfaces with a calendar database
.Pa @CALDIR@/kcaldav.db
.Pq in the web server's file-system root
administered by
.Xr kcaldav.passwd 1 .
Its run-time configuration is specified by
.Xr kcaldav.conf 5 .
.Pp
For example, assume the CGI program available at:
.Pp
.Dl https://localhost@CGIURI@
.Pp
The calendar root
.Pa @CALDIR@
resolves to
.Pa @CALPREFIX@
on the host file-system.
It contains
.Pa kcaldav.db
created by
.Xr kcaldav.passwd 1
specifying a single principal
.Pa kristaps
with a single calendar collection
.Pa calendar
as created with
.Pp
.Dl # kcaldav.passwd -Cu kristaps
.Pp
Most CalDAV clients will ask for the CGI program name, principal name,
and password.
The program name in this example is as follows:
.Pp
.Dl https://localhost@CGIURI@
.Pp
This is further simplified if the web server is configured to handle a
.Qq well-known
service that redirects to the CGI program name, leaving the only
configuration to be the web server root:
.Pp
.Dl https://localhost
.Pp
For some older clients, the CGI program name will need to include the
principal's name as well as the program name:
.Pp
.Dl https://localhost@CGIURI@/kristaps/
.Pp
Lastly, there are some clients (possibly only Mozilla Lightning) that
must connect directly to an individual calendar, such as with:
.Pp
.Dl https://localhost@CGIURI@/kristaps/calendar/
.Ss Well-Known Service
Many modern calendar clients use
.Qq well-known
URI identifiers to query a host for its CalDAV.
To enable the
.Qq well-known
service for
.Nm ,
the web server's absolute path
.Pp
.Dl https://localhost/.well-known/caldav
.Pp
must return a 301 redirect to the absolute URL
.Pp
.Dl https://localhost@CGIURI@
.Pp
assuming
the CalDAV host such as in the example.
.Ss System-Wide Calendar Administration
Let the calendar directory be
.Pa @CALDIR@ ,
resolving to
.Pa @CALPREFIX@
in the host file-system, which is read-writable by the web server.
Let the dummy user
.Qq kcaldav
be the owner of the database files.
.Pp
First,
.Xr kcaldav.passwd 1
must be set-user-ID for modifying the file.
.Bd -literal -offset indent
# chown kcaldav @PREFIX@/bin/kcaldav.passwd
# chmod u+s @PREFIX@/bin/kcaldav.passwd
.Ed
.Pp
Create user principals as follows:
.Bd -literal -offset indent
# doas -u kcaldav kcaldav.passwd -Cu user1
# kcaldav.passwd -Cu user2
# ...
.Ed
.Pp
Now any local user can modify her principal's password without
administrator intervention.
.Pp
.Dl user1% kcaldav.passwd -f @CALPREFIX@
.Ss Local Calendar Administration
Let the calendar directory be
.Pa @CALDIR@ ,
resolving to
.Pa @CALPREFIX@
in the host file-system, which is read-writable by the web server.
The database may then be manipulated solely by root:
.Pp
.Dl # kcaldav.passwd -f @CALPREFIX@ -Cu user1
.Dl # kcaldav.passwd -f @CALPREFIX@ -Cu user2
.Dl # ...
.Pp
Local users may not modify the database.
.\" .Sh CONTEXT
.\" For section 9 functions only.
.Ss Web Calendar Administration
.Nm
has built-in support for web-based administration by logged-in
(using HTTP authentication) principals through a web application of
HTML5, JavaScript, and CSS pages using
.Nm
as a JSON backend.
.Pp
Assuming these page have been installed into
.Pa /var/www/htdocs/kcaldav ,
principals can then access the server root,
.Pp
.Dl https://localhost/kcaldav/home.html
.Pp
to see their configuration.
.Pp
The principal
.Qq foo
can modify collection information online.
.Em Note :
the calendar database must be read-writable by the web server.
In general, the directory containing the database will also need to be
writable by the web server for creating its temporary transaction files.
.Ss Logging
.Nm
output logging information in a form similar to the Apache Common Log Format:
.Bd -literal -offset indent
%h %l %u %t %m\en
.Ed
.Pp
The
.Li %m
value extends the format by containing the unquoted message contents.
.Pp
Output is written to
.Dv stderr
by default, or otherwise as specified in
.Xr kcaldav.conf 5 .
Logging verbosity is also specified in the configuration file,
defaulting to warning and error messages only.
.Sh HTTP METHODS
This section describes each supported HTTP method.
.Ss DELETE
The DELETE method is handled according to RFC 4918.
Principals must have
.Dv DELETE
access.
Resource deletions process the
.Dq If-Match
header, if applied, for conditional deletion.
.Pp
Collection deletions begin by removing the
.Pa kcaldav.conf
file, which renders the directory opaque to
.Nm .
Following that, all files are removed followed by the directory itself.
.Em Note :
it is possible to remove the principal's home URL!
.Ss GET
The GET method is supported for calendar resources (defined by
content-type) as defined by RFC 4918.
The
.Dq If-None-Match
header is processed and checks the file etag (MD5 sum).
In all cases, the principal must have been delegated read access.
.Pp
For the JSON content-type (i.e., web application resources),
.Nm
routes into a management framework.
Only the
.Pa index.html
resource in the server root directory is supported.
Requests for the empty root
.Pq Dq \e
are aliased to
.Pa index.html .
.Ss POST
The POST method is supported only for text/html requests for specific
management (JSON content-type) resources.
POST methods on calendar collections are interpreted by the management
framework as JSON form requests to change collection properties.
The principal must have been delegated write access.
.Ss PROPFIND
The PROPFIND method queries collection or resource properties.
The principal must have been delegated read access.
It accepts the
.Dq Depth
header for recursive reports.
The following is a table of get-able properties.
.Pp
.TS
l l.
calendar-color Apple extension
calendar-data RFC 4791, 9.6
calendar-description RFC 4791, 5.2.1
calendar-home-set RFC 4791, 6.2.1
calendar-proxy-read-for caldav-proxy.txt, 5.3.1
calendar-proxy-write-for caldav-proxy.txt, 5.3.2
calendar-timezone RFC 4791, 5.2.2
calendar-user-address-set RFC 6638, 2.4.1
current-user-principal RFC 5379, 3
current-user-privilege-set RFC 3744, 5.4
displayname RFC 4918, 15.2
getcontenttype RFC 4918, 15.5
getctag caldav-ctag-02, 4.1
getetag RFC 4918, 15.6
group-member-set RFC 3744, 4.3; caldav-proxy.txt
group-membership RFC 3744, 4.4; caldav-proxy.txt
min-date-time RFC 4791, 5.2.6
owner RFC 4918, 14.17
principal-URL RFC 3744, 4.2
quota-available-bytes RFC 4331, 3
quota-used-bytes RFC 4331, 4
resourcetype RFC 4918, 15.9
schedule-calendar-transp RFC 6638, 9.1
supported-calendar-component-set RFC 4791, 5.2.3
supported-calendar-data RFC 4791, 9.6
.TE
.Ss PROPPATCH
If the web server has write access to collection
.Pa kcaldav.conf
files and the principal has been delegated write access, its properties
may be modified.
The following is a table of settable properties.
.Pp
.TS
l l.
calendar-colour Apple extension
calendar-description RFC 4791, 5.2.1
displayname RFC 4918, 15.2
.TE
.Ss PUT
The PUT method is supported for calendar resources where the principal
has been delegated write access.
.Pp
The
.Dq If-Match
and
.Dq If
headers are both accepted to check against etags (MD5 sums) and
conditionally replace resources.
.Ss REPORT
The REPORT method is handled similarly to
.Sx PROPFIND .
It accepts the
.Dq Depth
header for recursive reports.
.Sh IMPLEMENTATION NOTES
The
.Nm
system is fairly complicated, though as simple as it can be.
It focusses on safety and security throughout.
In this section, I describe several important topics regarding
implementation.
.Ss Authentication
.Nm
requires HTTP
.Dq QOP
digest authentication.
Nonces are maintained in the calendar database and guarantee that
principals are not subject to replay attacks.
There are a fixed number of nonces (a compile-time constant defaulting
to 1000) to prevent an adversary from growing the database forever;
however, an adversary may trigger a DOS by constantly flooding the
system with requests such that valid nonces are flushed.
Nonces are 16-bytes of random data.
.Pp
When a client first accesses the system (without authentication), it is
given a random, unrecorded nonce.
.Pp
When the client re-authenticates using the random nonce and principal
credentials, the system first checks that the user is valid.
The nonce is then checked in the database.
If it is not found (the case for principals re-authenticating with the
random nonce), authentication is requested again with the
.Dq stale
directive and a new nonce entry in the database.
Replay nonces request a full re-authentication.
This step ensures that the principal is valid, though it could be a
replay attack from a nonce entry since evicted.
.Pp
Finally, the client re-authenticates with the recorded nonce and is able
to access the system.
.Pp
The remaining attack is for an adversary to build up a database of known
historical responses and replay them all at once.
.Ss Date and Time
Well-defined calendar date and time is required for computing ranges of
free-busy, multiget filters, and so on.
.Nm
parses valid RFC 2445 (iCalendar) calendar dates fully, encompassing
arbitrary repeat-rules and so on.
Parsing UTC time-stamps is well-defined using the formula from the
.Dq Single Unix Specification
section 15 on
.Dq Seconds since epoch .
Parsing embedded time-zone time-stamps is far more complicated, but
fully supported as defined by RFC 2445 using both the SUS algorithm and
Zeller's congruence to compute time components.
Other CalDAV implementations make use of
.Xr tzfile 5
databases: since
.Nm
assumes it is in a
.Xr chroot 2
and that this database is unavailable, it parses all time-zone
definitions directly.
.Pp
One of the most complex components of RFC 2445 is the repeat-rule, such
as that used for time-zone daylight and standard sub-component
definitions.
.Nm
enumerates over all possible repeat-rule instances, and is thus able to
accomodate for arbitrarily-complicated repeat rules.
.\" Not used in OpenBSD.
.\" .Sh RETURN VALUES
.\" For sections 2, 3, and 9 function return values only.
.\" .Sh ENVIRONMENT
.\" For sections 1, 6, 7, and 8 only.
.\" .Sh FILES
.\" .Sh EXIT STATUS
.\" For sections 1, 6, and 8 only.
.\" .Sh EXAMPLES
.\" .Sh DIAGNOSTICS
.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
.\" .Sh ERRORS
.\" For sections 2, 3, 4, and 9 errno settings only.
.Sh SEE ALSO
.Xr kcaldav.passwd 1
.Sh STANDARDS
The
.Nm
utility minimally implements RFC 4918 (WebDAV), RFC 4791 (CalDAV), and
of course RFC 2616 (HTTP).
It also implements the following extensions:
.Bl -tag -width Ds
.It caldav-ctag-02
The
.Dq ctag
Calendar Server Extension.
.It caldav-proxy.txt
Read-write delegation support.
.It RFC 2617
.Dq Digest
authentication of all users.
.It RFC 3744
ACL queries on the authenticated principal (not ACEs).
.It RFC 4331
Available and used bytes in the collection file-system via
.Xr fstatfs 2 .
.It RFC 5397
The current principal address.
.It RFC 7232
Conditional HTTP responses (etag,
.Dq If-Match ,
etc.).
.It RFC 5785
The
.Qq well-known
web server interface.
.El
.Pp
Logging uses the
.Lk https://httpd.apache.org/docs/2.4/logs.html "Apache Common Log Format" .
.\" .Sh HISTORY
.\" .Sh AUTHORS
.\" .Sh CAVEATS
.\" .Sh BUGS
.\" .Sh SECURITY CONSIDERATIONS
.\" Not used in OpenBSD.