beenull/abook_carddav_squirrelmail
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
abook_carddav_squirrelmail/README.md
Alexey Shpakovsky aafc2f467a
update readme with some notes
2021-07-09 21:17:11 +02:00

5.6 KiB
Raw Blame History

abook_carddav

SquirrelMail CardDAV Address book backend plugin

Based on 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.