mirror of https://github.com/moparisthebest/xeps
374 lines
18 KiB
XML
374 lines
18 KiB
XML
<?xml version='1.0' encoding='UTF-8'?>
|
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
|
<!ENTITY % ents SYSTEM 'xep.ent'>
|
|
%ents;
|
|
]>
|
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
|
<xep>
|
|
<header>
|
|
<title>Best Practices for Use of SASL EXTERNAL with Certificates</title>
|
|
<abstract>This document specifies best practices for XMPP usage of the SASL EXTERNAL mechanism in the context of X.509 certificates.</abstract>
|
|
&LEGALNOTICE;
|
|
<number>0178</number>
|
|
<status>Active</status>
|
|
<type>Informational</type>
|
|
<sig>Standards</sig>
|
|
<approver>Council</approver>
|
|
<dependencies>
|
|
<spec>XMPP Core</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>N/A</shortname>
|
|
&stpeter;
|
|
&pgmillard;
|
|
<revision>
|
|
<version>1.0</version>
|
|
<date>2007-02-15</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Per a vote of the XMPP Council, advanced specification to Active.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.7</version>
|
|
<date>2007-02-06</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Clarified that the scope of this specification is limited to X.509 certificates.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.6</version>
|
|
<date>2007-01-29</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Allowed client to not include an authorization identity if the certificate contains no XMPP address (thus depending on the server to assign the identity).</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.5</version>
|
|
<date>2007-01-25</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Clarified distinction between authentication and authorization; corrected handling of authorization identities; corrected conditions under which SASL EXTERNAL mechanism is offered; specified recommended formats for client and server certificates.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.4</version>
|
|
<date>2006-11-27</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Modified XMPP address encapsulation methods per rfc3920bis; clarified conditions for certificates to be considered acceptable.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.3</version>
|
|
<date>2006-09-21</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Added TLS and SASL required child elements per rfc3920bis.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.2</version>
|
|
<date>2006-03-09</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Corrected client-server failure case to place error in SASL flow rather than binding flow; added note about non-X.509 usages.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.1</version>
|
|
<date>2006-03-09</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Initial version.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.3</version>
|
|
<date>2006-02-10</date>
|
|
<initials>psa/pgm</initials>
|
|
<remark><p>Specified inclusion of authorization identity for server-to-server.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.2</version>
|
|
<date>2006-02-10</date>
|
|
<initials>psa/pgm</initials>
|
|
<remark><p>Clarified distinction between authentication and authorization.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.1</version>
|
|
<date>2006-02-09</date>
|
|
<initials>psa/pgm</initials>
|
|
<remark><p>First draft.</p></remark>
|
|
</revision>
|
|
</header>
|
|
<section1 topic='Introduction' anchor='intro'>
|
|
<p>XMPP as specified in &rfc3920; and provisionally clarified in &rfc3920bis; allows the use of any SASL mechanism (see &rfc4422;) in the authentication of XMPP entities, including the SASL EXTERNAL mechanism. This document specifies a recommended protocol flow for such use in the context of X.509 certificates, specifically when negotiation of TLS is required by a deployment. <note>The protocol flows when TLS is not required are more complicated (e.g., alternate flows involving server dialback) and may be described in a future version of this document.</note> <note>This specification focuses on the use of the SASL EXTERNAL mechanism with X.509 certificates. Future specifications may document best practices for use of SASL EXTERNAL outside the context of the X.509 infrastructure, for example via Internet Protocol Security (IPSec) as specified in &rfc4301;.</note></p>
|
|
</section1>
|
|
<section1 topic='Client-to-Server Recommendation' anchor='c2s'>
|
|
<p>As specified in <cite>RFC 3920</cite> and provisionally clarified in <cite>rfc3920bis</cite>, if a JabberID is included in an X.509 certificate, it MUST be encapsulated as an id-on-xmppAddr Object Identifier. Although it is not necessary for an X.509 certificate to include a JabberID, it is RECOMMENDED that client certificates include at least one id-on-xmppAddr OID encapsulating the JabberID of associated user (e.g., "juliet@example.org"), and OPTIONAL for client certificates to include either more than one id-on-xmppAddr or no id-on-xmppAddr. This specification includes recommendations that address all three cases.</p>
|
|
<p>The RECOMMENDED protocol flow for client-to-server use of SASL EXTERNAL with end-user certificates is as follows:</p>
|
|
<ol>
|
|
<li>
|
|
<p>Client initiates stream to server.</p>
|
|
<code><![CDATA[
|
|
<stream:stream
|
|
xmlns:stream='http://etherx.jabber.org/streams'
|
|
xmlns='jabber:client'
|
|
to='example.com'
|
|
version='1.0'>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>Server replies with stream header.</p>
|
|
<code><![CDATA[
|
|
<stream:stream
|
|
xmlns:stream='http://etherx.jabber.org/streams'
|
|
xmlns='jabber:client'
|
|
id='c2s_234'
|
|
from='example.com'
|
|
version='1.0'>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>Server advertises TLS stream feature.</p>
|
|
<code><![CDATA[
|
|
<stream:features>
|
|
<starttls xmlns='urn:ietf:params:xml:ns:xmpp-tls'>
|
|
<required/>
|
|
</starttls>
|
|
</stream:features>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>Client sends STARTTLS command to server.</p>
|
|
<code><![CDATA[
|
|
<starttls xmlns='urn:ietf:params:xml:ns:xmpp-tls'/>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>Server informs client to proceed.</p>
|
|
<code><![CDATA[
|
|
<proceed xmlns='urn:ietf:params:xml:ns:xmpp-tls'/>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>Client presents certificate.</p>
|
|
</li>
|
|
<li>
|
|
<p>Server and client negotiate TLS and client initiates a new stream header to server.</p>
|
|
<code><![CDATA[
|
|
<stream:stream
|
|
xmlns:stream='http://etherx.jabber.org/streams'
|
|
xmlns='jabber:client'
|
|
to='example.com'
|
|
version='1.0'>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>Server replies with stream header.</p>
|
|
<code><![CDATA[
|
|
<stream:stream
|
|
xmlns:stream='http://etherx.jabber.org/streams'
|
|
xmlns='jabber:client'
|
|
id='c2s_345'
|
|
from='example.com'
|
|
version='1.0'>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>Server advertises SASL mechanisms. If server expects that client will be able to authenticate and authorize as the identity provided in the presented certificate, then server SHOULD advertize the SASL EXTERNAL mechanism; otherwise, if presented certificate is unacceptable (e.g., because the certificate is expired, not yet valid, or revoked, or because the root certificate was issued by a certification authority that is untrusted), server MUST NOT offer EXTERNAL mechanism.</p>
|
|
<code><![CDATA[
|
|
<stream:features>
|
|
<mechanisms xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
|
|
<mechanism>EXTERNAL<mechanism>
|
|
<mechanism>DIGEST-MD5<mechanism>
|
|
<mechanism>ANONYMOUS<mechanism>
|
|
<required/>
|
|
</mechanisms>
|
|
</stream:features>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>Because client presented a certificate, client SHOULD consider EXTERNAL to be its preferred SASL mechanism. If the client certificate includes only one XMPP address and the user wishes to authorize as the identity that has been authenticated by the TLS layer (i.e., the XMPP address that is contained in the client certificate), then the client SHOULD NOT include an authorization identity (i.e., the XML character data for the <auth/> element SHOULD be "=", indicating an empty response); if the client certificate contains more than one XMPP address or if the user wishes to authorize as another identity, then the client MUST include an authorization identity; if the client certificate contain no XMPP address, then the client SHOULD include an authorization identity (but MAY include no authorzation identity since the client may not even know its identity, instead having it assigned by the server).</p>
|
|
<code><![CDATA[
|
|
<auth xmlns='urn:ietf:params:xml:ns:xmpp-sasl' mechanism='EXTERNAL'>=</auth>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>Server determines whether to allow authentication and authorization of user.</p>
|
|
<ol>
|
|
<li>
|
|
<p>If the certificate presented by the client contains only one valid XMPP address that corresponds to a registered account on the server and client did not pass an authorization identity in the SASL exchange, then the server SHOULD allow authentication and authorization of that JID. For the purpose of client authentication and authorization with a server, a valid XMPP address is a JID encapsulated as a subjectAltName entity of type otherName with an ASN.1 Object Identifier of "id-on-xmppAddr" as specified in Section 5.1.1. of <cite>RFC 3920</cite>.</p>
|
|
<code><![CDATA[
|
|
<success xmlns='urn:ietf:params:xml:ns:xmpp-sasl'/>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>If the certificate contains more than one valid XMPP address that corresponds to a registered account on the server (e.g., because the server offers virtual hosting), then the server SHOULD allow authentication and authorization of the JID specified as the authorization identity.</p>
|
|
<code><![CDATA[
|
|
<success xmlns='urn:ietf:params:xml:ns:xmpp-sasl'/>
|
|
]]></code>
|
|
<p>If no authorization identity is included, then the server MUST return a SASL failure case of <invalid-authzid/> and close the stream.</p>
|
|
<code><![CDATA[
|
|
<failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
|
|
<invalid-authzid/>
|
|
</failure>
|
|
</stream:stream>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>If the certificate does not contain an XMPP address, then the server MAY attempt to determine if there is a registered account associated with the user, for example by performing an LDAP lookup based on the Common Name in the certificate; if such a JID mapping is successful and the mapped JID matches the authorization identity provided, then the server SHOULD allow authentication and authorization of that mapped JID.</p>
|
|
<code><![CDATA[
|
|
<success xmlns='urn:ietf:params:xml:ns:xmpp-sasl'/>
|
|
]]></code>
|
|
<p>If JID mapping is unsuccessful, then the server MUST return a SASL failure case of <not-authorized/> and close the stream.</p>
|
|
<code><![CDATA[
|
|
<failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
|
|
<not-authorized/>
|
|
</failure>
|
|
</stream:stream>
|
|
]]></code>
|
|
<p>If JID mapping is successful but the mapped JID does not match the authorization identity provided (if any), then the server MUST return a SASL failure case of <invalid-authzid/> and close the stream.</p>
|
|
<code><![CDATA[
|
|
<failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
|
|
<invalid-authzid/>
|
|
</failure>
|
|
</stream:stream>
|
|
]]></code>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
<li>
|
|
<p>If SASL authentication succeeded, client opens new stream, then client and server proceed with resource binding as described in <cite>RFC 3920</cite>.</p>
|
|
</li>
|
|
</ol>
|
|
</section1>
|
|
<section1 topic='Server-to-Server Recommendation' anchor='s2s'>
|
|
<p>As specified in <cite>RFC 3920</cite> and provisionally clarified in <cite>rfc3920bis</cite>, if a JabberID is included in an X.509 certificate, it MUST be encapsulated as an id-on-xmppAddr Object Identifier. Although it is not necessary for an X.509 certificate to include a JabberID, it is RECOMMENDED that server certificates include the id-on-xmppAddr OID encapsulating the JabberID of the bare XMPP server domain only (e.g., "example.org"). In addition, it is RECOMMENDED in the case of server certificates for the server's hostname to be encapsulated as a subjectAltName extension of type dNSName. Furthermore it is quite common for XMPP servers to also offer associated services as subdomains of the server; if a server offers such services then it is RECOMMENDED to either include an id-on-xmppAddr OID for each subdomain or to include a dnsName containing the wildcard character '*' applying to the left-most domain name component or component fragment (this is considered to match any single component or component fragment, e.g., *.example.org matches foo.example.org but not bar.foo.example.org, and im*.example.net matches im1.example.net and im2.example.net but not chat.example.net). This specification includes recommendations that address all three cases.</p>
|
|
<p>The RECOMMENDED protocol flow for server-to-server use of SASL EXTERNAL with server (domain) certificates is as follows:</p>
|
|
<ol>
|
|
<li>
|
|
<p>Server1 initiates stream to server2.</p>
|
|
<code><![CDATA[
|
|
<stream:stream
|
|
xmlns:stream='http://etherx.jabber.org/streams'
|
|
xmlns='jabber:server'
|
|
from='conference.example.org'
|
|
to='example.com'
|
|
version='1.0'>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>Server2 replies with stream header.</p>
|
|
<code><![CDATA[
|
|
<stream:stream
|
|
xmlns:stream='http://etherx.jabber.org/streams'
|
|
xmlns='jabber:server'
|
|
id='s2s_234'
|
|
from='example.com'
|
|
to='conference.example.org'
|
|
version='1.0'>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>Server2 advertises TLS stream feature.</p>
|
|
<code><![CDATA[
|
|
<stream:features>
|
|
<starttls xmlns='urn:ietf:params:xml:ns:xmpp-tls'>
|
|
<required/>
|
|
</starttls>
|
|
</stream:features>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>Server1 sends STARTTLS command to Server2.</p>
|
|
<code><![CDATA[
|
|
<starttls xmlns='urn:ietf:params:xml:ns:xmpp-tls'/>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>Server2 informs Server1 to proceed.</p>
|
|
<code><![CDATA[
|
|
<proceed xmlns='urn:ietf:params:xml:ns:xmpp-tls'/>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>Server1 presents certificate.</p>
|
|
</li>
|
|
<li>
|
|
<p>Server2 validates certificate.</p>
|
|
<ol>
|
|
<li>
|
|
<p>If certificate is unacceptable (e.g., because the certificate is expired, not yet valid, or revoked), Server2 closes Server1's TCP connection.</p>
|
|
</li>
|
|
<li>
|
|
<p>Else Server2 completes successful TLS negotiation and Server1 initiates a new stream header to Server2.</p>
|
|
<code><![CDATA[
|
|
<stream:stream
|
|
xmlns:stream='http://etherx.jabber.org/streams'
|
|
xmlns='jabber:server'
|
|
from='conference.example.org'
|
|
to='example.com'
|
|
version='1.0'>
|
|
]]></code>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
<li>
|
|
<p>Server2 replies with stream header.</p>
|
|
<code><![CDATA[
|
|
<stream:stream
|
|
xmlns:stream='http://etherx.jabber.org/streams'
|
|
xmlns='jabber:server'
|
|
id='s2s_345'
|
|
from='example.com'
|
|
to='conference.example.org'
|
|
version='1.0'>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>Server2 advertises SASL mechanisms. If Server2 expects that Server1 will be able to authenticate and authorize as the identity provided in the certificate that Server1 already provided (e.g., because the two servers share a common root certification authority, Server1's certificate has not been revoked, and the address provided in the 'from' address of Server1's initial stream header matches the authentication identity or a subdomain thereof), then Server2 SHOULD advertize the SASL EXTERNAL mechanism.</p>
|
|
<code><![CDATA[
|
|
<stream:features>
|
|
<mechanisms xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
|
|
<mechanism>EXTERNAL<mechanism>
|
|
<required/>
|
|
</mechanisms>
|
|
</stream:features>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>If Server2 advertizes SASL EXTERNAL, Server1 SHOULD consider EXTERNAL to be its preferred SASL mechanism. Server1 SHOULD include an authorization identity (base64-encoded as described in RFC 3920) as the XML character data of the <auth/> element, which SHOULD be the same as the 'from' address on the stream header it sent to Server2.</p>
|
|
<code><![CDATA[
|
|
<auth xmlns='urn:ietf:params:xml:ns:xmpp-sasl' mechanism='EXTERNAL'>Y29uZmVyZW5jZS5leGFtcGxlLm9yZwo=</auth>
|
|
]]></code>
|
|
<p>(In this case, the authorization identity is "conference.example.org".)</p>
|
|
</li>
|
|
<li>
|
|
<p>Server2 determines if hostname is valid.</p>
|
|
<ol>
|
|
<li>
|
|
<p>If the authorization identity provided by Server1 matches one of the valid XMPP addresses in the certificate, Server2 SHOULD return success. For the purpose of server authentication with another server, a valid XMPP address is a JID encapsulated as a subjectAltName extension of type otherName with an ASN.1 Object Identifier of "id-on-xmppAddr" or a domain name (which MAY include the wildcard character '*') encapsulated as a subjectAltName extension of type dNSName.</p>
|
|
<code><![CDATA[
|
|
<success xmlns='urn:ietf:params:xml:ns:xmpp-sasl'/>
|
|
]]></code>
|
|
</li>
|
|
<li>
|
|
<p>Else server MUST return a ¬authorized; failure and close the stream.</p>
|
|
<code><![CDATA[
|
|
<failure xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
|
|
<not-authorized/>
|
|
</failure>
|
|
</stream:stream>
|
|
]]></code>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
</ol>
|
|
</section1>
|
|
<section1 topic='Security Considerations' anchor='security'>
|
|
<p>This document introduces no security considerations or concerns above and beyond those discussed in <cite>RFC 3920</cite>.</p>
|
|
</section1>
|
|
<section1 topic='IANA Considerations' anchor='iana'>
|
|
<p>This document requires no interaction with &IANA;.</p>
|
|
</section1>
|
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
|
<p>This document requires no interaction with the ®ISTRAR;.</p>
|
|
</section1>
|
|
<section1 topic='Acknowledgements' anchor='ack'>
|
|
<p>Thanks to Dave Cridland, Philipp Hancke, Joe Hildebrand, Justin Karneges, Rob Norris, and Matthias Wimmer for their comments.</p>
|
|
</section1>
|
|
<section1 topic='Author Note' anchor='authornote'>
|
|
<p>Peter Millard, co-author of the initial version of this specification, died on April 26, 2006. The remaining author appreciates his assistance in defining the best practices described herein.</p>
|
|
</section1>
|
|
|
|
</xep>
|