VES MIME Format Specifications

Jim Zubov <jz&vesvault.com> VESvault Corp.

Overview

VES MIME (ves-mime) is an encrypted email message format, and is an extension of MIME (RFC 5322).

A ves-mime message is produced from an email message, referred to as the Original Message, by encrypting and properly encoding the MIME parts and headers so that the content can be read by authorized recipients only, while maintaining the MIME hierarchy and the order of headers close to the original.

The intent behind ves-mime is to enable specific parties that have access to the encryption key to reconstruct the Original Message from the VES MIME message with maximum possible fidelity, to enable transformation to/from ves-mime with minimum buffering in a stream mode; and to enable MIME-aware agents, such as IMAP clients, to selectively reconstruct a specific part of the Original Message by accessing the corresponding part of the ves-mime message and the main message headers.

The ves-mime format has been designed in conjunction with VESmail, an open source email encryption proxy that can be build as a consumer app or as a server CLI process. VESmail relies on open source libVES for cryptographic operations. libVES uses end-to-end encrypted online VES Repository to store encrypted items and share them with specific parties, while safeguarged from key loss with end-to-end VES Recovery option.

VES MIME Format Specifications

An email message is identified as ves-mime by having VESmail-ID: in the message headers.

A ves-mime message MUST have exactly one VESmail-ID: message header, located in any position in respect to other headers, and SHOULD NOT have VESmail-ID: in any other MIME parts of the message, including any nested messages.

A ves-mime message MAY have one or more VESmail-Header: in the message header and/or in any MIME part of the message, including nested messages and their MIME parts, mixed arbitrarily with other headers.

Any part of a ves-mime message, or the main headers, MAY have at least one VESmail-Part: header.

Any part with VESmail-Part: banner MUST be either the last part in a multipart container, or followed by another part with VESmail-Part: banner.

A ves-mime message MAY have at most one part with VESmail-Part: injected. Such part, if exists, MUST be of MIME type multipart/alternative, the boundary parameter MUST start with magic --VESmail-injected-, the first directly nested part MUST NOT be VESmail-Part: banner, all following directly nested parts MUST be VESmail-Part: banner.

A part with VESmail-Part: alternative MUST be of MIME type multipart/alternative.

A ves-mime message MAY have one VESmail-Verify: message header, and/or one VESmail-Xchg: message header, located in any position in respect to other headers. Either of those headers SHOULD NOT occur in any other MIME parts of the message, including any nested messages.

A ves-mime message SHOULD contain at least one part of type application/vnd.ves.encrypted, any such parts SHOULD use base64 transfer encoding.

VES MIME Message relative to the Original Message

If the Original Message does not have Message-ID:, or has a malformed one, a new Message-ID: with a unique value MUST be generated and appended to the message headers before transforming to ves-mime.

The VESmail-ID: of the ves-mime message MUST have the same value as the Message-ID: of the Original Message.

The Message-ID: value of the ves-mime message SHOULD be derived from the Message-ID: of the Original Message by appending a magic .m.ves.world to the value inside the < angular quotes >.

The following headers SHOULD NOT be encrypted in ves-mime and retain the value from the Original Message, as they may affect proper mail delivery: From:, To:, Cc:, Date:, MIME-Version:, Reply-To:, Return-Path:, Envelope-To:, Importance:, Priority:, Auto-Submitted:.

Each referenced id value in References: and In-Reply-To: from the Original Message, if any, SHOULD be passed unencrypted and SHOULD be appended with the magic .m.ves.world in ves-mime for proper thread tracking.

The ves-mime message headers, and the MIME headers of each part, whether they are taken from the Original Message without changes or are encrypted into VESmail-Header:, SHOULD follow in the same order as the corresponding headers of the Original Message. Additional headers specific to ves-mime, that have no correspondence to any headers in the Original Message, MAY be inserted at any position.

If the Subject: header of the Original Message is encrypted into VESmail-Header:, a dummy Subject: header MAY be inserted after the encrypted one.

If the Content-Disposition: header in any MIME part of the Original Message is encrypted into VESmail-Header:, a plain Content-Disposition: header MUST be inserted after the encrypted field with the copy of the main value (inline|attachment), but without any attributes such as filename.

If the Original Message has some incompliances with MIME or related standards, such as malformed headers or imporperly separated multipart containers, the ves-mime message will likely bear similar incompliances, and the message recovered from ves-mime might not be fully identical to the Original Message.

MIME parts of the Original Message in base64 and quoted-printable encoding are decoded into binary before encrypting into application/vnd.ves.encrypted, therefore any padding or illegal characters in the original encoded part will not be preserved when recovering the message from ves-mime. Any other encodings are treated as binary and will be passed verbatim when recovering from ves-mime, at the expense of the message size.

If the original Message contains a single body part without a multipart/alternative container, the body part MAY be wrapped in an injected multipart/alternative with VESmail-Part: injected, in order to fit VESmail Banners as alternative body parts. If the Original Message already has multipart/alternative, the Banners MAY be injected in it after the last part.

The ves-mime multipart boundary values (except for an injected container), and the lead-in and lead-out sections of each multipart container (before the first boundary and after the final boundary) SHOULD be identical to the corresponding parts of the Original Message.

Although the standards explicitly specify <CR><LF> as a line break character, in practice Unix platforms often use a single <LF>. A ves-mime message MUST replicate the use of linebreaks of the Original Message, as long as it is consistent throughout a single headers section or a single body section. Inconsistent linebreaks in a section of the Original Message MAY be reflected similarly in the ves-mime.

For compatibility reasons, any X-VESmail-*: header in a ves-mime message or in any MIME part of it, should be interpreted as a corresponding VESmail-*: specified in this document.

VES MIME Message Cipher

The cipher key and algorithm parameters for a VES MIME message are stored under VES Vault Item ves://vesmail/{vesmail_id} (see VES URI Scheme). Here, {vesmail_id} is the unquoted ID value from VESmail-ID: header.

Every application/vnd.ves.encrypted part of the message, and every VESmail-Header: header, MUST use the same Message Cipher.

Since the Message Cipher key is reused for encrypting differrent pieces of the content, the cipher algorithm SHOULD involve a random seed for each encrypted block to minimize side channel leaks. The recommended Message Cipher algorithm is AES256GCM1K, although any symmetric ciphers supported by libVES can be used.

Using libVES, the Message Cipher item is encrypted for the Sender, and for each of the intended Recipients, and the encrypted entries are deposited in VES Repository.

VESmail Banner

VESmail Banner is an unencrypted MIME part of a ves-mime message that does not correspond to any part of the Original Message. A Banner is placed in a multipart/alternative container, and is recognized as a message body.

A Banner is a human-readable placeholder that notifies a user that the message is encrypted, and instructs about the options of decrypting the content.

If the copy of the ves-mime message was saved in a VESmail Viewer spool – the Banner SHOULD provide an Instant Viewer link where the Recipient, after being asked to authorize with VES or guided through VES setup, can view the contents of the message decrypted by the end-to-end browser based Instant Viewer.

A ves-mime message MAY include more than one Banner as alternative bodies, normally text/plain and text/html.

VES MIME Headers

VESmail-ID: <msg-1234-5678@acme.com>

Scope: mail

The presence of this header identifies the message as ves-mime. This header contains a globally unique value in the same format as Message-ID:, and SHOULD comply to RFC 5322 section 3.6.4. The value MUST be the same as the Message-ID: of the Original Message.

VESmail-Header: GRkpxikFoYq/o3yWaHx6ftXpbSO4YsCK5LeGmyWZRMO7drTK3UCgAHCJNG8J
        q77jgSxfcXPoxGedylrh0k5S9MoIUQXLFg==

Scope: mail, mime

The value contains an encrypted header. A main message header, or a MIME part header, from the Original Message, signle line or multiline, is stripped of the terminal newline, but all multiline newlines and spacings are left intact, then encrypted with the Message Cipher, then Base64 encoded, arbitrary spaces and multiline breaks MAY be inserted.

VESmail-Part: injected

Scope: mime

The header may have one of the following values:

banner: MUST be supplied for a VESmail Banner MIME part.
injected: MUST be supplied for an injected multipart/alternative container.
body: MAY be supplied for an encrypted body part of the Original Message.
alternative: MAY be supplied for a multipart/alternative container that has VESmail Banners added to it.

VESmail-Verify: ~SXyKpUYJuOkpf8a25wNefplX

Scope: mail

This header MAY be persent in a ves-mime message, it allows anybody to verify the authenticity of the sender of the message through VES repository, without having access to the encrypted message content. The value of the header is an ASCII Session Token that can be used with libVES, or other VES API tool, to retrieve the ownership information about the Message Cipher Vault Item.

VESmail-Xchg: [[760,110,"#5=5tOhPtFav+e2g4h<g,CywT|0y#ra0"],
        [958,111,"Iy}_wmRVfDEVmrZH+q-WDF\/#wVgLpllz"]]

Scope: mail

This header MAY be present in a ves-mime message. It contains VES exchange information, that can be used by a recipient who have not yet set up their VES account to expedite the key propagation and have instant access to the Message Cipher upon completing their VES setup, without potential delay during an end-to-end VES key propagation process.

The value is a JSON array, may contain multiline newlines and spaces as long as they are consistent with JSON. Each member of the array is a 3-member array consisting of an integer userId, an integer vaultKeyId, and a string tempKey, that can be used with libVES to expedite the key propagation.

The presense of the exchange information adds some minor security risk, see Security Considerations.

Security Considerations

Any headers and/or MIME parts of the Original Message that contain any sensitive information SHOULD be encrypted in the corresponding ves-mime message. Message headers that affect routing and delivery are recommended not to be encrypted in ves-mime, and are not expected to contain sensitive information.

Security considerations for application/vnd.ves.encrypted MIME type are provided in the IANA Registry, same considerations apply to VESmail-Header:.

A malformed MIME message, such as broken multipart boundaries, when any sensitive information comes in a multipart container before the first boundary or after the final boundary, or when sensitive data is misplaced in certain message headers, MAY leak sensitive content when converted to ves-mime. The composing party MUST comply with MIME specifications and industry best practices to avoid potential leaks.

The presense of the exchange information in VESmail-Xchg: adds some security risk as opposed to end-to-end VES key exchange. The tempKey is a passphrase that decrypts an encrypted private Temp Vault Key stored in VES Repository, which in turn decrypts the Message Cipher for the message, and also Message Ciphers for other messages that have been sent by the same Sender to the same Recipient. The encrypted private Temp Vault Key is not publicly accessible, VES API requires to complete VES setup, which involves email verification. Additionally, the Temp Vault Key is permanently deactivated once the Recipient has completed VES setup, and no further Message Ciphers are shared with the Temp Vault Key. However, it is possible to envision a situation when an Intruder has some kind of side access to VES Repository, and having a ves-mime email with exchange tokens allows the Intruder to decrypt the message, and potentially certain other messages from the same Sender to the Recipient. Moreover, if a ves-mime email is addressed to multiple Recipients with incomplete VES setup and includes exchange tokens, each of the Recipients is exposed to this potential security risk.

The ultimately secure solution is to require all Recipients to have their VES setup completed before being able to receive ves-mime messages.

The second best option is to not send the exchange tokens in the email, then the Recipient will have to rely on end-to-end VES Temp Key Exchange. In this case the Intruder would have to commit an identity theft on the Recipient and set up an imposter VES account by stealing control over the Recipient's email to gain access to the encrypted information.