Data structures: vCards

This page is based on reading code from commit 5c0104f dated 2018-06-11 and files generated by it. It is incomplete and there may errors or omissions!

Relation to Mailpile objects

RFC 6350 defines the vCard format for representing information about individuals and other entities. The format is a text file consisting of content lines (which are wrapped if longer than 75 characters), each beginning with a name of a property. Mailpile uses the vCard format to store information about contacts and profiles externally. On startup, all the vCard data is read and stored internally. Each Mailpile vCard has a unique random id property named X-MAILPILE-RID which is a randomly assigned hexadecimal number (length <= 13 digits).

The data stored in vCards comes from these sources:

• Emails sent and received by Mailpile, although not all email addresses listed in the contact index part of the Metadata Index have vCards.
• The setup dialog which creates a Mailpile profile (called an "E-mail Account" on the Welcome page).
• The GnuPG key ring. Most email addresses which are listed in the user ids of the keys will be imported to both the Metadata Index and the vCard store.

The vCards associated with Mailpile profiles, unlike the others, have a KIND property with value "profile". A profile defined in a vCard is linked to a mail source (incoming) and a mail route (outgoing) defined in ConfigManager and stored in mailpile.cfg. Also, the mail source defined in ConfigManager is linked back to its profile's vCard. For example (showing both types of attributes as stored in the .vcf and the mailpile.cfg files):

X-MAILPILE-PROFILE-ROUTE:1 is a link to config/routes/1.
X-MAILPILE-PROFILE-SOURCE:776592edd51 is a link to config/sources/776592edd51.
which has an attribute profile=ed1592eddb12 linking back to the vCard with X-MAILPILE-RID: ed1592eddb12.

External format

The vCards are stored in a subdirectory vcards. Each vCard is stored in a text file, one vCard per file. The file may be encrypted. The file format is generally as prescribed by RFC 6350. Each file name consists of the vCard X-MAILPILE-RID value with extension .vcf; e.g. the file that contains the line X-MAILPILE-RID:a4dbd8fbd59e2 is named a4dbd8fbd59e2.vcf.

A typical vCard (not a profile, not associated with a PGP key) contains the following properties.

CLIENTPIDMAP
EMAIL
FN
KIND;PID=990.1:internal
NOTE
PHOTO
X-GRAVATAR-TS
X-LIBRAVATAR-TS
X-MAILPILE-HISTORY
X-MAILPILE-HTML-POLICY
X-MAILPILE-LAST-PGP-KEY-SHARE
X-MAILPILE-PREFER-PROFILE
X-MAILPILE-RID

A typical vCard for a local mail profile typically has these properties in addition to the above.

X-MAILPILE-CRYPTO-FORMAT
X-MAILPILE-CRYPTO-POLICY
X-MAILPILE-PROFILE-SIGNATURE
X-MAILPILE-PROFILE-TAG

A vCard for a remote server profile typically has these properties in addition to all the above.

X-MAILPILE-PROFILE-ROUTE
X-MAILPILE-PROFILE-SIGNATURE
X-MAILPILE-PROFILE-SOURCE

A vCard for a contact with a PGP key, which falls into any of the categories listed above, typically contains the following additional properties.

KEY
X-GPG-MRGID

Internal format

All the vCards are stored internally in a object of class mailpile.vcard.VCardStore which is a dictionary. The dictionary has two keys for each vCard, the random id (vCard property X-MAILPILE-RID), and the email address (vCard property EMAIL). If the vCard for a contact contains more than one email address (e.g. a vCard derived from the GnuPG key with multiple user ids), then the dictionary contains keys for all the email addresses. The values for all these keys point to the same mailpile.vcard.MailpileVCard object.

The mailpile.vcard.MailpileVCard class supports the following attributes random_uid

Attributes provided by contacts:
pgp_key
pgp_key_shared
html_policy
crypto_policy
crypto_format

Attributes provided by profiles:
signature
route
tag

Attributes:
history_vcl added by mailpile.vcard.MailpileVCard.record_history()
html_policy

X-MAILPILE-CRYPTO-FORMAT

Stores selections in Edit Profile-Security and Privacy-Show too many encryption settings.

Nothing checked: [blank]
Minimize metadata (clears prefer_inline): +obscure_meta
Prefer compatibility (clears other two); avoid PGP/MIME ... :+prefer_inline
Prefer PGP/MIME (clears prefer_inline): +pgpmime
Automatically attach encryption keys to outgoing mail: +send_keys
Signal a preference for signed mail: openpgp_header:S
Signal a preference for encrypted mail (sets above): openpgp_header:SE
Signal a preference for un-signed, un-encrypted mail (clears above two): openpgp_header:N

X-MAILPILE-CRYPTO-POLICY

Stores selections in Edit Profile-Security and Privacy-Show too many encryption settings.

Nothing checked: none
Best-effort ... (clears next two): best-effort
Always digitally sign outgoing mail (clears best-effort): openpgp-sign
Always encrypt ... (clears best-effort): openpgp-encrypt
(both of the above two) : openpgp-sign-encrypt

KEY

Example: PREF;PID=990.8:data:application/x-pgp-fingerprint\,9B9B2CD86DE4C91854452B2E05DF29FE0DECDDF5

X-MAILPILE-HISTORY

Lists signed or encrypted messages recently sent TO the contact(?) with base36 encoded time and base36 encoded Message Index ID.

Example: PID=990.1:s-PAAKXW-16L6\,s-PABQB9-16LK

X-MAILPILE-LAST-PGP-KEY-SHARE

The last time the profile's PGP key was sent to the contact as an integer in s since 1970-01-01 00:00:00 UTC.

Example: PREF;PID=990.3:1516978103