XEP-xxxx: Trust Messages

This document specifies a way to communicate the trust in public long-term keys used by end-to-end encryption protocols from one endpoint to another.
Melvin Keskin
© 1999 – 2021 XMPP Standards Foundation. SEE LEGAL NOTICES.


WARNING: This document has not yet been accepted for consideration or approved in any official manner by the XMPP Standards Foundation, and this document is not yet an XMPP Extension Protocol (XEP). If this document is accepted as a XEP by the XMPP Council, it will be published at <https://xmpp.org/extensions/> and announced on the <standards@xmpp.org> mailing list.
Standards Track
0.0.1 (2020-02-15)
Document Lifecycle
  1. Experimental
  2. Proposed
  3. Stable
  4. Final

1. Introduction

End-to-end encryption without verifying the authenticity of the exchanged public long-term keys only enables the endpoints to protect their communication against passive attacks. This means an attacker cannot read encrypted messages in transit without actively intervening in the key exchange. However, without any other precautions active attacks are still possible. If an attacker replaces the exchanged keys with malicious ones or introduces a new malicious endpoint with an own key, the end-to-end encrypted messages can be read and manipulated by the attacker.

When using end-to-end encryption where public long-term keys are transmitted over a channel which is not protected against active attacks, the authenticity of those keys is not guaranteed. Such a key has to be authenticated by the receiving endpoint over a channel which is protected against active attacks to maintain the confidentiality of sent messages and ensure the authenticity and integrity of received messages.

A trust message is an XMPP message that contains the information of whether the sending endpoint trusts a specific public long-term key. The authenticity and integrity of the message is ensured by a signing mechanism. Trust messages can be used in conjunction with an end-to-end encryption protocol like OpenPGP for XMPP (XEP-0373) [1] or OMEMO Encryption (XEP-0384) [2] e.g. to automatically or semi-automatically establish secure channels protected against active attacks.

Furthermore, the fact that an endpoint trusts a key or not can be kept confidential toward an attacker by encrypting those messages and sending them only to endpoints with authenticated keys. That means particularly that an attacker cannot detect by the content of a trust message whether an authentication of a key took place. An authentication will therefore stay anonymous toward an attacker. The encryption protects against passive attacks since an attacker cannot read the content of the trust message. The restriction to send trust messages only to endpoints with authenticated keys in addition to the encryption protects against active attacks since the attacker will not, after introducing a malicious key, receive a trust message encrypted with that key.

2. Glossary

Communication endpoint owning exactly one public long-term key. In most cases that is an XMPP client instance. In the terminology of OMEMO Encryption (XEP-0384) [2], that is a "device". To cover also the possibility for using multiple endpoints on the same physical device and via the same client instance, the general term "endpoint" is used.
Key authentication
Verification that a key received over an insecure channel is actually the one of the assumed endpoint
Key identifier
Identifier of a key (e.g., a fingerprint or the key itself)
Trust message
XMPP message which indicates that specific keys are trusted or not trusted by the sender. A trust message for an endpoint's key contains the key identifier of the given key.

3. Trust Message Structure

A trust message MUST be signed in a way to ensure its authenticity and integrity.

The part specific for a trust message begins with the <trust-message> element. Its encryption attribute MUST specify the encryption protocol that uses the keys denoted by their identifiers. To send a trust message for keys of OpenPGP for XMPP (XEP-0373) [1] the attribute encryption='urn:xmpp:openpgp:0' or for keys of OMEMO Encryption (XEP-0384) [2] the attribute encryption='eu.siacs.conversations.axolotl' MUST be used. For other values there is an overview of possible encryption protocols [3]. A trust message MUST contain at least one <key-owner> element and each element MUST contain at least one <trust> or <distrust> element. Inside of each <trust> or <distrust> element there MUST be exactly one key identifier. Those elements are used for the following purposes:

In the following example the keys of the later given identifiers are used by the encryption protocol OMEMO Encryption (XEP-0384) [2] specified by eu.siacs.conversations.axolotl.

Example 1. Specifying the Encryption Protocol of the Keys
<trust-message xmlns='urn:xmpp:trust-messages:0' encryption='eu.siacs.conversations.axolotl'>

In the following example the keys of the later given identifiers belong to alice@example.org.

Example 2. Specifying the JID Owning the Keys
<key-owner jid='alice@example.org'>

In the following example the key corresponding to the identifier inside <trust> and </trust> is trusted by the sending endpoint.

Example 3. Indicating the Trust in a Specific Key

In the following example the key corresponding to the identifier inside the <distrust> and </distrust> is not trusted by the sending endpoint.

Example 4. Indicating the Distrust in a Specific Key

4. Use Cases

An endpoint of alice@example.org MAY send a trust message to other endpoints of alice@example.org, to contacts like bob@example.com or to a specific resource like carol@example.net/phone.

The usage of Message Carbons (XEP-0280) [4] for trust messages is RECOMMENDED. It minimizes the number of trust messages to be sent while having the same payload because trust messages with the same payload do not have to be sent for each endpoint. In combination with the usage of Message Archive Management (XEP-0313) [5], the delivery of trust messages to temporarily offline endpoints is ensured even if they are available under a different resource after going online than the last known one before going offline. Additionally, using Message Carbons (XEP-0280) [4] for every encrypted trust message will lead to send trust messages which are less distinguishable by analyzing their content from other encrypted messages using Stanza Content Encryption (XEP-0420) [6]. However, it may be possible to distinguish an encrypted trust message from other encrypted messages and therefore detect the fact that a specific authentication took place by analyzing the network traffic over a period of time but that is out of scope for this specification.

TODO: Move this paragraph to Stanza Content Encryption (XEP-0420) [6]. The following message attribute and element are RECOMMENDED because without having <body>, the goals of them would not be achieved. type='chat' is needed to deliver the trust message to all endpoints (see XEP-0280: Message Carbons). <store xmlns='urn:xmpp:hints'/> is needed to deliver the trust message to each offline endpoint after it went online (see XEP-0313: Message Archive Management and XEP-0334: Message Processing Hints).

In the following examples Alice's endpoint sends a trust message for OMEMO Encryption (XEP-0384) [2] (eu.siacs.conversations.axolotl) keys of own endpoints and Bob's endpoints to Carol's resource "phone". Alice's keys corresponding to the identifiers starting with "68" and "22" are trusted by Alice's endpoint connected via resource "laptop". Bob's key corresponding to the identifiers starting with "68" and "22" are trusted by Alice's endpoint connected via resource "laptop". Bob's key corresponding to the identifier starting with "62" is trusted by Alice's endpoint connected via resource "laptop" but not Bob's keys corresponding to the identifiers starting with "b4" and "d9".

4.1 Unencrypted Trust Message

A trust message before encryption or without any encryption could look like the following example. Keep in mind, like said before, that the authenticity and integrity of the message MUST be ensured by a signing mechanism even if the message is not encrypted. However, the strength of trust messages is the possibility to encrypt them and to choose its recipients.

Example 5. Alice's endpoint sends an unencrypted trust message to Carol
<message from='alice@example.org/laptop' to='carol@example.org' type='chat'>
  <store xmlns='urn:xmpp:hints'/>
  <trust-message xmlns='urn:xmpp:trust-messages:0' encryption='eu.siacs.conversations.axolotl'>
    <key-owner jid='alice@example.org'>
    <key-owner jid='bob@example.com'>

4.2 Encrypted Trust Message

Like described in the introduction, it is possible to encrypt a trust message and send it only to endpoints whose keys have already been authenticated. Both actions are RECOMMENDED, especially for concealing the fact that an endpoint authenticated another endpoint's key. When using an end-to-end encryption like OMEMO Encryption (XEP-0384) [2] which cannot encrypt arbitrary elements, Stanza Content Encryption (XEP-0420) [6] is needed to encrypt a trust message. The following example shows how such a message could look like. For encrypting with OpenPGP for XMPP (XEP-0373) [1], the element <encrypted xmlns='eu.siacs.conversations.axolotl'> MUST be replaced by <openpgp xmlns='urn:xmpp:openpgp:0'>, the element <envelope xmlns='urn:xmpp:sce:0'> by <signcrypt xmlns='urn:xmpp:openpgp:0'> and <header sid='27183'>...</header> MUST be removed.

Example 6. Alice's endpoint sends an encrypted trust message to Carol
<message from='alice@example.org/laptop' to='carol@example.org' type='chat'>
  <store xmlns='urn:xmpp:hints'/>
  <encrypted xmlns='eu.siacs.conversations.axolotl'>
    <header sid='17183'>
    <envelope xmlns='urn:xmpp:sce:0'>
      <time stamp='2020-01-01T00:00:00'/>
      <from jid='alice@example.org/laptop'/>
      <to jid='carol@example.org'/>
        <trust-message xmlns='urn:xmpp:trust-messages:0' encryption='eu.siacs.conversations.axolotl'>
          <key-owner jid='alice@example.org'>
          <key-owner jid='bob@example.com'>

5. Implementation Notes

This specification uses Message Carbons (XEP-0280) [4] for sending a trust message to all endpoints of a contact or to all own endpoints at once. By sending a trust message to the contact, each endpoint of the contact and each own endpoint receives the same trust message by the server. Thus, a client needs to send the same trust message only once.

If not all endpoints of the contact should receive the trust message, the trust message MAY be sent to specific endpoints of the contact but for all own endpoints Message Carbons (XEP-0280) [4] MAY be used and vice versa. Even when a client does not yet have a contact, the client MAY use Message Carbons (XEP-0280) [4] for delivering a trust message to all own endpoints by sending it to the own bare JID. If then a client receives a trust message with its own full JID as the sender, it MAY discard that message directly without parsing the content.

Example: Alice's endpoint A1 authenticates the key of her endpoint A2. A1 sends the trust message for A2's key only once to all of Alice's and Bob's endpoints by using Message Carbons (XEP-0280) [4].

Attention: In that context, sending an encrypted trust message to all endpoints of a contact or to all own endpoints does not mean to encrypt it with the keys of all those endpoints. Instead, it only means that all of those endpoints should receive the trust message even if it is not encrypted for some of them and thereby not decryptable by those endpoints. Keep in mind that a trust message SHOULD only be encrypted for endpoints with authenticated keys.

6. IANA Considerations


7. XMPP Registrar Considerations


8. XML Schema

REQUIRED for protocol specifications.


Appendix A: Document Information

XMPP Standards Foundation
Standards Track
Last Updated
Approving Body
XMPP Council
XMPP Core, XEP-0001, XEP-0280, XEP-0334, XEP-0420
Superseded By
Short Name

This document in other formats: XML  PDF

Appendix B: Author Information

Melvin Keskin


This XMPP Extension Protocol is copyright © 1999 – 2020 by the XMPP Standards Foundation (XSF).


Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).

Visual Presentation

The HTML representation (you are looking at) is maintained by the XSF. It is based on the YAML CSS Framework, which is licensed under the terms of the CC-BY-SA 2.0 license.

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <https://xmpp.org/community/> for a complete list.

Errata can be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

Appendix G: Notes

1. XEP-0373: OpenPGP for XMPP <https://xmpp.org/extensions/xep-0373.html>.

2. XEP-0384: OMEMO Encryption <https://xmpp.org/extensions/xep-0384.html>.

3. Explicit Message Encryption - Encryption Protocols <https://xmpp.org/extensions/xep-0380.html#table-1>.

4. XEP-0280: Message Carbons <https://xmpp.org/extensions/xep-0280.html>.

5. XEP-0313: Message Archive Management <https://xmpp.org/extensions/xep-0313.html>.

6. XEP-0420: Stanza Content Encryption <https://xmpp.org/extensions/xep-0420.html>.

Appendix H: Revision History

Note: Older versions of this specification might be available at https://xmpp.org/extensions/attic/

  1. Version 0.0.1 (2020-02-15)

    First draft.


Appendix I: Bib(La)TeX Entry

  title = {Trust Messages},
  author = {Keskin, Melvin},
  type = {XEP},
  number = {xxxx},
  version = {0.0.1},
  institution = {XMPP Standards Foundation},
  url = {https://xmpp.org/extensions/xep-xxxx.html},
  date = {2020-02-15/2020-02-15},