1
0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-30 13:12:15 -05:00
xeps/xep-0434.xml

507 lines
25 KiB
XML
Raw Normal View History

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
<!ENTITY ns "urn:xmpp:tm:1">
<!ENTITY ns-atm "urn:xmpp:atm:1">
<!ENTITY ns-omemo "urn:xmpp:omemo:2">
<!ENTITY ns-sce "urn:xmpp:sce:1">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Trust Messages (TM)</title>
<abstract>
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.
</abstract>
&LEGALNOTICE;
<number>0434</number>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0001</spec>
<spec>XEP-0280</spec>
<spec>XEP-0334</spec>
<spec>XEP-0420</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>TM</shortname>
<author>
<firstname>Melvin</firstname>
<surname>Keskin</surname>
<email>melvo@olomono.de</email>
<jid>melvo@olomono.de</jid>
</author>
<revision>
<version>0.6.0</version>
<date>2021-10-04</date>
<initials>melvo</initials>
<remark>
<p>Specify key identifier encoding, improve glossary and update to XEP-0384 version 0.8.0:</p>
<ul>
<li>Specify usage of Base64 encoding for key identifiers within trust messages</li>
<li>Specify usage of Base16 encoding for key identifiers within Trust Message URIs</li>
<li>Use Base64-encoded key identifiers in examples</li>
<li>Add 'hash value' as example of key identifier</li>
<li>Update OMEMO's namespace to 'urn:xmpp:omemo:2'</li>
<li>Update namespace to 'urn:xmpp:tm:1'</li>
</ul>
</remark>
</revision>
<revision>
<version>0.5.1</version>
<date>2021-05-14</date>
<initials>melvo</initials>
<remark>
<p>Update to XEP-0450 version 0.3.0 and apply consistent formatting:</p>
<ul>
<li>Update ATM's namespace to 'urn:xmpp:atm:1'</li>
<li>Apply consistent formatting for revision history</li>
</ul>
</remark>
</revision>
<revision>
<version>0.5.0</version>
<date>2021-04-16</date>
<initials>melvo</initials>
<remark>
<p>Update to XEP-0420 version 0.4.0 and adapt namespace to shortname:</p>
<ul>
<li>Replace SCE's old 'content' element by its new 'envelope' element</li>
<li>Replace SCE's old 'payload' element by its new 'content' element</li>
<li>Update SCE's namespace to 'urn:xmpp:sce:1'</li>
<li>Change namespace to 'urn:xmpp:tm:0'</li>
</ul>
</remark>
</revision>
<revision>
<version>0.4.0</version>
<date>2021-04-13</date>
<initials>melvo</initials>
<remark>
<p>Add new section, use more precise sentences, apply consistent formatting:</p>
<ul>
<li>Add new section for Trust Message URIs</li>
<li>Use 'that' instead of 'which' for restrictive clauses</li>
<li>Apply consistent formatting for paragraphs and revision history</li>
</ul>
</remark>
</revision>
<revision>
<version>0.3.0</version>
<date>2020-12-19</date>
<initials>melvo</initials>
<remark>
<p>Clarify usage, use real namespace for examples and add missing section:</p>
<ul>
<li>Clarify usage of trust messages by protocols such as &xep0450;</li>
<li>Use namespace 'urn:xmpp:atm:0' of &xep0450; as example for 'usage' attribute</li>
<li>Add section 'Security Considerations'</li>
</ul>
</remark>
</revision>
<revision>
<version>0.2.0</version>
<date>2020-11-05</date>
<initials>melvo</initials>
<remark>
<p>Improve explanations, descriptions and examples, introduce new attribute and complete all sections:</p>
<ul>
<li>Remove link to encryption protocol namespaces</li>
<li>Add short name</li>
<li>Shorten and improve introduction</li>
<li>Use emphasizing text formatting instead of quotation marks</li>
<li>Add new section for explaining the core properties of trust messages</li>
<li>Add examples comparing trust messages to public key certificates</li>
<li>Improve description of trust message structure</li>
<li>Introduce 'usage' attribute for 'trust-message' element</li>
<li>Focus on &xep0420; and adjust examples accordingly</li>
<li>Complete sections 'IANA Considerations', 'XMPP Registrar Considerations' and 'XML Schema'</li>
</ul>
</remark>
</revision>
<revision>
<version>0.1.0</version>
<date>2020-02-27</date>
<initials>XEP Editor (jsc)</initials>
<remark>Accepted by vote of Council on 2020-02-19</remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2020-02-15</date>
<initials>melvo</initials>
<remark>First draft</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='introduction'>
<p>
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 an additional malicious endpoint, the end-to-end encrypted messages can be read and manipulated by the attacker.
</p>
<p>
When using end-to-end encryption where public long-term keys are transmitted over a channel that 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 another channel that is already protected against active attacks to maintain the confidentiality of sent messages and ensure the authenticity and integrity of received messages.
Trust messages can be used to transfer the needed data via XMPP for performing such an authentication.
Furthermore, they can transmit the data used for distrusting a key.
</p>
</section1>
<section1 topic='Glossary' anchor='glossary'>
<dl>
<di>
<dt>Endpoint</dt>
<dd>
Communication endpoint owning exactly one public long-term key.
In most cases that is an XMPP client instance.
In the terminology of &xep0384;, that is a <em>device</em>.
To cover also the possibility for using multiple endpoints on the same physical device and via the same client instance, the general term <em>endpoint</em> is used.
</dd>
</di>
<di>
<dt>Key authentication</dt>
<dd>
Verification that a key received over an insecure channel is actually the one of the assumed endpoint
</dd>
</di>
<di>
<dt>Key identifier</dt>
<dd>
Identifier of a key (e.g., a hash value / fingerprint or the key itself)
</dd>
</di>
<di>
<dt>Public key certificate</dt>
<dd>
Electronic document used to prove the authenticity of a public key
</dd>
</di>
<di>
<dt>Trust message</dt>
<dd>
XMPP message that indicates whether specific keys are trusted or untrusted by the sending endpoint.
A trust message for an endpoint's key contains the key identifier of the given key.
</dd>
</di>
</dl>
</section1>
<section1 topic='Why Trust Messages?' anchor='why-trust-messages'>
<p>
Trust messages can be used in conjunction with an end-to-end encryption protocol such as &xep0373; or &xep0384; to automatically or semi-automatically establish secure channels protected against active attacks.
This protocol specifies how trust messages are transmitted and protocols such as &xep0450; specify how and for which purpose they are processed.
</p>
<section2 topic='General Advantages' anchor='why-trust-messages-general-advantages'>
<p>
Trust messages have the following advantages:
</p>
<section3 topic='No Permanent Storage' anchor='why-trust-messages-general-advantages-no-permanent-storage'>
<p>
A permanent storage is not needed.
Cached data can be be removed as soon as the recipient made use of them.
E.g., a server-side storage holding available data because it does not know when a client needs to access them, as for certificate-based approaches, is unnecessary.
</p>
</section3>
<section3 topic='No Additional Infrastructure' anchor='why-trust-messages-general-advantages-no-additional-infrastructure'>
<p>
An infrastructure in additional to the one used for messages is not needed because trust messages are ordinary messages.
E.g., a server-side storage and a mechanism for accessing it other than those used for messages is unnecessary.
</p>
</section3>
</section2>
<section2 topic='Advantages with Encryption' anchor='why-trust-messages-advantages-with-encryption'>
<p>
The authenticity and integrity of trust messages are ensured by a signing mechanism.
If trust messages are additionally encrypted, they have the following advantages:
</p>
<section3 topic='Same Cryptographic Properties' anchor='why-trust-messages-advantages-with-encryption-same-cryptographic-properties'>
<p>
The cryptographic properties of the encryption protocol are applied to the trust messages.
Properties such as confidentiality, forward secrecy and deniability can have a positive impact on the authentication of keys.
Hence, trust messages, in contrast to certificates, can e.g. be deniable toward a third party if the encryption protocol provides that kind of deniability.
</p>
</section3>
<section3 topic='Confidential Communication of Trust' anchor='why-trust-messages-advantages-with-encryption-confidential-communication-of-trust'>
<p>
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.
This means that an attacker cannot detect by the content of a trust message whether a specific key is trusted by the sender.
If the trust message is sent for an authentication of a key, the involved parties of that authentication will therefore stay anonymous toward an attacker.
</p>
<p>
The encryption protects against passive attacks on the transmission of the trust messages.
That way, an attacker cannot read the content of the trust messages.
</p>
<p>
The restriction to send trust messages only to endpoints with authenticated keys in addition to the encryption protects against active attacks on the transmission of the trust messages.
An attacker will even after introducing a malicious key not receive a trust message encrypted with that key.
</p>
</section3>
<section3 topic='No Selective Blocking' anchor='why-trust-messages-advantages-with-encryption-no-selective-blocking'>
<p>
Blocking data used to trust or distrust keys in transit is made more difficult.
In particular, an attacker is not able to selectively block transmitted data used to distrust the attacker's key.
</p>
<p>
If an attacker cannot distinguish whether the data sent from a client is used for trusting or distrusting a key, the attacker can only randomly block some messages or the whole communication.
If the communication is already compromised by an active attack, the attacker does not want to stop the whole communication.
During that state, the attacker has the possibility to keep on e.g. eavesdropping or altering messages.
Therefore, the attacker wants to block data that can lead to excluding the attacker.
But the attacker does not want to block the communication itself.
</p>
<p>
Data that is used by the recipient to distrust the attacker's key would make it impossible for the attacker to continue to encroach on the communication.
Thus, it is important to prevent an attacker from blocking data used for making trust decisions.
E.g., an approach using certificates permanently stored on a server cannot prevent an attacker from specifically blocking such data because certificates have to be discoverable and identifiable as such.
</p>
<p>
It might be possible to distinguish an encrypted trust message from other encrypted messages by analyzing the network traffic over a period of time.
However, the mitigation of that issue is out of scope.
</p>
</section3>
</section2>
</section1>
<section1 topic='Trust Message Structure' anchor='trust-message-structure'>
<p>
A trust message (i.e., the root <![CDATA[<message/>]]> element)
</p>
<ul>
<li>
MUST contain exactly one <![CDATA[<trust-message/>]]> direct child element that
<ul>
<li>
MUST be signed in a way to ensure its authenticity and integrity.
</li>
<li>
SHOULD be encrypted to ensure its confidentiality.
</li>
<li>
MUST have an <em>xmlns</em> attribute specifying its namespace <em>&ns;</em>.
</li>
<li>
MUST have a <em>usage</em> attribute specifying the namespace of the protocol that uses the trust message for a specific purpose.
</li>
<li>
MUST have an <em>encryption</em> attribute specifying the namespace of the encryption protocol that uses the keys.
</li>
<li>
MUST contain at least one <![CDATA[<key-owner/>]]> direct child element that
<ul>
<li>
MUST have a <em>JID</em> attribute specifying the bare JID of the key owner.
</li>
<li>
MUST contain at least one <![CDATA[<trust/>]]> or <![CDATA[<distrust/>]]> direct child element indicating the trust respectively distrust in a key.
Each <![CDATA[<trust/>]]> and <![CDATA[<distrust/>]]> element MUST contain exactly one Base64-encoded (see &rfc4648;) key identifier.
The kind of identifier that the key's encryption protocol specifies MUST be used.
</li>
</ul>
</li>
</ul>
</li>
<li>
SHOULD have a <![CDATA[type='chat']]> attribute which is needed to deliver the trust message to all endpoints (see <link url='https://xmpp.org/extensions/xep-0280.html#recommended-rules'>XEP-0280: Message Carbons</link>).
</li>
<li>
SHOULD contain a <![CDATA[<store xmlns='urn:xmpp:hints'/>]]> direct child element which is needed to deliver the trust message to each offline endpoint after it went online (see <link url='https://xmpp.org/extensions/xep-0313.html#business-storeret-user-archives'>XEP-0313: Message Archive Management</link> and <link url='https://xmpp.org/extensions/xep-0334.html#sect-idm45856619663120'>XEP-0334: Message Processing Hints</link>).
</li>
</ul>
<p>
The last two points are needed to achieve their mentioned goals because a trust message does not contain a <![CDATA[<body>]]> element which would automatically lead to the desired result.
</p>
<p>
In the following example, two &xep0384; keys of Alice are indicated as trusted, one key of Bob is indicated as trusted and two other ones of Bob are indicated as untrusted.
</p>
<example caption='Trust Message Element for Alice&apos;s and Bob&apos;s OMEMO Keys used by ATM'><![CDATA[
<trust-message xmlns=']]>&ns;<![CDATA[' usage=']]>&ns-atm;<![CDATA[' encryption=']]>&ns-omemo;<![CDATA['>
<key-owner jid='alice@example.org'>
<trust>aFABnX7Q/rbTgjBySYzrT2FsYCVYb49mbca5yB734KQ=</trust>
<trust>IhpPjiKLchgrAG5cpSfTvdzPjZ5v6vTOluHEUehkgCA=</trust>
</key-owner>
<key-owner jid='bob@example.com'>
<trust>YjVI04NcbTPvXLaA95RO84HPcSvyOgEZ2r5cTyUs0C8=</trust>
<distrust>tCP1CI3pqSTVGzFYFyPYUMfMZ9Ck/msmfD0wH/VtJBM=</distrust>
<distrust>2fhJtrgoMJxfLI3084/YkYh9paqiSiLFDVL2m0qAgX4=</distrust>
</key-owner>
</trust-message>
]]></example>
</section1>
<section1 topic='Use Cases' anchor='use-cases'>
<p>
Trust messages MAY be sent unencrypted to solely communicate the trust in specific keys without any other protection.
But as described before, the strength of trust messages is the possibility to encrypt their content and choose to which endpoints they are sent according to the trust in the endpoints' keys.
</p>
<section2 topic='Unencrypted Trust Message' anchor='use-cases-unencrypted-trust-message'>
<p>
The <![CDATA[<trust-message/>]]> element MUST be signed before sending for ensuring the authenticity and integrity.
</p>
</section2>
<section2 topic='Encrypted Trust Message' anchor='use-cases-encrypted-trust-message'>
<p>
The <![CDATA[<trust-message/>]]> element SHOULD be signed and encrypted before sending for applying all advantages the encryption provides.
That protects against passive attacks on the transmission of the trust message.
The trust message SHOULD only be sent to endpoints whose keys have already been authenticated for also preventing active attacks on the transmission of the trust message.
</p>
<p>
Describing how the <![CDATA[<trust-message/>]]> element has to be used by each existing encryption protocol is out of scope.
&xep0420; specifies a common method for encrypting arbitrary elements which can be used by different encryption protocols.
When using an encryption protocol such as &xep0384; that uses &xep0420; (SCE), the SCE <![CDATA[<content/>]]> element MUST contain the <![CDATA[<trust-message/>]]> element as a direct child.
</p>
<section3 topic='SCE Profile' anchor='use-cases-encrypted-trust-message-sce-profile'>
<p>
A trust message SCE <![CDATA[<envelope/>]]> element
</p>
<ul>
<li>
MUST contain an <![CDATA[<rpad/>]]> affix element.
This prevents an attacker from finding out the trust message's content by its length and distinguishing a trust message from another kind of SCE message.
</li>
<li>
MUST contain a <![CDATA[<time/>]]> affix element.
This prevents an attacker from delivering trust messages in the wrong order or delivering a former trust message again.
If the trust messages are used by the recipient for making trust decisions, it protects the recipient from setting the opposite of the intended trust state by applying trust changes in the wrong order or reapplying a former change.
</li>
<li>
SHOULD contain a <![CDATA[<from/>]]> affix element.
This prevents an attacker from spoofing the sender.
</li>
<li>
SHOULD contain a <![CDATA[<to/>]]> affix element.
This prevents an attacker from spoofing the recipient.
</li>
</ul>
</section3>
<example caption='SCE Envelope Element Used for a Trust Message from Alice&apos;s Endpoint to Carol'><![CDATA[
<envelope xmlns=']]>&ns-sce;<![CDATA['>
<rpad>QHqW2arWFewoERL1a43wonBKpTmsrBWnc1d66HSDq85NgMLmjrDJV9lV</rpad>
<time stamp='2020-01-01T00:00:00'/>
<from jid='alice@example.org/notebook'/>
<to jid='carol@example.com'/>
<content>
<trust-message xmlns=']]>&ns;<![CDATA[' usage=']]>&ns-atm;<![CDATA[' encryption=']]>&ns-omemo;<![CDATA['>
<key-owner jid='alice@example.org'>
<trust>aFABnX7Q/rbTgjBySYzrT2FsYCVYb49mbca5yB734KQ=</trust>
<trust>IhpPjiKLchgrAG5cpSfTvdzPjZ5v6vTOluHEUehkgCA=</trust>
</key-owner>
<key-owner jid='bob@example.com'>
<trust>YjVI04NcbTPvXLaA95RO84HPcSvyOgEZ2r5cTyUs0C8=</trust>
<distrust>tCP1CI3pqSTVGzFYFyPYUMfMZ9Ck/msmfD0wH/VtJBM=</distrust>
<distrust>2fhJtrgoMJxfLI3084/YkYh9paqiSiLFDVL2m0qAgX4=</distrust>
</key-owner>
</trust-message>
</content>
</envelope>
]]></example>
</section2>
</section1>
<section1 topic='Implementation Notes' anchor='implementation-notes'>
<p>
&xep0280; 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 &xep0313;, 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.
</p>
<p>
This specification uses &xep0280; 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.
</p>
<p>
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 &xep0280; MAY be used and vice versa.
Even when a client does not yet have a contact, the client MAY use &xep0280; 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.
</p>
<p>
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 &xep0280;.
</p>
<p>
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.
</p>
</section1>
<section1 topic='Security Considerations' anchor='security-considerations'>
<p>
Protocols using trust messages SHOULD specify rules for processing them in order to create or sustain a secure communication.
Therefore, those protocols SHOULD state in which cases from which senders trust messages are used for making trust decisions and for which keys they are sent to whom.
</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana-considerations'>
<p>
This document requires no interaction with the Internet Assigned Numbers Authority (IANA).
</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='xmpp-registrar-considerations'>
<section2 topic='URI Query Types' anchor='xmpp-registrar-considerations-uri-query-types'>
<p>
As authorized by &xep0147;, the XMPP Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).
</p>
<section3 topic='trust-message' anchor='xmpp-registrar-considerations-uri-query-types-trust-message'>
<p>
An XMPP URI with the <em>trust-message</em> query type (defined as <em>Trust Message URI</em>) MAY be used to provide a trust message for various purposes and a single key owner out-of-band.
Such a URI MAY be encoded as a QR code and used if only a QR code scan is available as a trusted channel.
E.g., the <em>initial authentication</em> needed by &xep0450; can be performed by scanning a QR code that encodes a Trust Message URI.
</p>
<p>
Only a Trust Message URI from a trusted source SHOULD be processed because of its impact on the communication's security.
Therefore, users SHOULD be asked for confirmation if a Trust Message URI is used to make a trust decision.
</p>
<p>
The <em>JID</em> attribute of the <![CDATA[<key-owner/>]]> element MUST be used as the Trust Message URI's path.
The first key-value pair of the URI's query MUST represent the <em>encryption</em> attribute of the <![CDATA[<trust-message/>]]> element.
All remaining key-value pairs of the URI's query MUST represent the <![CDATA[<trust/>]]> respectively <![CDATA[<distrust/>]]> elements of the <![CDATA[<key-owner/>]]> element.
Each key identifier MUST be Base16-encoded (see &rfc4648;).
The key of a key-value pair MUST be the element's respectively attribute's name and the value their content.
</p>
<example caption='Trust Message URI for Bob&apos;s OMEMO keys'><![CDATA[
xmpp:bob@example.com?trust-message;encryption=]]>&ns-omemo;<![CDATA[;trust=623548d3835c6d33ef5cb680f7944ef381cf712bf23a0119dabe5c4f252cd02f;distrust=b423f5088de9a924d51b31581723d850c7cc67d0a4fe6b267c3d301ff56d2413;distrust=d9f849b6b828309c5f2c8df4f38fd891887da5aaa24a22c50d52f69b4a80817e
]]></example>
</section3>
</section2>
<section2 topic='Protocol Namespaces' anchor='xmpp-registrar-considerations-protocol-namespaces'>
<p>
This specification defines the following XMPP namespaces:
</p>
<ul>
<li>&ns;</li>
</ul>
</section2>
<section2 topic='Protocol Versioning' anchor='xmpp-registrar-considerations-protocol-versioning'>
&NSVER;
</section2>
</section1>
<section1 topic='XML Schema' anchor='xml-schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace=']]>&ns;<![CDATA['
xmlns=']]>&ns;<![CDATA['
elementFormDefault='qualified'>
<xs:element name='trust-message'>
<xs:complexType>
<xs:attribute name='usage' type='xs:string' use='required'/>
<xs:attribute name='encryption' type='xs:string' use='required'/>
<xs:sequence>
<xs:element ref='key-owner' minOccurs='1' maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='key-owner'>
<xs:complexType>
<xs:attribute name='jid' type='xs:string' use='required'/>
<xs:sequence>
<xs:element name='trust' type='xs:base64Binary' minOccurs='0' maxOccurs='unbounded'/>
<xs:element name='distrust' type='xs:base64Binary' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
</xep>