XEP-xxxx: XMPP Connections across HTTPS (HACX)

1. Introduction¶

Various methods exist to connect to XMPP servers over direct TLS, SRV records for XMPP over TLS (XEP-0368) [1] defines SRV records, RFC 7395 [2] defines websocket, XMPP Over BOSH (XEP-0206) [3] defines BOSH. HACX defines a method to retrieve all of those along with optional extra information such as SNI/ALPN requirements and pinned public keys from a RFC 5785 [4] well-known URI over HTTPS.

2. Requirements¶

• Needs to look like HTTPS.
• Needs to support all current and future XMPP connection methods through extensibility
• Should be as simple as possible, all XMPP clients already have an XML parser, most have an HTTP client

Several alternatives were considered to avoid writing yet-another-spec but they were all deficient in various ways:

• DOH (DNS-over-HTTPS) or DNS-over-TLS could be used to look up SRV records for XMPP over TLS (XEP-0368) [1] SRV records, but can't mix priority/weight with Discovering Alternative XMPP Connection Methods (XEP-0156) [5] alternative methods, and can't support extra features such as domain fronting (arbitrary SNI/ALPN)
• Discovering Alternative XMPP Connection Methods (XEP-0156) [5] has a similar HTTP .well-known URL document, but since the XSF doesn't control the namespace we can't extend it with the extra required attributes to support weight/priority/alpn/sni and pinned keys, along with future methods. The business rules also state that it must only be used as a fallback which is in direct opposition of what HACX requires.
• POSH [6] pins certificates instead of keys, and also explicitly allows other forms of authentication (like a cert issued by a trusted CA), which is incompatible with a network attacker that might control a CA

3. Protocol¶

HACX servers MUST use HTTPS. This means that the HACX client MUST verify the certificate of the HTTPS service at the source domain in order to securely "bootstrap" into the use of HACX; specifically, the rules of RFC 2818 [7] apply to this "bootstrapping" step to provide a secure basis for all subsequent HACX operations. HACX clients and servers MUST support HPKP (RFC 7469 [8]), HSTS (RFC 6797 [9]), and DANE (RFC 6698 [10]), and SHOULD support any future standard that serves to increase the security of this HTTPS request.

A HACX document is retrieved over secure HTTP in the following way:

1. The HACX client performs an HTTPS GET request at the source domain to the path "/.well-known/xmpp-{client/server}.xml". The value of "{client/server}" is either "client" or "server" depending on if you want to connect to a server providing the jabber:client or jabber:server namespace. For example, if a client is trying to connect a user with the jid romeo@montague.tld using HACX, then the HTTPS GET request would be as follows: GET /.well-known/xmpp-client.xml HTTP/1.1 Host: montague.tld.
2. If the server has a HACX document, it responds with the document like so:

   <hacx ttl="604800">
       <tls ip="fd00:feed:dad:beef::1" port="443" priority="5"/>
       <tls ip="10.1.1.1" port="443" priority="10" sni="fronting.tld" alpn="aDI="/>
       <tls ip="10.1.1.2" port="443" priority="15" sni="montague.tld" alpn="eG1wcC1jbGllbnQ=">
           <public-key-pin sha-256="4/mggdlVx8A3pvHAWW5sD+qJyMtUHgiRuPjVC48N0XQ=" sha-512="25N+1hB2Vo42l9lSGqw+n3BKFhDHsyork8ou+D9B43TXeJ1J81mdQEDqm39oR/EHkPBDDG1y5+AG94Kec0xVqA=="/>
       </tls>
       <websocket url="wss://montague.tld/ws" ip="10.1.1.3" port="443" priority="20" weight="50" sni="anotherfront.tld">
       <bosh url="https://example.tld/bosh" ip="fd00:feed:dad:beef::2" port="443" priority="20" weight="50">
   </hacx>

   The document is defined as such:
   1. ttl attribute: If missing, assume a value of 30, MUST be non-negative integer representing number of seconds to cache this document. If connectivity is blocked, you SHOULD still use this document past TTL expiration.
   2. tls element: This connection type is SRV records for XMPP over TLS (XEP-0368) [1] style Direct TLS connection
   3. websocket element: This connection type is RFC 7395 [2] websocket connection
   4. bosh element: This connection type is XMPP Over BOSH (XEP-0206) [3] bosh connection
   5. public-key-pin element: This can be on any connection type, and is a base64 hash of the DER encoding of certificate's public key, not the certificate itself, HPKP (RFC 7469 [8]) style. Multiple of these may be provided, only one must match, and all different hash types for a single element MUST match the same key so only one hash type need be checked. If these are provided and none match, the connection MUST be considered untrusted and MUST be aborted. Attributes can be any valid registered hash name. If missing, TLS certificates MUST be validated the same way as for STARTTLS. (i.e., as specified in XMPP Core [11]), or another equivalent such as DANE (RFC 6698 [10]) or POSH (POSH [6])
   6. ip attribute: MUST be provided as either an IPv4 or IPv6 address, implementors SHOULD provide both IPv4 and IPv6 options.
   7. port attribute: MUST be provided, for maximum censorship resistance implementors are encouraged to use 443 to blend with HTTPS.
   8. url attribute: MUST be provided for websocket/bosh elements, MUST NOT be provided for tls elements, protocol MUST be wss:// for websocket, https:// for bosh (mandatory TLS), ip and port MUST be overriden with ip/port attributes, hostname in URL MUST be sent in HTTP Host: header
   9. sni attribute: If missing, HACX client MUST NOT use/set the SNI TLS extension at all, if set, HACX client MUST set the SNI TLS extension to this value exactly.
   10. alpn attribute: If missing, HACX client MUST NOT use/set the ALPN (RFC 7301 [12]) TLS extension at all, if set, HACX client MUST base64 decode this field and set the ALPN TLS extension to that value exactly. MUST NOT be provided for websocket/bosh elements so proper http protocol can be negotiated.
   11. priority attribute: MUST be provided, same as definition in RFC 2782 [13] SRV records
   12. weight attribute: If missing, default to 0, same as definition in RFC 2782 [13] SRV records
   13. HACX clients MUST discard any connection method they don't have support for, or do not wish to try due to privacy reasons (ALPN set to xmpp-client), then SHOULD try them in proper priority/weight order until a successful connection is achieved. Any type of connection error MUST trigger a fallback to the next record. Common errors include invalid protocol (HTTP when you expect XMPP), TLS certificate validation errors, and more.
3. If the server knows where a HACX document can be found, it MUST respond with a HTTP status code 302 (Found) and a redirect to the correct location. The location provided in the redirect response MUST specify an HTTPS URI. To protect against circular references, it is RECOMMENDED that HACX clients follow no more than 10 redirects, although applications or implementations can require that fewer redirects be followed.
4. If the server does not have or know about a HACX document, it MUST respond with HTTP status code 404 (Not Found).

4. Use Cases¶

HACX provides a simple way to look up exactly how to connect to any given XMPP server in a simple, censorship resistant, distributed way. An attacker would have to block all A and AAAA record lookups and/or HTTPS to completely block this lookup, and even then it's easily done over something like Tor which otherwise does not support things like DNS SRV or TXT lookups. Additionally, DNS SRV records can not provide values for SNI or ALPN extensions, or a relative priority for other connections methods like BOSH and Websockets.

5. Implementation Notes¶

This should be trivial to implement for any program that already implements SRV records for XMPP over TLS (XEP-0368) [1] and POSH [6], much of the same code can be reused.

Server operators might want to prioritize connection methods that maximize privacy, like no ALPN, domain fronting (different SNI value), or no SNI. Consider looking at everything available at an HTTP level to potentially lie to attackers, while providing correct info to users. Consider providing different sets of servers to different IP blocks or regions. Consider using any of the multitude of free or cheap HTTP hosts or CDNs to forward traffic to your real server. The possibilities are endless.

6. Security Considerations¶

POSH (POSH [6]) already provides the ability of anyone with control of an HTTPS server to override trust of TLS certificates for the XMPP server matching that domain, HACX is slightly different in that it pins public keys like HPKP (RFC 7469 [8]) and not certificates like POSH, but the delegation is the same.

HACX additionally delegates what were previously DNS lookups to the HTTPS server, since this is protected by TLS certificate validation, this should be even more secure than plain DNS, equivalent to something like DNS-over-HTTPS or DNS-over-TLS, but without trusting a 3rd party DNS server. DNSSEC delegation is preserved as well since it protects the A/AAAA record for the HTTPS host, and can also validate it with DANE (RFC 6698 [10]).

This does allow anyone with write access to the /.well-known/ directory on an HTTPS host to host a XMPP server for that domain even if they don't have access to create DNS records or listen on port 5222, but this was already true due to Discovering Alternative XMPP Connection Methods (XEP-0156) [5] (HTTP Lookup Method) and RFC 7395 [2]

7. IANA Considerations¶

Well-known URIs (RFC 5785 [4]) requires registration of new URI suffixes. This document specifies two URI suffixes:

URI Suffix: xmpp-client.xml
Change Controller: XSF
Reference: [TODO: HACX LINK HERE]
Related Information: XMPP jabber:client namespace

URI Suffix: xmpp-server.xml
Change Controller: XSF
Reference: [TODO: HACX LINK HERE]
Related Information: XMPP jabber:server namespace

The Well-known URI registry is currently located here.

8. XMPP Registrar Considerations¶

This document requires no interaction with the XMPP Registrar [14].

Appendices

Appendix A: Document Information¶

Series

XEP

Number

xxxx

Publisher

XMPP Standards Foundation

Status

ProtoXEP

Type

Standards Track

Version

0.0.2

Last Updated

2018-05-16

Approving Body

XMPP Council

Dependencies

XEP-0368, RFC 5785

Supersedes

None

Superseded By

None

Short Name

NOT_YET_ASSIGNED

This document in other formats: XML  PDF

Appendix B: Author Information¶

Travis Burtrum

Email

travis@burtrum.org

JabberID

travis@burtrum.org

Appendix C: Legal Notices¶

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.

Given that this XMPP Extension Protocol normatively references IETF technologies, discussion on the <xsf-ietf@xmpp.org> list might also be appropriate.

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¶

Appendix H: Revision History¶

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

1. Version 0.0.2 (2018-05-16)¶

   Fix requirements, editing, add alternatives.

   tjb
2. Version 0.0.1 (2018-05-01)¶

   First draft.

   tjb

Appendix I: Bib(La)TeX Entry

@report{burtrum2018xepxxxx,
  title = {XMPP Connections across HTTPS (HACX)},
  author = {Burtrum, Travis},
  type = {XEP},
  number = {xxxx},
  version = {0.0.2},
  institution = {XMPP Standards Foundation},
  url = {https://xmpp.org/extensions/xep-xxxx.html},
  date = {2018-05-01/2018-05-16},
}

END