xeps/inbox/user-auth.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
  <!ENTITY rfc4226 "<span class='ref'><link url='http://tools.ietf.org/html/rfc4226'>RFC 4226</link></span> <note>RFC 4226: HOTP: An HMAC-Based One-Time Password Algorithm &lt;<link url='http://tools.ietf.org/html/rfc4226'>http://tools.ietf.org/html/rfc4226</link>&gt;.</note>" >
  <!ENTITY rfc6238 "<span class='ref'><link url='http://tools.ietf.org/html/rfc6238'>RFC 6238</link></span> <note>RFC 6238: TOTP: Time-Based One-Time Password Algorithm &lt;<link url='http://tools.ietf.org/html/rfc6238'>http://tools.ietf.org/html/rfc6238</link>&gt;.</note>" >

%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Two-factor user authentication with a shared secret</title>
  <abstract>This document specifies a two-factor authentication mechanism to check if a XMPP account exists and if it is trying to use or access services or resources of certain device, application or service. Authentication mechanism is based on transmitting a password using Ad-Hoc Commands. Password is calculated from shared secret. </abstract>
  <legal>
    <copyright>This XMPP Extension Protocol is copyright (c) 1999 - 2013 by the XMPP Standards Foundation (XSF).</copyright>
    <permissions>Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the &quot;Specification&quot;), 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.</permissions>
    <warranty>## NOTE WELL: This Specification is provided on an &quot;AS IS&quot; 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. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##</warranty>
    <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 out of the use or inability to use 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.</liability>
    <conformance>This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at &lt;<link url='http://www.xmpp.org/extensions/ipr-policy.shtml'>http://www.xmpp.org/extensions/ipr-policy.shtml</link>&gt; or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).</conformance>
  </legal>
  <number>xxxx</number>
  <status>ProtoXEP</status>
  <type>Standards Strack</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0050</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>NOT_YET_ASSIGNED</shortname>
  <author>
    <firstname>Teemu</firstname>
    <surname>Väisänen</surname>
    <email>Teemu.Vaisanen@vtt.fi</email>
    <jid>uolevi@gmail.com</jid>
  </author>
  <revision>
    <version>0.0.1</version>
    <date>2013-12-19</date>
    <initials>tuv</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
	<p>
		This document offers mechanisms to solve the following problem:
		There are two XMPP client entities (Verifier and Prover). The
		Verifier can be presenting e.g., a physical device, an application
		or a service and and the Prover is presenting an XMPP account of
		user entity (e.g., a human) that wants to login.

		Before the Verifier can execute or ask executing any access
		control mechanism, e.g., to check if the Prover's XMPP accout is
		authorized use certain resource(s), the Prover must be authenticated.
		We present usage of two-factor authentication in which the following
		authentication factors are used:
	</p>
	<ul>
		<li>
			A knowledge factor that means something only the user knows.
			In this application this knowledge is a shared secret known
			only by the Prover and Verifier, and a full JID of the
			Verifier where a password calculated from this secret must
			be sent to.

			Notice that	Prover's XMPP account's username and password
			are not necessarily used as knowledge factors, if, e.g.,
			mechanisms presented in &xep0175; are used.
		</li>
		<li>
			The second factor is a possession factor that means something only
			the user has, e.g., a device or application that the user
			wants to use. The shared secret can be told only to certain
			Prover XMPP account that is	running in a certain device or in
			certain application.
		</li>
	</ul>
	<p>
		In addition to these, described mechanism offers possibility to
		approve authentication inside only a certain time-slot.
	</p>
	<p>
		Prover and Verifier entities mean same as in &rfc6238; but are
		implemented as two XMPP clients. When using terms of &xep0146;,
		Prover is Local Client and Verifier is Remote Client.
	</p>
	<p>
		Several mechanisms for client-to-client authentication, such as
		&xep0250; exist and can be used with the protocol defined in
		this document. This document describes a new simple and
		extendable protocol for two-factor one-way client authentication
		by specifying a profile on &xep0050;. One-way here means that
		the actual user (e.g, a human) of Prover's XMPP Client is not
		required to know anything about the Verifier.
	</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
    <p>This document addresses the following requirements:</p>
    <ul>
        <li>Enable the Verifier entity to perform authentication of
        their users (e.g., humans) by verifying that a Prover entity
        holds a shared secret.</li>
		<li>Verifier's and Prover's XMPP accounts do not necessarily need
		to know each other beforehand nor be contacts.</li>
        <li>Re-use existing XMPP and Jabber protocols wherever possible.</li>
    </ul>
</section1>


<section1 topic='Discovery' anchor='disco'>
    <p>
		A client MAY advertise any authentication commands it
		supports via &xep0030; (as described in <cite>XEP-0050</cite>).
    </p>
    <p>
		If these commands are advertised, &xep0115; can be used to
		query capability of authentication commands in a client.
		If the Prover and the Verifier are working on a same physical
		device, they both MAY know the exact format and existence of supported
		commands.
    </p>
</section1>

<section1 topic='Glossary' anchor='glossary'>
  <p>
	  The following table lists common terms and corresponding descriptions.
  </p>
  <dl>
    <di><dt>HMAC</dt><dd>Keyed-Hashing for Message Authentication</dd></di>
    <di><dt>HMAC-SHA-256</dt><dd>HMAC-SHA-256 is the realization of the
    HMAC message authentication code using the SHA-256 hash function.</dd></di>
    <di><dt>HMAC-SHA-512</dt><dd>HMAC-SHA-512 is the realization of the
    HMAC message authentication code using the SHA-512 hash function.</dd></di>
    <di><dt>HOTP</dt><dd>HMAC-Based One-Time Password Algorithm</dd></di>
    <di><dt>Local Client</dt><dd>An XMPP client that wants to authenticate
    itself to Remote Client.</dd></di>
    <di><dt>One-time pad</dt><dd>Example of perfectly secret encryption scheme.</dd></di>
    <di><dt>OTP</dt><dd>A one-time password is a password that is valid
    for only one login session or transaction.</dd></di>
    <di><dt>Prover</dt><dd>Same as Local Client.</dd></di>
    <di><dt>Remote Client</dt><dd>An XMPP client that authenticates Local Client.</dd></di>
    <di><dt>SHA</dt><dd>US Secure Hash Algorithms</dd></di>
    <di><dt>TOTP</dt><dd>Time-Based One-Time Password Algorithm</dd></di>
    <di><dt>Verifier</dt><dd>Same as Remote Client.</dd></di>
  </dl>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
    <p>
		This document defines a profile of <cite>XEP-0050</cite> that
		enables a client to perform the following tasks on a entity
		that or which resources it wants to use:
	</p>
    <ol>
        <li>Authenticate with a Time-Based One-Time Password (TOTP)</li>
        <li>Authenticate with a one-time-pad</li>
        <li>Authenticate with a ...</li>
    </ol>
	<p>
		Although this document aims to define common use cases for
		authentication,	an implementation or deployment MAY support any
		subset and MAY support additional commands not defined herein.
	</p>
    <p>
		<em>Note: The text that follows assumes that implementors have
		read and understood &xep0050;, password
		generation algorithms described in &rfc4226; and &rfc6238;</em>,
		and randomness requirements described in &rfc4086;,
		and know about one-time pads and perfect secrecy.
	</p>

    <section2 topic='Authenticate with a Time-Based One-Time Password (TOTP)' anchor='set-totp'>
        <p>
			Time-Based One-Time Password (TOTP) algorithm described in
			&rfc6238; is an extension of the HMAC-based
			One-Time Password (HOTP) algorithm defined in &rfc4226;,
			to support the time-based moving factor. In TOTP, time
			reference and a time step replaces the counter in the HOTP
			computation.
		</p>
		<example caption='Local Client (Prover) requests to authenticate with a TOTP to a Remote Client (Verifier)'><![CDATA[
<iq from='juliet@example.com/chamber'
    to='juliet@example.com/balcony'
    type='set'
    id='set-totp-1'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           action='execute'
           node='http://jabber.org/protocol/auth#set-totp'/>
</iq>
        ]]></example>
        <p>Unless an error occurs (see the
        <link url='#errors'>Error Handling</link> section below), the service
        SHOULD return the appropriate form.</p>

        <example caption='Remote Client (Verifier) replies with a form to set a TOTP'><![CDATA[
<iq from='juliet@example.com/balcony'
    to='juliet@example.com/chamber'
    type='result'
    id='set-totp-1'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           node='http://jabber.org/protocol/auth#set-totp'
           sessionid='set-totp:20131020T1320Z'
           status='executing'>
    <actions>
	  <complete />
    </actions>
    <x xmlns='jabber:x:data' type='form'>
      <title>Time-Based One-Time Password</title>
      <instructions>Send a Time-Based One-Time Password</instructions>
      <field type='text-single'
             var='totp'>
             label='TOTP'>
      </field>
    </x>
  </command>
</iq>
        ]]></example>
        <example caption='Local Client (Prover) submits the TOTP secret form to Remote Client (Verifier)'><![CDATA[
<iq from='juliet@example.com/chamber'
    to='juliet@example.com/balcony'
    type='set'
    id='set-totp-2'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           node='http://jabber.org/protocol/auth#set-totp'
           sessionid='set-status:20131020T1320Z'>
    <x xmlns='jabber:x:data' type='submit'>
      <field var='totp'>
        <value>218418045</value>
      </field>
    </x>
  </command>
</iq>
        ]]></example>
        <p>After receiving a correct secret, the Verifier informs Prover of completion.</p>
        <example caption='Remote Client (Verifier) informs Local Client (Prover) of completion'><![CDATA[
<iq from='juliet@example.com/balcony'
    to='juliet@example.com/chamber'
    type='result'
    id='set-totp-2'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           node='http://jabber.org/protocol/auth#set-totp'
           sessionid='set-status:20131020T1320Z'
           status='completed'/>
</iq>
        ]]></example>
    </section2>


        <section2 topic='Authenticate with a one-time pad' anchor='set-otpad'>
        <p>
			As described in &rfc4949; one-time pad is an encryption
			algorithm in which the key is a random sequence of symbols
			and each symbol is used for encryption only one time,
			i.e., used to encrypt only one plaintext symbol and thus
			produce only one ciphertext symbol and thus produce only one
			ciphertext symbol. A copy of the key is used similarly
			for decryption.
		</p>
		<example caption='Local Client (Prover) requests to authenticate with a one-time pad to a Remote Client (Verifier)'><![CDATA[
<iq from='juliet@example.com/chamber'
    to='juliet@example.com/balcony'
    type='set'
    id='set-otpad-1'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           action='execute'
           node='http://jabber.org/protocol/auth#set-otpad'/>
</iq>
        ]]></example>
        <p>Unless an error occurs (see the
        <link url='#errors'>Error Handling</link> section below), the service
        SHOULD return the appropriate form.</p>


        <example caption='Remote Client (Verifier) replies with a form to set a one-time pad'><![CDATA[
<iq from='juliet@example.com/balcony'
    to='juliet@example.com/chamber'
    type='result'
    id='set-otpad-1'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           node='http://jabber.org/protocol/auth#set-otpad'
           sessionid='set-totp:20131125T1022Z'
           status='executing'>
    <actions>
	  <complete />
    </actions>
    <x xmlns='jabber:x:data' type='form'>
      <title>One-time pad</title>
      <instructions>Send a one-time pad</instructions>
      <field type='text-single'
             var='otpad'>
             label='OTPAD'>
      </field>
    </x>
  </command>
</iq>
        ]]></example>
        <example caption='Local Client (Prover) submits the one-time pad form to Remote Client (Verifier)'><![CDATA[
<iq from='juliet@example.com/chamber'
    to='juliet@example.com/balcony'
    type='set'
    id='set-otpad-2'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           node='http://jabber.org/protocol/auth#set-otpad'
           sessionid='set-status:20131125T1022Z'>
    <x xmlns='jabber:x:data' type='submit'>
      <field var='totp'>
        <value>umeet321oop</value> <!-- TODO: VAIHDA -->
      </field>
    </x>
  </command>
</iq>
        ]]></example>
        <p>After receiving a one-time pad, the Verifier informs Prover of completion.</p>
        <example caption='Remote Client (Verifier) informs Local Client (Prover) of completion'><![CDATA[
<iq from='juliet@example.com/balcony'
    to='juliet@example.com/chamber'
    type='result'
    id='set-otpad-2'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           node='http://jabber.org/protocol/auth#set-otpad'
           sessionid='set-status:20131125T1022Z'
           status='completed'/>
</iq>
        ]]></example>
        </section2>

</section1>


<section1 topic='Error Handling' anchor='errors'>
    <p>
		Several error conditions are possible when a Prover sends a
		command	request to the Verifier, as defined in the following
		table. If one of these errors occurs, the Verifier entity MUST
		return an error stanza to the requesting Prover.
	</p>

    <table caption='Error Conditions'>
        <tr>
            <th>Condition</th>
            <th>Cause</th>
        </tr>
        <!--<tr>
            <td>&conflict;</td>
            <td>The command cannot be completed because of a data or system
            conflict (e.g., ...)</td>
            </tr>-->
        <tr>
            <td>&feature;</td>
            <td>The specific command is not supported (even though the
            ad-hoc commands protocol is).</td>
        </tr>
        <tr>
            <td>&forbidden;</td>
            <td>The requesting entity does not have sufficient
            privileges to perform the command.</td>
        </tr>
        <tr>
            <td>&unavailable;</td>
            <td>The ad-hoc commands protocol is not supported.</td>
        </tr>
        <tr>
            <td>&payment;</td>
            <td>If the user needs to provide payment in order to access
            to resources behind the Verifier (e.g., if the user is not
            in the customer database or the customer's account is not
            paid up).</td>
        </tr>
    </table>

    <p>For the syntax of these errors, see &xep0086;. Naturally, other
    errors may be returned as well.</p>
</section1>



<section1 topic='Implementation Notes' anchor='impl'>
	<p>
		Implementations of this protocol MAY introduce extra forms for
		commands and MAY use other secret key generation mechanisms than
		currently presented TOTP and one-time pad.
	</p>
	<p>
		There are several secure ways to transmit one-time pads or the
		shared secret that is used in TOTP from Verifier to the Prover.
		If both Verifier and Prover entities are running in one
		application inside one device, the shared secret can be
		generated and transmitted inside running implementation and
		be removed right after the usage.
	</p>
  </section1>

<!--<section1 topic='Accessibility Considerations' anchor='access'>
	<p>OPTIONAL.</p>
</section1>-->

<!--<section1 topic='Internationalization Considerations' anchor='i18n'>
	<p>OPTIONAL.</p>
</section1>-->

<section1 topic='Business Rules' anchor='rules'>
	<p>Presented authentication mechanism offers possibilities to
	execute at least the following access policies and different
	combinations of them, but their detailed descriptions and how
	policies are transmitted to the Verifier are out of scope of
	this document:</p>
	<ul>
		<li>
			The policy MAY allow only anonymous XMPP accounts, only
			non-anonymous XMPP accounts, or both, to be verified and/or
			to access certain resources.

			No additional access control mechanisms are necessarily
			needed.
		</li>
		<li>
			The policy MAY allow, e.g., only JIDs in certain domains,
			JIDs in a certain whitelist, JIDs in certain roster
			group(s), or JIDs with certain subscription types to be
			verified and/or to access certain resources. Additional
			mechanisms are required, e.g., to check wanted roster.
		</li>
	</ul>

	<p>In each case, the Verifier MAY check Prover's JID right after
	receiving the first Ad-Hoc command or after a succesful	verification
	process.</p>

	<p>If Prover's JID is not approved, the Verifier SHOULD
	reply with &forbidden; error message.</p>

	<p>After the a succesful verification the Verifier can, e.g.,</p>
	<ul>
				<li>start the wanted process,</li>
				<li>ask access rights from additional provision servers,
				e.g. with &xep0324;, and/or</li>
				<li>give access to the wanted resource.</li>
			</ul>
	</section1>
<section1 topic='Security Considerations' anchor='security'>
	<p>
		Mechanisms for determining when a command can be executed based
		on permissions or rights are considered specific to the
		application and/or implementation of <cite>XEP-0050</cite>, as
		defined in <cite>XEP-0050</cite>.

		In this application a command SHOULD be executed if and only
		if it comes from full user's JID that is already known to
		the Verifier. This decreases possibility to execute, e.g,
		relay attacks.

		Determining other permissions or rights are considered specific
		to access policies of systems, as presented in
		<link url='#rules'>Business Rules</link> section.
	</p>
	<p>
		Possibility of executing Denial-of-service (DoS) attacks against
		the Verifier can be reduced by ending processing of received
		messages coming from not authorized JIDs or containing incorrect
		secret as early as possible.
	</p>
	<p>
		Randomness requirements for security described in
		<cite>RFC 4086</cite> apply.
	</p>
	<p>
		When using TOTP, security considerations of
		<cite>RFC 6238</cite> apply.
	</p>
	<p>
		When using TOTP, HMAC-SHA-256 or HMAC-SHA-512 functions SHOULD
		be used instead of the HMAC-SHA-1 that has been specified for
		the HOTP computation in <cite>RFC 4226</cite>.
	</p>
	<p>
		When using TOTP, when an OTP is generated at the end of a
		time-step window, the receiving time most likely falls into the
		next time-step window. A validation system MUST set a policy
		for an acceptable OTP transmission delay window for validation.
		A larger acceptable delay window would expose a larger window
		for attacks, so as in <cite>RFC 6238</cite>, we RECOMMEND that
		at most one time step is allowed as the network delay.
	</p>
	<p>
		As described in <link url='#intro'>Introduction</link>, the
		user of the Prover XMPP client does not necessarily know
		anything about the Verifier. In addition to this, the user
		does not necessarily know what the device or the application
		will do after a succesful authentication. Notice that this
		problem relates to every closed source XMPP client
		implementations, thus implementations' code SHOULD be open
		source.
	</p>
	<p>
		When using one-time pads, to ensure one-time use, the copy of
		the key used for encryption MUST be destroyed after use, as
		is the copy used for decryption.
	</p>
	<p>
		When using one-time pads, commands containing pads that have
		incorrect pad length, SHOULD not be executed.
	</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'>

    <section2 topic='Protocol Namespaces' anchor='registrar-protocol'>
        <p>The XMPP Registrar includes 'http://jabber.org/protocol/auth'
        in its registry of protocol namespaces (see &NAMESPACES;).</p>
    </section2>

    <section2 topic='Field Standardization' anchor='registrar-formtype'>
        <p>&xep0068; defines a process for standardizing the fields used
        within Data Forms scoped by a particular namespace
        (see also &FORMTYPES;). The reserved fields for the
        'http://jabber.org/protocol/auth' namespace are specified
        below.</p>
        <code caption='Registry Submission'><![CDATA[
<form_type>
  <name>http://jabber.org/protocol/auth</name>
  <doc>XEP-XXXX</doc>
  <desc>Forms used for authenticating clients</desc>
  <field var='set-totp'
         type='text-single'
         label='Time-Based One-Time Password'/>
  <field var='set-otpad'
         type='text-single'
         label='One-time pad'/>
</form_type>
    ]]></code>
  </section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
	<p>
		Because the protocol defined here is a profile of
		<cite>XEP-0050</cite>, no schema definition is needed.
	</p>
</section1>
</xep>