# abook_carddav SquirrelMail CardDAV Address book backend plugin Based on [carddavclient][]. [carddavclient]: https://github.com/mstilkerich/carddavclient/ ## Requirements Basically, same as [carddavclient][]: * PHP 7.1 or 7.4 (tested with 7.4.17) with the following extensions: json, iconv, openssl (only to connect to https backends), mbstring, xmlreader, xmlwriter. On most distros they're likely to be installed by default, on Alpine you need to install relevant `php7-*` packages. * SquirrelMail 1.4.22 (tested with 1.4.23 SVN), most likely **NOT** compatible with SquirrelMail 1.5. ## Installation * (optional) build carddavclient (`vendor` directory). There's a `build.sh` script which uses `Dockerfile.build` in `build` directory. * Copy everything to a `abook_carddav` subdirectory in `plugins` directory of your SquirrelMail installation. * Open `{your.squirrelmail.installation}/plugins/abook_carddav/discover.php` - it should show you "Loading... ...ok! Config... ...ok!" on top. If not - check your web server's error log. * Enable the plugin as usual (via `conf.pl`). ## Configuration Each user configures the plugin for themselves separately. * Open `{your.squirrelmail.installation}/plugins/abook_carddav/discover.php`, provide hostname, URL, or whatever you know about your CardDAV server, together with your username and password. For example, in case of Baikal server running on `https://baikal.example.com:8000/`, discovery URL is `https://baikal.example.com:8000/dav.php`. Valid username and password are required to find addressbooks available to a specific user. Press "Submit" button. * After a second or few you will get to a page with a hopefully huge log - scroll to the very bottom and look for line "Addressbooks discovered". * If you see a number greater than 0 - success! - copy any pair of "Addressbook URI" and "Base URL" values, and paste them in the SquirrelMail options, "Display Preferences" page, "CardDAV Address Book" section - together with your username and password. ## Usage * If listing is allowed in settings, "Addresses" shows all contacts in your CardDAV address book, who have an email address. * Otherwise, you can always yse addressbook search. * "Address Autocompletion" plugin has an option to pre-load Contacts. Note that this option is not compatible with addressbook plugins which have listing disabled. Note on Vcard fields -------------------- In addition to "email", Vcard format supports quite a lot of fields (name, org, title, notes, address, phone, etc), while SquirrelMail - much less (name, nickname, info). Moreover, SquirrelMail uses "nickname" field as unique key to identify address book entries when editing/deleting them. I.e. when user clicks a button to delete an entry, SquirrelMail tells addressbook backend: "please delete user with this nickname". For CardDAV servers, such unique keys are otherwise meaningless URIs. Also SquirrelMail supports only one email address per contact, while vcard can have multiple. So I came up with this otherwise strange idea: add an option (checkbox) whether addressbook is writeable, and make field contents depend on it: * when addressbook is in read-only mode, "nickname" field in SquirrelMail shows content of "organisation" field in vcard. * when addressbook is write-enabled, "nickname" field contains vcard URI, and "info" field contains value of "organisation" field from vcard (which you actually can edit). Moreover, when addressbook is in read-only mode, each vcard is repeated as many times as there are email addresses in it, and also "info" field has different phone numbers (but you can't edit them). Sounds messy, but works nice in my case :) Note about password storage --------------------------- This plugin has three options regarding password storage: * use same password for CardDav account as for IMAP (usually it's the password you enter to login to SquirrelMail) - obviously it's the best option from the password storage point of view, but only if your CardDav and IMAP accounts have the same password (note that usernames might differ). * _encrypt_ your CardDav password using your IMAP password - probably the best option in all other cases, but remember that you will have to re-enter your CardDav password (for it to be re-encrypted) in case your IMAP password changes. _Encryption_ used here is basically XORing CardDav password with sha256 checksum of IMAP password and storing the result. * No encryption, CardDav password is stored in your prefs file in plain text. Obviously, in last case if someone gets hold of your prefs file (malicious server admin, php script, or via backups) - they can read your CardDav password from it. In second case, in addition to copy of your prefs file, they need to know your IMAP password - and then they can find out your CardDav password. If anyone has a better (more secure) idea of password storage - please let me know! Also, when user switches from first option ("use IMAP password") to last one ("store password in plaintext") - their IMAP password appears in prefs file in plain text. Fixing this is first item on my list. Some more notes --------------- * Currently, CardDav server/account is configured by each user individually, although it should be pretty easy to add an option of admin-specified "global" or per-user CardDav server/account. * Also, it should be pretty simple to implement multiple CardDav address books (just call add_account function multiple times with different arguments), but I don't have good idea how to implement it UI-wise. * It should be easy to adapt this plugin to other SquirrelMail versions, if someone finds a compatibility issue.