Mikeh at 02:39, 16 September 2006

2006-09-16T02:39:16Z

New page

=User Registration and Authorization=
 With all of Jabber's building blocks at
our fingertips, we can now take a look at two fundamental processes that
revolve around Jabber users:

* The registration, or creation, of Jabber user accounts
* The authentication of a Jabber user account, including the different
authentication methods These processes involve some of the things we
learned about in Chapter 5 and Chapter 6, so we'll take a look at them
again along the way:

* The XML stream header
* The <tt>jabber:iq:register</tt> namespace
* The <tt>jabber:iq:auth</tt> namespace At the end of this chapter, we
will create a small utility program with which we can register users on
a server. We can then use this utility program to create users as
required for further recipes in this book.

 

== XML Stream Flow ==
 User registration and user authorization are two
processes that take place at the start of an XML stream, immediately
following the XML stream header exchange. The Jabber server is designed
to check for and process any user registration request or
authentication request ''before'' anything else.

This makes sense, as outside of a session (a session is created for a
user when the authentication completes successfully), any other
element—a <tt><message/></tt> element, a
<tt><presence/></tt> element, or an <tt><iq/></tt> element
that doesn't contain an extension qualified by the
<tt>jabber:iq:register</tt> or <tt>jabber:iq:auth</tt> namespaces—is
invalid. So if any of these other elements are sent ''before''
authentication has taken place (that is, before a session has been
created for that connection), they are queued and processed ''after''
authentication.

Figure 7-1 shows the general flow within an XML stream, with regard to
where the registration and/or authentication steps happen.

[[image:jab_0701.png|XML stream flow showing registration and authentication|center|350 px]]
 -</code>

 
== User Registration ==
 User registration with a Jabber ''server''
specifically means the creation (or modification) of a user account for
the JSM component—the component that provides the basic IM services and
has a notion of users and user sessions. It takes place at the start of
a connection to a Jabber server, as does user authentication, as shown
in Figure 7-1.

Let's take a look at the XML fragments involved in a typical user
registration process. Example 7-1 shows the XML stream header exchange
and the IQ packets in the <tt>jabber:iq:register</tt> namespace.

''A typical user registration process'' First is the XML stream header
exchange:

<code>SEND: <?xml version='1.0'?> <stream:stream to='yak'
xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'>

RECV: <?xml version='1.0'?> <stream:stream
xmlns:stream='http://etherx.jabber.org/streams' id='3B2DB1A7'
xmlns='jabber:client' from='yak'>
</code>

Then the client sends a request to discover what information must be
passed to the Jabber server to register a new user:

<code>SEND: <iq type='get'> <query
xmlns='jabber:iq:register'/> </iq>

RECV: <iq type='result'> <query xmlns='jabber:iq:register'>
<instructions> Choose a username and password to register with
this server. </instructions> <name/> <email/>
<username/> <password/> </query> </iq>
</code>

The client does as asked and sends the required information, which
results in a successful new user registration:

<code>SEND: <iq type='set'> <query
xmlns='jabber:iq:register'> <username>leslie</username>
<password>secret</password>
<email>lel@plevna.com</email> <name>Leslie
Hawke</name> </query> </iq>

RECV: <iq type='result'/>
</code>

 

=== Configuration and Module Load Directives ===
 Lets start by reviewing
the relevant configuration in jabber.xml. User registration is a JSM
feature, and we find two places of interest in that component instance
definition. The first is in that instance's configuration, in the
section qualified by the <tt>jabber:config:jsm</tt> namespace:

<code><register notify="yes"> <instructions> Choose a
username and password to register with this server.
</instructions> <name/> <email/> </register>
</code>

The second is in that instance's connection method, showing the
''mod_register'' module being loaded. The module plays a major part in
handling the registration process, but there are others, too, as we will
see:

<code><load main="jsm"> <jsm>./jsm/jsm.so</jsm>
<mod_echo>./jsm/jsm.so</mod_echo>
<mod_roster>./jsm/jsm.so</mod_roster>
<mod_time>./jsm/jsm.so</mod_time>
<mod_vcard>./jsm/jsm.so</mod_vcard>
<mod_last>./jsm/jsm.so</mod_last>
<mod_version>./jsm/jsm.so</mod_version>
<mod_announce>./jsm/jsm.so</mod_announce>
<mod_agents>./jsm/jsm.so</mod_agents>
<mod_browse>./jsm/jsm.so</mod_browse>
<mod_admin>./jsm/jsm.so</mod_admin>
<mod_filter>./jsm/jsm.so</mod_filter>
<mod_offline>./jsm/jsm.so</mod_offline>
<mod_presence>./jsm/jsm.so</mod_presence>
<mod_auth_plain>./jsm/jsm.so</mod_auth_plain>
<mod_auth_digest>./jsm/jsm.so</mod_auth_digest>
<mod_auth_0k>./jsm/jsm.so</mod_auth_0k>
<mod_log>./jsm/jsm.so</mod_log>
<tt><mod_register>./jsm/jsm.so</mod_register></tt>
<mod_xml>./jsm/jsm.so</mod_xml> </load>
</code>

The <tt><register/></tt> configuration section looks familiar; the
contents are very similar to the IQ-result returned in response to the
IQ-get in the <tt>jabber:iq:register</tt> namespace in Example 7-1.
Indeed, to respond to an IQ-get, the ''mod_register'' module looks for
this <tt><register/></tt> section and formulates the contents into
a reply, making a simple modification as it goes: it appends tags for
the two fields <username/> and <password/> as these two are
''always'' required, regardless of configuration.

Removing the <tt><register/></tt> section from the configuration
effectively blocks the registration process and returns an appropriate
error to the user:

<code>SEND: <iq type='get'> <query
xmlns='jabber:iq:register'/> </iq>

RECV: <iq type='error'> <query xmlns='jabber:iq:register'/>
<error code='501'>Not Implemented</error> </iq>
</code>

Removing the reference to the ''mod_register'' module from the component
instance's connection method:

<code>
</code>

has the same effect.

More information on the configuration discussed here can be found in
Section 4.4.

 

=== Step by Step ===
 Taking the stream contents in Example 7-1 step by
step, what do we see?

 

==== The XML stream header exchange ====
 Although the XML declaration
that is sent immediately preceding the opening
<tt><stream:stream/></tt> root tag is optional, it's not a good
idea to leave it out. While the Jabber server currently does not enforce
its presence, future implementations may do so.<ref>That said, for the
time being, when you're testing against a Jabber server using telnet,
it's 20 less characters that you have to type every time you create a
new connection. </ref> The Jabber server will always send an XML
declaration in response. In both cases—in both streamed XML
documents—the encoding is assumed to be UTF-8.

For the most part, the rest of the <tt><stream:stream/></tt> root
tag is static. The namespace qualifying the stream content is
<tt>jabber:client</tt> (which is the only namespace acceptable when
making such an XML stream connection to the
<tt>c2s</tt>—Client-to-Server—component listening on port 5222), and
the namespace qualifying the stream itself is fixed at
http://etherx.jabber.org/streams.<ref>The name "etherx" comes from an
old library that implemented XML streams. </ref>

The only thing that is going to be dynamic is the <tt>to</tt> attribute,
which is used to specify the Jabber server name. Note that this is the
''logical'' name, the internal name, of the Jabber server. In our
example, we've already resolved the physical hostname, <tt>yak</tt>,
and connected to port 5222; the <tt>to</tt> attribute is to specify the
virtual Jabber host, which in many cases—including an out-of-the-box
jabber.xml configuration—has the same name as the physical host.

If our Jabber server has just a single virtual host, we can use an
<tt><alias/></tt> configuration tag in the <tt>c2s</tt> component
instance configuration, as described in Section 4.6.3, to remove the
requirement of specifying the <tt>to</tt> attribute.

Using:

<code><alias to='yak'/>
</code>

will set the ''default'' alias to <tt>yak</tt> and indeed override any
value specified in the <tt>to</tt> attribute.

 
==== "Required" fields ====
 The list of fields returned in the response
to the IQ-get in the <tt>jabber:iq:register</tt> namespace is actually
supposed to be a list of ''mandatory'' fields:

* <name/> * <email/> * <username/> * <password/>
However, with the current version of the Jabber server (1.4.1, which is
our reference version for this book), this is not the case.

The <tt><username/></tt> and <tt><password/></tt> fields
''are'' mandatory; not supplying them or supplying an invalid username
or password will result in an error:

<code>SEND: <iq type='set'> <query
xmlns='jabber:iq:register'> <username>leslie</username>
<email>lel@plevna.com</email> <name>Leslie
Hawke</name> </query> </iq>

RECV: <iq type='error'> <query xmlns='jabber:iq:register'>
<username>leslie</username>
<email>lel@plevna.com</email> <name>Leslie
Hawke</name> </query> <error code='406'>Not
Acceptable</error> </iq>
</code>

However, currently, failing to supply any of the other fields—the fields
that are specified in the <tt><register/></tt> section of the JSM
instance's configuration—will not result in an error. This may be fixed
in a later release. In any case, it's no great loss; the details are
simply stored in the user's spool file on the server, and right now
there's only one situation where this information is subsequently used:
in answering a browse request made to a user's JID, the server looks up
the <tt><name/></tt> tag from the registration data stored and
uses the value there in the browse response:

<code> SEND: <iq type='get' to='dj@yak'> <query
xmlns='jabber:iq:browse'/> </iq>

RECV: <iq type='result' from='dj@yak' to='sabine@yak/Work'>
<user <tt>name='DJ Adams'</tt> xmlns='jabber:iq:browse'
jid='dj@yak'/> </iq>
</code>

 

==== Set without get ====
 In many of the examples of IQ throughout the
book, we've seen a standard pattern: IQ-get <tt>-></tt> IQ-result
<tt>-></tt> IQ-set <tt>-></tt> IQ-result. This pattern isn't any
different here, but it's not essential. Bearing in mind that
registration field requirements aren't going to change that often, and
even if they do, the only ones that are enforced are
<tt><username/></tt> and <tt><password/></tt>, you can get
away with forgoing the IQ-get and cutting straight to the chase with an
IQ-set. This isn't a recommendation to do that, merely an observation,
as it's always good practice to ask first.

 

==== Still no connection ====
 After registering a new user, note that
there's still no session. Only after successful authorization (see
later in this chapter) is a session created. Although used in
authentication (and so implicitly in session creation), the value of the
<tt>id</tt> attribute in the XML stream header returned by the server
(which has the value <tt>3B2DB1A7</tt> in Example 7-1) is a
''connection'' ID, not a ''session'' ID.

So, what can we do at this stage? Well, one of two things: register
another user (yes!) or proceed to the authentication stage. Basically,
reaching the end of the registration process, we're back where we
started; a "raw" connection where only one of two sequences is valid:
the <tt>jabber:iq:register</tt> or <tt>jabber:iq:auth</tt> sequence.

 
==== Passwords ====
 You may be wondering about the plaintext nature of
the password sent in the registration process. Although the Jabber
server offers different types of password-based authentication, there's
a "bootstrap" process required to get the password to the server in the
first place. There's currently no way around the fact that the server
must at one time receive the password in all its plaintext glory. After
receiving it, there are authentication processes that don't use the
plaintext password again.

So if you're concerned about the security of this registration phase,
consider doing it over a secure (SSL) connection to the server.

We will look at the detail of the different authentication mechanisms
later in this chapter; however, it is worth noting here, in the context
of the registration process, that the JSM modules that implement the
mechanism are responsible for storing the password when it's received.
The ''mod_register'' module actually registers the user, but it is the
''mod_auth_plain'' and ''mod_auth_0k'' modules that actually store the
password when received.<ref>The ''mod_auth_digest'' module doesn't play
a password-storing role, just a password-checking one, as the mechanism
it provides uses the plaintext password that is stored by
''mod_auth_plain''. </ref>

Passwords are stored on another occasion—when a user wishes to
''change'' his password. This procedure is also covered by the
<tt>jabber:iq:register</tt> namespace, albeit in a different context—the
context of a ''session''. While a <tt>jabber:iq:register</tt>-based IQ
conversation ''outside'' the context of a session is for registering a
user, a similar conversation ''within'' the context of a session, that
is, after a user has authenticated, is used to change the user's
password and other registration details. Among other reasons, this is
for security: a session context implies the user has identified and
authenticated himself, and so has the authority to change the password.

Example 7-2 shows a typical IQ-set to change a password.

''Changing a password with jabber:iq:register''

<code>SEND: <iq type='set' id='pass_4' to='yak'> <query
xmlns='jabber:iq:register'>
<password>newsecret</password> </query> </iq>

RECV: <iq type='result' id='pass_4' from='yak' to='dj@yak/Work'/>
</code>

The <tt>to</tt> attribute is required here, to make sure the query is
handled by the server itself. We can also see evidence that the context
of this exchange is within a session in the value of the <tt>to</tt>
attribute on the IQ-result packet—the JID <tt>dj@yak/Work</tt> includes
a resource suffix, which implies a session (a resource must be specified
in the authentication process—see later in this chapter). And the
specification of a <tt><username/></tt> is not necessary, as the
server will stamp the incoming IQ-set anyway with the JID associated
with the user's session.

If you had made an IQ-get, as recommended earlier, before doing the
IQ-set to change the password, the result would have looked like this:

<code>RECV: <iq type='result' to='dj@yak/Work' id='pass_2'
from='yak'> <query xmlns='jabber:iq:register'>
<password/> <instructions> Choose a username and password to
register with this server. </instructions> <name/>
<email/>
<key>9a6957b7f69535274afa5c134fb4d916c5d5c20b</key>
<registered/> </query> </iq>
</code>

We see that, as in the registration IQ-get outside the session context,
the contents of the <tt><register/></tt> section of the JSM
instance's configuration have been inserted (the
<tt><instructions/></tt>, <tt><name/></tt>, and
<tt><email/></tt> tags). Additionally, we have a
<tt><key/></tt> tag, as a simple security token (described in
Section 6.2.11) and a <tt><registered/></tt> tag. The
<tt><key/></tt> is not actually checked in the current
implementation and therefore does not have to be supplied in the return
IQ-set packet. And the <tt><register/></tt> tag is merely a flag
telling us that the user is already registered.

Use of the <tt>jabber:iq:register</tt> namespace in conversation with
the JSM in a session context is not limited to changing passwords; you
can modify the rest of the registration details supplied when the user
was created—in this case, the <tt><name/></tt> and
<tt><email/></tt> information. In fact, with the current
implementation, because of the lack of checks, you can specify your own
fields in the <tt>jabber:iq:register</tt> IQ-set, in both contexts. But
don't do it; it's a habit that will probably be impossible to keep up in
later releases of the server.<ref>And no, you can't spoof someone else
by specifying the <tt><username/></tt> tag in a session context
<tt>jabber:iq:register</tt> IQ-set; it is ignored, and the correct JID
is taken from the <tt>from</tt> attribute stamp made as the packet hits
the server. </ref>

It almost goes without saying that because IQs in the
<tt>jabber:iq:register</tt> namespace are handled differently in a
session context, you can't register a new user once your session has
started; you must end it. To end it, the XML stream must be closed with
a <tt></stream:stream></tt>, and a new connection and stream must
then be created.

 

==== Reversing a user registration ====
 The opposite of registering a
user is ''unregistering'' a user. This is not the same as removing that
user altogether. When the <tt><remove/></tt> tag, described in
Section 6.2.11, is used in a <tt>jabber:iq:register</tt>-qualified
IQ-set during a user session, the user is ''unregistered''. That is,
all the information held in the user's spool file is removed. But the
spool file itself is not removed until the Jabber server is shut down.
This means that even if you <tt><remove/></tt> a user, the
username will still exist until the server is cycled, causing an error
if the same username is used in a new registration attempt:

<code>RECV: <iq type='error'> <query
xmlns='jabber:iq:register'> <username>dj</username>
<password>secret</password> </query> <error
code='409'>Username Not Available</error> </iq>
</code>

This may well be fixed in a later release of the Jabber server.

 

==== A note on error messages ====
 Various errors can occur during user
registration. They are, on the whole, fairly plain and easy to
understand. But because of the way the server has been written, you
might be surprised at ''what'' error message you receive in certain
circumstances.

Because the required fields <tt><username/></tt> and
<tt><password/></tt> are checked ''before'' looking to see whether
or not there is a <tt><register/></tt> section in the JSM instance
configuration, you will always receive a ''406 "Not Acceptable"''
instead of a ''501 "Not Implemented"'' if you don't supply those
fields, even if the registration mechanism has been turned off.

Likewise, if you specify a username that already exists, you will
receive a ''409 "Username Not Available"'' instead of a ''501 "Not
Implemented."''

Of course, if you do an IQ-get with the <tt>jabber:iq:register</tt>
namespace beforehand, you ''will'' receive the "correct" error—good
practice pays!

 

== User Authentication ==
 There are similarities between user
registration and user authentication:

* Authentication must take place outside of a session context (it
doesn't really makes sense inside a session context, anyway). It is
perfectly possible to perform a user registration step followed by a
user authentication step (for any user) in the same XML stream. * Any
packets sent before the authentication step (apart from user
registration packets) are queued until after the authentication step has
been completed. * The IQ-get in the <tt>jabber:iq:auth</tt> namespace is
not mandatory but is recommended (even more strongly than the
recommendation for the IQ-get in the <tt>jabber:iq:register</tt>
namespace). Example 7-3 shows a typical authentication process,
including the XML stream header exchange.

''A typical user authentication process'' Here the authentication
process immediately follows the initial XML stream header exchange:

<code>SEND: <?xml version='1.0'?> <stream:stream to='yak'
xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'>

RECV: <?xml version='1.0'?> <stream:stream
xmlns:stream='http://etherx.jabber.org/streams' id='1ED34A55'
xmlns='jabber:client' from='yak'>
</code>

We ask the server about the authentication methods available for our
specific user:

<code>SEND: <iq type='get'> <query xmlns='jabber:iq:auth'>
<username>dj</username> </query> </iq>

RECV: <iq type='result'> <query xmlns='jabber:iq:auth'>
<username>dj</username> <password/> <digest/>
<sequence>496</sequence> <token>3B2DEEC0</token>
<resource/> </query> </iq>
</code>

Because we're connecting here to the server with ''telnet'' and don't
have any digest utilities handy, we decide to use the simplest
authentication method and send our password in plaintext. The server
checks the credentials and gives us the thumbs-up.

<code>SEND: <iq type='set'> <query xmlns='jabber:iq:auth'>
<username>dj</username>
<password>secret</password>
<resource>laptop</resource> </query> </iq>

RECV: <iq type='result' id='pthsock_client_auth_ID'/>
</code>

At this stage, we have a session.<ref>The
<tt>pthsock_client_auth_ID</tt> value for the <tt>id</tt> attribute in
the IQ-result is placed by the JSM as it processes the IQ-set request,
when a value has not been specified. </ref>

 

=== Configuration and Module Load Directives ===
 The <tt>c2s</tt>
component contains a configuration directive related to the
authorization process:

<code><service id="c2s"> <load>
<pthsock_client>./pthsock/pthsock_client.so</pthsock_client>
</load> <pthcsock xmlns='jabber:config:pth-csock'> <alias
to='yak'/> <tt><authtime/></tt> ... </pthcsock>
</service>
</code>

This <tt><authtime/></tt> tag is used to set the time limit, in
seconds, within which authentication should be completed, starting to
measure at the time the connection was made. See Section 4.6.3 for more
details.

There is also an undocumented tag, <tt><auth/></tt>, which can be
specified in the JSM instance configuration (for example, after the
<tt><register/></tt> section) and with which you can specify an
external component that is to handle authentication in place of the
standard JSM modules (''mod_auth_*''). The JSM module load directives
specify the modules that handle authentication:

<code><load main="jsm"> <jsm>./jsm/jsm.so</jsm>
<mod_echo>./jsm/jsm.so</mod_echo>
<mod_roster>./jsm/jsm.so</mod_roster>
<mod_time>./jsm/jsm.so</mod_time>
<mod_vcard>./jsm/jsm.so</mod_vcard>
<mod_last>./jsm/jsm.so</mod_last>
<mod_version>./jsm/jsm.so</mod_version>
<mod_announce>./jsm/jsm.so</mod_announce>
<mod_agents>./jsm/jsm.so</mod_agents>
<mod_browse>./jsm/jsm.so</mod_browse>
<mod_admin>./jsm/jsm.so</mod_admin>
<mod_filter>./jsm/jsm.so</mod_filter>
<mod_offline>./jsm/jsm.so</mod_offline>
<mod_presence>./jsm/jsm.so</mod_presence>
<tt><mod_auth_plain>./jsm/jsm.so</mod_auth_plain>
<mod_auth_digest>./jsm/jsm.so</mod_auth_digest>
<mod_auth_0k>./jsm/jsm.so</mod_auth_0k></tt>
<mod_log>./jsm/jsm.so</mod_log>
<mod_register>./jsm/jsm.so</mod_register>
<mod_xml>./jsm/jsm.so</mod_xml> </load>
</code>

Each of these modules, ''mod_auth_plain'', ''mod_auth_digest'', and
''mod_auth_0k'' can play a role in the authentication process. As
mentioned in Section 4.4.4, they provide different authentication
methods, these methods being reflected in their names:

* ''mod_auth_plain'': plaintext * ''mod_auth_digest'': digest
* ''mod_auth_0k'': zero-knowledge You have a certain amount of flexibility
as administrator to determine what methods are made available on your
Jabber server. If you want to offer all three, do nothing. If you want
to offer only the ''zero-knowledge'' method, comment out or otherwise
remove the other two definitions from the list of module load
directives:

<code>
</code>

If you want to offer the ''digest'' method, you must include the module
load directives for both ''mod_auth_plain'' and ''mod_auth_digest'', as
the latter is merely an extension—a "parasite"—upon the former.

Let's look at each of these authentication methods in turn.

 
==== Plaintext authentication method ====
 The plaintext authentication
method works as you would expect and is the default lowest common
denominator method supplied with the Jabber server. It is provided by
the ''mod_auth_plain'' module.

; Method
: The password is transmitted in the XML stream, inside the
: <tt><password/></tt> tag in the <tt>jabber:iq:auth</tt> IQ-set
: packet, from the client to the server in plaintext, where it is
: compared to the password stored, also in plaintext, on the server. :
: When a password is changed, using a <tt>jabber:iq:register</tt> IQ-set
: as described earlier in this chapter, <tt>mod_auth_plain</tt> stores
: the password, as received, in the user's spool file.
; Advantages
: This method is by far the simplest to implement on the client side. It
: is also useful for debugging and testing purposes as it can be used in
: a connection "by hand" via telnet, not requiring any extra
: computation such as the digest and zero-knowledge methods do.
; Disadvantages
: It's insecure, on two levels. First, the password is transmitted in
: plaintext across the wire from client to server. The risk can be
: minimized by encrypting the whole connection using SSL. Second, the
: password is stored in plaintext on the server, which may be
: compromised.
 
==== Digest authentication method ====
 The module that provides the
digest authentication method, ''mod_auth_digest'', works in conjunction
with the plaintext module, ''mod_auth_plain''. It provides a way to
avoid having to send the plaintext password across the wire.

; Method
: The digest method is similar to the plaintext method, in that the
: password sent by the client is compared to the password stored on the
: server. However, in this case, the password is first encoded using a
: hashing algorithm. It is encoded by the client before being sent
: across the wire, and it is encoded by the server (having retrieved it
: in plaintext) before making the comparison. : The algorithm used is
: the NIST SHA-1 message digest algorithm.<ref>More information on SHA-1
: (Secure Hash Algorithm 1) can be obtained at
: http://www.itl.nist.gov/fipspubs/fip180-1.htm. </ref>: This algorithm
: takes arbitrary input and produces a fingerprint or "message digest"
: of it.<ref>There are different types of message digest that can be
: produced with this algorithm: binary, hexadecimal, and base64. The
: hexadecimal format is used here and elsewhere in Jabber. </ref>: A
: random string, shared between the client and the server, is appended
: to the password before being passed to the hashing algorithm. This
: random string is the connection ID—the value of the <tt>id</tt>
: attribute in the server's XML stream header response that we saw in
: Example 7-3:
<code>RECV: <?xml version='1.0'?> <stream:stream
xmlns:stream='http://etherx.jabber.org/streams' id='<tt>1ED34A55</tt>'
xmlns='jabber:client' from='yak'>
</code>
: which means, in the case where the password is "secret," the string
: that will be hashed is:
<code> secret1ED34A55</code>
: which is:
<code> 03ea09f012493415908d63dcb1f6dbdb9bfc09ba</code>
: The digested password is transmitted to the server inside the
: <tt><digest/></tt> tag. : ''mod_auth_digest'' is unlike the
: other two modules in that it doesn't take any responsibility for
: storing passwords; it leaves that to ''mod_auth_plain'', as the
: plaintext password must be rehashed with a new random suffix each
: time.
; Advantages
: No plaintext password is transmitted across the wire from client to
: server, and only a small amount of computation—a single SHA-1 hash
: process—is required.
; Disadvantages
: The password is still stored in plaintext on the server.
 
==== Zero-knowledge authentication method ====
 The zero-knowledge
authentication method is so-called as the server requires no knowledge
of the password in order to check the credentials. It makes use of the
same hashing algorithm used in the digest authentication method.

; Method
: Just as ''mod_auth_plain'' is responsible for storing the password (in
: plaintext) when a user is created or when the password is changed, so
: ''mod_auth_0k'' is responsible for storing ''its version'' of the
: password, actually, the information it needs (originally ''based'' on
: the password) to check the client's credentials in a zero-knowledge
: authentication process. : As we know from the user registration and
: password change processes, any new password is supplied to the server
: in plaintext. This is where a secure (SSL) connection is critical for
: complete security. While the ''mod_auth_plain'' module just stores
: that password as is, the ''mod_auth_0k'' module stores a sequenced
: hash of the password instead. : What does this mean? The server
: stores a value that is the password hashed with an arbitrary string
: token multiple (''N'') times, recursively. It doesn't store the
: password itself. It also remembers how many times it has been hashed
: (''N''). : Whenever a client wants to authenticate, the server sends
: the client the string token and the value of ''N''. The client, having
: obtained the password from the user, performs the same iterative
: hashing sequence that the server performed when it was originally
: given the password but performs the sequence ''N''-1 times. It passes
: the result of this sequence to the server, which does one more hash
: to go from ''N''-1 to ''N'', and compares what it gets with what it
: has stored. If they match, authentication is successful, and the
: server stores the ''N''-1 hash passed from the client and decrements
: ''N'', ready for next time. : The server sends the client the
: information it needs in two tags:
; <tt><sequence></tt>
: The value of ''N'' is sent in the <tt><sequence/></tt> tag.
; <tt><token></tt>
: The arbitrary string token to be hashed with the password is sent in
: the <tt><token/></tt> tag. : The ''N''-1 hash value is passed by
: the client to the server in the <tt><hash/></tt> tag. : By way
: of illustration, Example 7-4 shows a small Perl script that a Telnet
: user can use to make the necessary hashing computations when wishing
: to authenticate with a Jabber server using the zero-knowledge method.
''A script implementing the client-side zero-knowledge process''

<code>#!/usr/bin/perl -w

use strict; use Digest::SHA1 qw(sha1_hex); use Getopt::Std;

our($opt_p, $opt_t, $opt_s); getopt('pts');

unless ($opt_p and $opt_t and $opt_s) { print "Usage: $0 -p
<password> -t <token> -s <sequence>\n"; exit;
}

# Initial hash of password
my $hash = sha1_hex($opt_p);

# Sequence 0: hash of hashed-password and token
$hash = sha1_hex($hash.$opt_t);

# Repeat N-1 times
$hash = sha1_hex($hash) while $opt_s--;

print "$hash\n";
</code>
: To use the script, pass the data via the parameters, using the values
: obtained from the response to the initial IQ-get. The value that the
: script produces for the value to send in the <tt><hash/></tt>
: tag, like this: :
<code>$ <tt>./0k</tt> Usage: 0k -p <password> -t <token> -s
<sequence>
</code>
:
<code>$ <tt>./0k -p secret -t ABCDE -s 400</tt>
01945b9b2c3207c4cce5dc99e50605779f570077 $

</code>

; Advantages
: No password is stored on the server. No (plaintext) password is
: transmitted from client to server.
; Disadvantages
: This method is slightly more compute-intensive than the other methods.
: There is still a security weak spot in the procedure, when the
: password is set or reset, as it must be passed in plaintext. A reset
: is required when ''N'' reaches 0, which is another disadvantage—a
: password can be used only ''N'' times before a plaintext reset.
 
=== Choosing the Authentication Method ===
 Now that we know a little bit
about the authentication methods, let's jump back to the initial IQ-get
query in Example 7-3:

<code>SEND: <iq type='get'> <query xmlns='jabber:iq:auth'>
<username>dj</username> </query> </iq>

RECV: <iq type='result'> <query xmlns='jabber:iq:auth'>
<username>dj</username> <password/> <digest/>
<sequence>496</sequence> <token>3B2DEEC0</token>
<resource/> </query> </iq>
</code>

What we're actually seeing here is the result of the authentication
modules announcing their readiness to authenticate the user
<tt>dj</tt>. The query is passed to each of the modules.
''mod_auth_plain'' announces its readiness by inserting the
<tt><password/></tt> flag, ''mod_auth_digest'' does the same with
the <tt><digest/></tt> flag, and ''mod_auth_0k'' inserts the
<tt><sequence/></tt> and <tt><token/></tt> tags and values,
which is what the client will need if it wishes to authenticate using
the zero-knowledge method. The <tt><resource/></tt> tag, which is
required in any authentication, is finally added before the result is
returned.

This way, the IQ-result can convey which authentication methods are
available; if the ''mod_auth_plain'' and ''mod_auth_digest'' modules
were to be commented out in the module load directive list, as we saw
earlier, then the IQ-result would look like this without the
<tt><password/></tt> or <tt><digest/></tt> tags:

<code>RECV: <iq type='result'> <query
xmlns='jabber:iq:auth'> <username>dj</username>
<sequence>496</sequence> <token>3B2DEEC0</token>
<resource/> </query> </iq>
</code>

{{Note|At the beginning of this section, we strongly recommended using
the IQ-get in the <tt>jabber:iq:auth</tt> namespace, before proceeding
with the IQ-set. This was primarily to be able to check what
authentication methods were supported. However, as you can see here, it
is in fact ''essential'' in the case of the zero-knowledge
authentication method, because without the <tt><sequence/></tt>
and <tt><token/></tt> information, we cannot begin our hashing
sequence.

</code>

 
=== Password Errors and Retries ===
 If you don't supply all the required
parameters, you are notified with a 406 ''"Not Acceptable"'' error:

<code>SEND: <iq type='set'> <query xmlns='jabber:iq:auth'>
<username>dj</username>
<digest>03ea09f012493415908d63dcb1f6dbdb9bfc09ba</digest>
</query> </iq>

RECV: <iq type='result' id='pthsock_client_auth_ID'> <query
xmlns='jabber:iq:auth'> <username>dj</username>
<digest>03ea09f012493415908d63dcb1f6dbdb9bfc09ba</digest>
</query> <error code='406'>Not Acceptable</error>
</iq>
</code>

In this case, no <tt><resource/></tt> value was supplied. The
<tt><resource/></tt> value is required, as it is the key part of
the JID that is used to distinguish between multiple connections as the
same user on the same Jabber server.

If you get the password wrong, you receive a 401 ''"Not Authorized"''
error. There is currently no limit on the number of times an
authorization attempt can be made, but the <tt><karma/></tt>
limits for the <tt>c2s</tt> connections (see Chapter 5) may slow the
attempts down.

 

== User Registration Script ==
 Currently, the Jabber technology has no
concept of ''anonymous'' users—users who can connect to the server with
no previous registration requirement. Until this is possible, we have
to make do with creating specific users for specific scenarios.

To this end, it would be useful to be able to run a quick script to
register a new user, rather than grab an existing client, start it up,
and go through the process of registering a new user with the Jabber
server, with whatever window navigation and mouse clicking that might
entail. All the script must do is interact with the Jabber server in
the context of the <tt>jabber:iq:register</tt> namespace, specifically,
pre-session. It must be able to make a registration ''inquiry'' by
sending an IQ-get and returning the fields listed in the result and to
make a registration ''attempt'', when supplied with values for the
registration fields.

We should be able to invoke our script, ''reguser'', in one of two
ways. The first, specifying merely a hostname (and optional port, which
will default to 5222 if not specified), implies a registration
''inquiry'', that we wish to make an inquiry of the Jabber server as to
(a) whether registration is possible and (b) if so, what fields are
required. The second way, specifying not only the host and optional port
but also a list of field name and value pairs, implies a registration
''attempt''. Example 7-5 shows both these ways in action.

''Uses of the reguser script''

<code> $ <tt>./reguser yak:5222</tt> [Enquiry] Fields: username
password email name

$ <tt>./reguser yak username=joseph password=spinach 'name=Joseph Adams'
email=joseph@yak</tt> [Attempt] (joseph) Successful registration

$ <tt>./reguser yak username=dj password=secret 'name=DJ Adams'
email=dj@yak</tt> [Attempt] (dj) Error: 409 (Username Not Available)</code>
As it's our first substantial script, let's take it step by step. It's
written in Perl and uses the <tt>Net::Jabber</tt> module:

<code>#!/usr/bin/perl

use strict; use Net::Jabber 1.0022 qw(Client);

use constant NS_REGISTER => 'jabber:iq:register';

unless (@ARGV) { print usage(); exit;
}
</code>

We start out with some basic start-of-script housekeeping: delaring our
usage of <tt>Net::Jabber</tt>, setting a constant for the
<tt>jabber:iq:register</tt> namespace, and handling the case of being
"wrongly" invoked by giving some help text from the <tt>usage()</tt>
subroutine. The specification of <tt>Client</tt> in the line:

<code>use Net::Jabber 1.0022 qw(Client);
</code>

means that the connection is going to be client-based; in other words,
the namespace that will be used to qualify the XML stream header that
<tt>Net::Jabber</tt> will produce is <tt>jabber:client</tt>.

The <tt>Net::Jabber</tt> module has changed as it has matured over the
recent versions (1.0020, 1.0021, and 1.0022), and these changes do
sometimes affect how the scripts that use <tt>Net::Jabber</tt> should be
written. So we explicitly specify in the <tt>use</tt> statement which
version of <tt>Net::Jabber</tt> we require, to avoid confusion.

<code>my ($host, $port) = split(":", shift @ARGV); $port ||= 5222;

my $c = Net::Jabber::Client->new();

defined($c->Connect( hostname => $host, port => $port, ))
or die "Cannot reach Jabber server at $host:$port\n";

my ($iq, $query, $result);
</code>

We parse the hostname and port, defaulting the latter to 5222 if it
wasn't specified. Then we create a new instance of the
<tt>Net::Jabber::Client</tt> object. The <tt>Net::Jabber</tt> family of
modules presents its collective functions in an object-oriented way. The
scalar <tt>$c</tt> represents the "client" mechanism with which we
connect to the Jabber server.

With the <tt>Connect()</tt> method, we make a connection to the Jabber
server; the namespace of the XML stream for this connection, sent to
the Jabber server in the stream header, is <tt>jabber:client</tt>.

<code># Registration attempt or inquiry?

if (scalar @ARGV) {

# Attempt: Send <iq type='set'> <query
# xmlns='jabber:iq:register'> <username>...</username>
# <password>...</password> ... </query> </iq>

print "[Attempt] ";

$iq = Net::Jabber::IQ->new(); $iq->SetType('set'); $query =
$iq->NewQuery(NS_REGISTER);
</code>

We work out what we have to do by looking to see if any extra parameters
beyond the hostname and port were specified. If there were, we need to
build an IQ-set in the <tt>jabber:iq:register</tt> namespace to make a
registration attempt.

The <tt>Net::Jabber::IQ</tt> module represents the IQ model and provides
methods to manage IQ packets. With the <tt>new()</tt> constructor, we
create a new, empty IQ packet in <tt>$iq</tt>, and set its
<tt>type</tt> attribute to <tt>set</tt>.

As we know, the <tt><query/></tt> part of an IQ packet is
contained ''within'' the <tt><iq/></tt> tag. The
<tt>NewQuery()</tt> method, called on an IQ packet, creates a
<tt><query/></tt> tag as a child of that IQ packet and delivers us
a handle on that <tt><query/></tt> tag—which we store in
<tt>$query</tt>—so that we can manipulate it independently of the IQ
packet that wraps around it. The <tt>jabber:iq:register</tt> namespace
value is passed as a parameter to the <tt>NewQuery()</tt> call to set
the correct <tt>xmlns</tt> namespace attribute.

Figure 7-2 shows what the packet looks like at this stage and how the
scalar object references <tt>$iq</tt> and <tt>$query</tt> relate to it.

[[image:jab_0702.png|An IQ packet under construction by Net::Jabber::IQ|center|350 px]]
 </code> In our <tt>foreach</tt>
loop, we run through the list of parameters, in the form
''fieldname=value'', and call a <tt>Set</tt> method on the
<tt>$query</tt> object (the <tt><query/></tt> packet) to add
child tags:

<code> foreach my $arg (@ARGV) { my ($field, $value) = split('=",
$arg); print "($value) " if $field eq 'username'; eval
'$query->Set'.ucfirst($field).'($value)';
}

$result = $c->SendAndReceiveWithID($iq);
</code>

<tt>Net::Jabber::Query</tt> provides a number of <tt>SetXXXX</tt>
methods that are available according to namespace. These "set" methods
available for the <tt>jabber:iq:register</tt> namespace are plentiful
and include <tt>SetName</tt>, <tt>SetEmail</tt>, <tt>SetPhone</tt>, and
so on. Each method will create a child tag named after the method (e.g.,
<tt>SetName</tt> will create a <tt><name/></tt> tag, and
<tt>SetPhone</tt> will create a <tt><phone/></tt> tag) and insert
the value passed to the method into the tag.

For example:

<code>$query->SetName('DJ Adams');
</code>

will insert (or amend) a tag in the <tt><query/></tt> thus:

<code><iq type='set'> <query xmlns='jabber:iq:register'>
<tt><name>DJ Adams</name></tt> </query> </iq>
</code>

We use <tt>eval</tt> to allow us to make our <tt>SetXXXX</tt> method
calls dynamically, according to each field name specified. The
<tt>ucfirst()</tt> function is used to change the first character of the
field name to uppercase, to suit the <tt>SetXXXX</tt> method naming
conventions.

Once we've added all the fields, we send the complete packet
(<tt>$iq</tt>) to the server using the <tt>SendAndReceiveWithID()</tt>
method on the connection (<tt>$c</tt>) object. This method is extremely
powerful and does many things for us. It keeps the process of writing
small scripts like this very simple. It adds a unique <tt>id</tt>
attribute to the <tt><iq/></tt> packet, transmits the packet over
the XML stream, ''and waits for a response''.

"Hey, what about the event model that we read about?" you might ask. Of
course, <tt>Net::Jabber</tt> supports an event-model programming style,
but for now we can get away with keeping our code "procedural" (and
short) using this high-level method that does everything we want. After
all, in any one execution of the script, we wish to send only one packet
to the Jabber server and receive one back. Nothing more complicated than
that.

Recipes in later chapters will demonstrate the event model.

The response is stored in <tt>$result</tt> and is itself an IQ packet,
as we expect. So <tt>$result</tt> is a handle on a
<tt>Net::Jabber::IQ</tt> object that we can now manipulate:

<code> # Success if ($result->GetType() eq 'result') { print
"Successful registration\n";
}

# Failure
else { print "Error: ", $result->GetErrorCode(), " (",
$result->GetError(), ")\n";
}

}
</code>

We check the type of the IQ returned from the server. If it's a
<tt>result</tt>:

<code>RECV: <iq type='result' id='1'> <query
xmlns='jabber:iq:register'/> </iq>
</code>

then great—the registration was successful. Otherwise, we can grab the
error code and description from the <tt><error/></tt> element:

<code>RECV: <iq type='error'> <query
xmlns='jabber:iq:register'> <username>dj</username>
<password>secret</password> </query> <tt><error
code='409'>Username Not Available</error></tt> </iq>
</code>

using the <tt>GetError()</tt> and <tt>GetErrorCode()</tt> methods on the
IQ object.

We go through a similar process if there are no further parameters
following the <tt>host[:port]</tt> specification:

<code>else {

# Inquiry: Send <iq type='get'><query
# xmlns='jabber:iq:register'/></iq>

print "[Inquiry] ";

$iq = Net::Jabber::IQ->new(); $iq->SetType('get'); $query =
$iq->NewQuery(NS_REGISTER);

$result = $c->SendAndReceiveWithID($iq);

</code>

The only difference here is that we set the IQ type to <tt>get</tt>, not
<tt>set</tt>, and we don't insert any tags into the <tt>$query</tt>
object, before sending the packet off and waiting for a response:

If we receive a <tt>result</tt> type, like this:

<code>RECV: <iq type='result'> <query
xmlns='jabber:iq:register'> <instructions> Choose a username
and password to register with this server. </instructions>
<name/> <email/> <username/> <password/>
</query> </iq>
</code>

then we need to extract the fields listed in the <tt><query/></tt>
tag and return them to the user.

<code> # Success if ($result->GetType() eq 'result') { $query =
$result->GetQuery();

my %contents = $query->GetRegister(); delete
$contents{'instructions'}; print "Fields: ", join(', ', keys
%contents), "\n";
}

</code>

While the <tt>NewQuery()</tt> method creates a new
<tt><query/></tt> tag inside an IQ object, the <tt>GetQuery()</tt>
method retrieves an existing one, in the form of a
<tt>Net::Jabber::Query</tt> object whose handle we store in
<tt>$query</tt>. We can call the <tt>GetRegister()</tt> method on this
query object, which returns a hash of the contents:

<code>( 'instructions' => 'Choose a username and password ...',
'name' => undef, 'email' => undef, 'username'
=> undef, 'password' => undef )
</code>

And, after removing the "instructions," we can display them as the
result.

When an error is returned in response to the IQ-get (perhaps no
registrations are allowed), we display the error in the same way as
before:

<code> # Failure else { $query = $result->GetQuery(); print "Error:
", $result->GetErrorCode(), " (", $result->GetError(), ")\n";
}

}
</code>

When we've finished, we close the connection and exit. Here we also have
the <tt>usage()</tt> subroutine defined:

<code>$c->Disconnect;

exit;

sub usage {

<<EOF Usage: Enquiry: reguser host[:port] Attempt: reguser
host[:port] field1=value1 [fieldN = valueN] ... EOF

}
</code>

 

=== Using the Script ===
 The script is very basic, but it gets the job
done. It is suitable for calling from another script, for mass user
generation, although you may wish to modify it so that a connection is
not created and destroyed for every username that needs to be
registered.<ref>Otherwise, you may experience socket rating problems.
See Section 4.13.1 in Chapter 4 for details. </ref>

It also illustrates how simple a Jabber client can be. In this case, the
<tt>Net::Jabber</tt> libraries mask the bulk of the effort (socket
connection, XML stream negotiation, XML fragment traffic management,
and so on). We'll be making use of this script to create users for our
recipes later on in the book.

←Older revision		Revision as of 14:22, 18 September 2009
Line 1:		Line 1:
		+	{{Content Programming Jabber}}
	=User Registration and Authorization=		=User Registration and Authorization=
	<br>With all of Jabber's building blocks at		<br>With all of Jabber's building blocks at

JabChapter 7 - Revision history

Uncopy: content navi added

Mikeh at 02:39, 16 September 2006