KCALDAV(8) System Manager's Manual KCALDAV(8)

kcaldavsimple CalDAV server

kcaldav

kcaldav is a CGI program that minimally implements CalDAV. It interfaces with a calendar database /caldav/kcaldav.db (in the web server's file-system root) administered by kcaldav.passwd(1).

For example, assume the CGI program available at:

https://localhost/cgi-bin/kcaldav

The calendar root /caldav resolves to /var/www/caldav on the host file-system. It contains kcaldav.db created by kcaldav.passwd(1) specifying a single principal kristaps with a single calendar collection calendar as created with

# kcaldav.passwd -Cu kristaps

Most CalDAV clients will ask for the CGI program name, principal name, and password. The program name in this example is as follows:

https://localhost/cgi-bin/kcaldav

This is further simplified if the web server is configured to handle a "well-known" service that redirects to the CGI program name, leaving the only configuration to be the web server root:

https://localhost

For some older clients, the CGI program name will need to include the principal's name as well as the program name:

https://localhost/cgi-bin/kcaldav/kristaps/

Lastly, there are some clients (possibly only Mozilla Lightning) that must connect directly to an individual calendar, such as with:

https://localhost/cgi-bin/kcaldav/kristaps/calendar/

Many modern calendar clients use "well-known" URI identifiers to query a host for its CalDAV. To enable the "well-known" service for kcaldav, the web server's absolute path

https://localhost/.well-known/caldav

must return a 301 redirect to the absolute URL

https://localhost/cgi-bin/kcaldav

assuming the CalDAV host such as in the example.

Let the calendar directory be /caldav, resolving to /var/www/caldav in the host file-system, which is read-writable by the web server. Let the dummy user "kcaldav" be the owner of the database files.

First, kcaldav.passwd(1) must be set-user-ID for modifying the file.

# chown kcaldav /usr/local/bin/kcaldav.passwd
# chmod u+s /usr/local/bin/kcaldav.passwd

Create user principals as follows:

# doas -u kcaldav kcaldav.passwd -Cu user1
# kcaldav.passwd -Cu user2
# ...

Now any local user can modify her principal's password without administrator intervention.

user1% kcaldav.passwd -f /var/www/caldav

Let the calendar directory be /caldav, resolving to /var/www/caldav in the host file-system, which is read-writable by the web server. The database may then be manipulated solely by root:

# kcaldav.passwd -f /var/www/caldav -Cu user1
# kcaldav.passwd -f /var/www/caldav -Cu user2
# ...

Local users may not modify the database.

kcaldav 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 kcaldav as a JSON backend.

Assuming these page have been installed into /var/www/htdocs/kcaldav, principals can then access the server root,

https://localhost/kcaldav/home.html

to see their configuration.

The principal "foo" can modify collection information online. 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.

This section describes each supported HTTP method.

The DELETE method is handled according to RFC 4918. Principals must have DELETE access. Resource deletions process the “If-Match” header, if applied, for conditional deletion.

Collection deletions begin by removing the kcaldav.conf file, which renders the directory opaque to kcaldav. Following that, all files are removed followed by the directory itself. Note: it is possible to remove the principal's home URL!

The GET method is supported for calendar resources (defined by content-type) as defined by RFC 4918. The “If-None-Match” header is processed and checks the file etag (MD5 sum). In all cases, the principal must have been delegated read access.

For the JSON content-type (i.e., web application resources), kcaldav routes into a management framework. Only the index.html resource in the server root directory is supported. Requests for the empty root (“\”) are aliased to index.html.

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.

The PROPFIND method queries collection or resource properties. The principal must have been delegated read access. It accepts the “Depth” header for recursive reports. The following is a table of get-able properties.

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

If the web server has write access to collection kcaldav.conf files and the principal has been delegated write access, its properties may be modified. The following is a table of settable properties.

calendar-colour Apple extension
calendar-description RFC 4791, 5.2.1
displayname RFC 4918, 15.2

The PUT method is supported for calendar resources where the principal has been delegated write access.

The “If-Match” and “If” headers are both accepted to check against etags (MD5 sums) and conditionally replace resources.

The REPORT method is handled similarly to PROPFIND. It accepts the “Depth” header for recursive reports.

The kcaldav 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.

kcaldav requires HTTP “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.

When a client first accesses the system (without authentication), it is given a random, unrecorded nonce.

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 “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.

Finally, the client re-authenticates with the recorded nonce and is able to access the system.

The remaining attack is for an adversary to build up a database of known historical responses and replay them all at once.

Well-defined calendar date and time is required for computing ranges of free-busy, multiget filters, and so on. kcaldav 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 “Single Unix Specification” section 15 on “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 tzfile(5) databases: since kcaldav assumes it is in a chroot(2) and that this database is unavailable, it parses all time-zone definitions directly.

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. kcaldav enumerates over all possible repeat-rule instances, and is thus able to accomodate for arbitrarily-complicated repeat rules.

kcaldav.passwd(1)

The kcaldav utility minimally implements RFC 4918 (WebDAV), RFC 4791 (CalDAV), and of course RFC 2616 (HTTP). It also implements the following extensions:

caldav-ctag-02
The “ctag” Calendar Server Extension.
caldav-proxy.txt
Read-write delegation support.
RFC 2617
“Digest” authentication of all users.
RFC 3744
ACL queries on the authenticated principal (not ACEs).
RFC 4331
Available and used bytes in the collection file-system via fstatfs(2).
RFC 5397
The current principal address.
RFC 7232
Conditional HTTP responses (etag, “If-Match”, etc.).
RFC 5785
The "well-known" web server interface.
October 9, 2020 OpenBSD 6.7