xeps/xep-0262.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>Use of ZRTP in Jingle RTP Sessions</title>
  <abstract>This specification defines how to use ZRTP (RFC 6189) in the Jingle application type for the Real-time Transport Protocol (RTP) as a way to negotiate media path key agreement for secure RTP in one-to-one media sessions.</abstract>
  &LEGALNOTICE;
  <number>0262</number>
  <status>Draft</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0166</spec>
    <spec>XEP-0167</spec>
    <spec>RFC 6189</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>jingle-zrtp</shortname>
  <schemaloc>
    <url>http://xmpp.org/schemas/jingle-apps-rtp-zrtp.xsd</url>
  </schemaloc>
  <discuss>jingle</discuss>
  &stpeter;
  <revision>
    <version>1.0</version>
    <date>2011-06-15</date>
    <initials>psa</initials>
    <remark><p>Per a vote of the XMPP Council, advanced specification to Draft.</p></remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2011-04-12</date>
    <initials>psa</initials>
    <remark><p>Updated reference to reflect publication of RFC 6189; clarified that inclusion of the hash is optional.</p></remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2010-08-09</date>
    <initials>psa</initials>
    <remark><p>In harmony with the ZRTP spec, moved communication of &lt;zrtp-hash/&gt; element from Jingle session-info message to jingle-invite, specifically as a child of the &lt;encryption/&gt; element from XEP-0167; increased protocol version from zero to one.</p></remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2009-02-25</date>
    <initials>psa</initials>
    <remark><p>Initial published version.</p></remark>
  </revision>
  <revision>
    <version>0.0.2</version>
    <date>2009-02-24</date>
    <initials>psa</initials>
    <remark><p>Defined dedicated namespace for the zrtp-hash element to improve service discovery and handling of session-info message; clarified protocol flow and security considerations.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2009-02-17</date>
    <initials>psa</initials>
    <remark><p>First draft, copied from XEP-0167.</p></remark>
  </revision>
</header>

<section1 topic='Protocol' anchor='protocol'>
  <p>&xep0167; recommends the use of the Secure Real-time Transport Protocol (SRTP) for end-to-end encryption of RTP sessions negotiated using &xep0166;. An alternative approach to end-to-end encryption of RTP traffic is provided by &rfc6189;, developed by Phil Zimmermann, the inventor of "Pretty Good Privacy" (PGP). Although negotiation of ZRTP mainly occurs in the media channel rather than the signalling channel, the ZRTP specification defines one SDP attribute called "zrtp-hash" (this communicates the ZRTP version supported as well as a hash of the Hello message). Inclusion of this information is OPTIONAL in both SIP/SDP and Jingle.</p>
  <p>The SDP format is shown below.</p>
  <code>
a=zrtp-hash:zrtp-version zrtp-hash-value
  </code>
  <p>An example follows.</p>
  <code>
a=zrtp-hash:1.10 fe30efd02423cb054e50efd0248742ac7a52c8f91bc2df881ae642c371ba46df
  </code>
  <p>This SDP attribute can be translated into Jingle as a &lt;zrtp-hash/&gt; element qualified by the 'urn:xmpp:jingle:apps:rtp:zrtp:1' namespace, as shown below.</p>
  <code><![CDATA[
<zrtp-hash version='zrtp-version' xmlns='urn:xmpp:jingle:apps:rtp:zrtp:1'>zrtp-hash-value</zrtp-hash>
  ]]></code>
  <p>An example follows.</p>
  <code><![CDATA[
<zrtp-hash version='1.10' xmlns='urn:xmpp:jingle:apps:rtp:zrtp:1'>
  fe30efd02423cb054e50efd0248742ac7a52c8f91bc2df881ae642c371ba46df
</zrtp-hash>
  ]]></code>
  <p>The &lt;zrtp-hash/&gt; element is sent as a child of the &lt;encryption/&gt; element defined in &xep0167;.</p>
  <p>If the Jingle initiator wishes to use ZRTP, it includes the &lt;zrtp-hash/&gt; element in its session invitation (where it hashes over its own Hello message as described in the ZRTP specification).</p>
  <example caption="Initiator sends session invitation with zrtp-hash"><![CDATA[
<iq from='romeo@montague.lit/orchard'
    id='uz61v4m4'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-initiate'
          initiator='romeo@montague.lit/orchard'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='voice'>
      <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
        <payload-type id='96' name='speex' clockrate='16000'/>
        <payload-type id='97' name='speex' clockrate='8000'/>
        <payload-type id='18' name='G729'/>
        <payload-type id='103' name='L16' clockrate='16000' channels='2'/>
        <payload-type id='98' name='x-ISAC' clockrate='8000'/>
        <encryption required='true'>
          <zrtp-hash xmlns='urn:xmpp:jingle:apps:rtp:zrtp:1' version='1.10'>
            fe30efd02423cb054e50efd0248742ac7a52c8f91bc2df881ae642c371ba46df
          </zrtp-hash>
        </encryption>
      </description>
      <transport xmlns='urn:xmpp:jingle:transports:ice-udp:1'
                 pwd='asd88fgpdd777uzjYhagZg'
                 ufrag='8hhy'>
        <candidate component='1'
                   foundation='1'
                   generation='0'
                   id='el0747fg11'
                   ip='10.0.1.1'
                   network='1'
                   port='8998'
                   priority='2130706431'
                   protocol='udp'
                   type='host'/>
        <candidate component='1'
                   foundation='2'
                   generation='0'
                   id='y3s2b30v3r'
                   ip='192.0.2.3'
                   network='1'
                   port='45664'
                   priority='1694498815'
                   protocol='udp'
                   rel-addr='10.0.1.1'
                   rel-port='8998'
                   type='srflx'/>
      </transport>
    </content>
  </jingle>
</iq>
    ]]></example>
    <p>If the receiving party wishes to proceed with ZRTP negotiation, it also includes the &lt;zrtp-hash/&gt; element in its session-accept message (where it hashes over its own Hello message as described in the ZRTP specification).</p>
    <example caption="Responder sends session-accept"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
    id='pn2va48j'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-accept'
          initiator='romeo@montague.lit/orchard'
          responder='juliet@capulet.lit/balcony'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='voice'>
      <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
        <payload-type id='97' name='speex' clockrate='8000'/>
        <payload-type id='18' name='G729'/>
        <encryption>
          <zrtp-hash xmlns='urn:xmpp:jingle:apps:rtp:zrtp:1' version='1.10'>
            badfbe66ff87fe135750377509b09b0babd1c3ec25fa4314565e2bf7ccc30299
          </zrtp-hash>
        </encryption>
      </description>
      <transport xmlns='urn:xmpp:jingle:transports:ice-udp:1'
                 pwd='YH75Fviy6338Vbrhrlp8Yh'
                 ufrag='9uB6'>
        <candidate component='1'
                   foundation='1'
                   generation='0'
                   id='or2ii2syr1'
                   ip='192.0.2.1'
                   network='0'
                   port='3478'
                   priority='2130706431'
                   protocol='udp'
                   type='host'/>
      </transport>
    </content>
  </jingle>
</iq>
    ]]></example>
  <p>Note that a unique zrtp-hash is needed for each media stream, since the hash for each stream is computed from a different ZRTP Hello message (e.g., if a session includes both audio and video then the value of the &lt;zrtp-hash/&gt; element included in the &lt;description/&gt; element for the audio stream will be different from the value for the video stream).</p>
</section1>

<section1 topic='Determining Support' anchor='disco'>
  <p>If an entity supports the use of ZRTP in Jingle as described in this document, it MUST advertise that fact in its responses to &xep0030; information ("disco#info") requests by returning a feature of "urn:xmpp:jingle:apps:rtp:zrtp:1":</p>
  <example caption='A disco#info query'><![CDATA[
<iq type='get' 
    from='calvin@usrobots.lit/lab'
    to='herbie@usrobots.lit/home'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
  ]]></example>
  <example caption='A disco#info response'><![CDATA[
<iq type='result' 
    from='herbie@usrobots.lit/home'
    to='calvin@usrobots.lit/lab'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <feature var='urn:xmpp:jingle:1'/>
    <feature var='urn:xmpp:jingle:apps:rtp:zrtp:1'/>
  </query>
</iq>
  ]]></example>
  <p>In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.</p>
</section1>

<section1 topic='Security Considerations' anchor='security'>
  <p>Security considerations for ZRTP itself are provided in <cite>RFC 6189</cite>.</p>
  <p>XMPP stanzas such as Jingle invite messages and service discovery exchanges are not encrypted or signed. As a result, it is possible for an attacker to intercept these stanzas and modify them, thus convincing one party that the other party does not support ZRTP and therefore denying the parties an opportunity to use ZRTP. However, because the zrtp-hash is mostly advisory, the parties could still use ZRTP even if the signalling channel is compromised.</p>
</section1>

<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>

<section1 topic='Acknowledgements' anchor='acks'>
  <p>Thanks to Werner Dittmann and Emil Ivov for their implementation feedback.</p>
</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
    <p>This specification defines the following XML namespace:</p>
    <ul>
      <li>urn:xmpp:jingle:apps:rtp:zrtp:1</li>
    </ul>
    <p>The &REGISTRAR; includes the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
  </section2>
  <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
    &NSVER;
  </section2>
</section1>

<section1 topic='XML Schemas' anchor='schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:jingle:apps:rtp:zrtp:1'
    xmlns='urn:xmpp:jingle:apps:rtp:zrtp:1'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0262: http://www.xmpp.org/extensions/xep-0262.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='zrtp-hash'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute name='version' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

</xs:schema>
  ]]></code>
</section1>

</xep>