Changes

Jump to navigation Jump to search
m
no edit summary
== Basic Notes ==

You must know there is:
# <iq/> - for command exchanges
# <message/> - to transfer messages ;)
# <presence/> - to exchange presence information

You can send these items only within a XML stream. Usually these items should also contain:
# to - where the item should be delivered (example: to='user2@server2.com' or to='service3.server4.org')
# id - as identification for this item (important for iq)
# type - in example get, set, result, error as the basic types in a iq

Sounds complicate? Nah, it is not ;) You will know when the time comes...

''In case an item does not contain a '''to''' the item will be delivered to user's own Jabber server!''

== Connecting to a server ==

Usually a Jabber server listens on port 5222 (TCP). As soon as you have connected and established a XML stream the server expects authentification as a user ([[#The log-in-process (aka authentication with a server or service)]]). Depending on server settings an option to create a new account is offered, too ([[#Creating a new account]]).

'''For a normal TCP socket the stream is established like this ([http://www.ietf.org/rfc/rfc3920.txt RFC 3920] Section 4.8.):'''

* A basic "session":
<pre>
C: <?xml version='1.0'?>
<stream:stream
to='example.com'
xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'
version='1.0'>
S: <?xml version='1.0'?>
<stream:stream
from='example.com'
id='someid'
xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'
version='1.0'>
... encryption, authentication, and resource binding ...
C: <message from='juliet@example.com'
to='romeo@example.net'
xml:lang='en'>
C: <body>Art thou not Romeo, and a Montague?</body>
C: </message>
S: <message from='romeo@example.net'
to='juliet@example.com'
xml:lang='en'>
S: <body>Neither, fair saint, if either thee dislike.</body>
S: </message>
C: </stream:stream>
S: </stream:stream>
</pre>

* A "session" gone bad:
<pre>
C: <?xml version='1.0'?>
<stream:stream
to='example.com'
xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'
version='1.0'>
S: <?xml version='1.0'?>
<stream:stream
from='example.com'
id='someid'
xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'
version='1.0'>
... encryption, authentication, and resource binding ...
C: <message xml:lang='en'>
<body>Bad XML, no closing body tag!
</message>
S: <stream:error>
<xml-not-well-formed
xmlns='urn:ietf:params:xml:ns:xmpp-streams'/>
</stream:error>
S: </stream:stream>
</pre>

=== Secure connections ===

* '''Note''', there are two layers of security to consider:
:# Client <-> Server (encryption of the TCP connection; TLS and SASL should be used)
:# Client <-> Client (data exchange between clients, in example an instant message; this should be done with [http://www.gnupg.org/ GnuPG])

== Creating a new account ==
Currently there is no official standard about how to create or delete an account. Anyway the existing servers still support the old way.

To create an account the client must not be authenticated.

# Request the required information.
# Register.

* Example for registering a new account:
<pre>
C: <iq type='get' id='reg1'>
<query xmlns='jabber:iq:register'/>
</iq>
S: <iq type='result' id='reg1'>
<query xmlns='jabber:iq:register'>
<username/>
<password/>
</query>
</iq>
C: <iq type='set' id='reg2'>
<query xmlns='jabber:iq:register'>
<username>hax0r</username>
<password>god</password>
</query>
</iq>
</pre>

The Server might respond with success...
<pre>
S: <iq type='result' id='reg2'>
<query xmlns='jabber:iq:register'/>
</iq>
</pre>

or with an error:
<pre>
S: <iq type='error' id='reg2'>
<query xmlns='jabber:iq:register'>
<username>edrin</username><password>pwd</password>
</query>
<error code='409'>
Username Not Available
</error>
</iq>
</pre>

* To delete an account the client must be authenticated - of course - and send:
<pre>
Sorry, I don't remember right now
</pre>

== The log-in-process (aka authentication with a server or service) ==
More details are described in [http://xmpp.org/extensions/xep-0078.html XEP-0078: Non-SASL Authentication].

Under some circumstances you might want to provide the password as a '''digest'''; see [http://xmpp.org/extensions/xep-0078.html XEP-0078: Non-SASL Authentication] for more details about this.

For authentication with Jabber servers and services the jabber:iq:auth namespace must be used:
# Client requests required fields from server.
# Client authentication.

* Example:
<pre>
C: <iq type='get' to='shakespeare.lit' id='auth1'>
<query xmlns='jabber:iq:auth'>
<username>bill</username>
</query>
</iq>

S: <iq type='result' id='auth1'>
<query xmlns='jabber:iq:auth'>
<username/>
<password/>
<digest/>
<resource/>
</query>
</iq>

C: <iq type='set' id='auth2'>
<query xmlns='jabber:iq:auth'>
<username>bill</username>
<password>Calli0pe</password>
<resource>office</resource>
</query>
</iq>
</pre>

On success server will respond with:
<pre>
S: <iq type='result' id='auth2'/>
</pre>

Server Informs Client of Failed Authentication (Incorrect Credentials):
<pre>
S: <iq type='error' id='auth2'>
<error code='401' type='auth'>
<not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
</pre>

Server Informs Client of Failed Authentication (Resource Conflict):
<pre>
S: <iq type='error' id='auth2'>
<error code='409' type='cancel'>
<conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
</pre>

Server Informs Client of Failed Authentication (Required Information Not Provided).
<pre>
S: <iq type='error' id='auth2'>
<error code='406' type='modify'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
</pre>

== Sending a message ==
The information provided here conforms to [http://www.ietf.org/rfc/rfc3921.txt RFC 3921] Section 4.

First lets take a look at the most complex situation.

* A message with all message features in use:
<pre>
C: <message
to='romeo@example.net'
from='juliet@example.com/balcony'
type='chat'
xml:lang='en'>
<subject>I implore you!</subject>
<subject xml:lang='cz'>&#x00DA;p&#x011B;nliv&#x011B; prosim!</subject>
<body>Wherefore art thou, Romeo?</body>
<body xml:lang='cz'>Pro&#x010D;e&#x017D; jsi ty, Romeo?</body>
<thread>e0ffe42b28561960c6b12b944a092794b9683a38</thread>
</message>
</pre>

Ok, here is the explaination;
# '''to''' - specifies the receiver - of course it should be required.
# '''from''' - the server routing your message should fill this for you; just leave away.
# '''type''' - specifies how romeo's client should handle the messag.
## ''normal'' or left away - a small message window should pop up.
## ''chat'' - a chat window should pop up.
## ''headline'' - message should be handled as a news feed - no response is expected.
## ''groupchat'' - for multi-user chat environment; see the according section in this guide.
## ''error'' - well, an error message; for details regarding stanza error syntax, refer to [http://www.ietf.org/rfc/rfc3920.txt RFC 3920].
# '''xml:lang''' - the default language of text in this message; this is not supported by any client I know of yet.
# '''subject''' - useful especially for type 'normal' and type 'headline'; not supported in combination with type 'chat' in most clients.
# '''body''' - yes, this is the message text ;)
# '''thread''' - a very optional thing, clients could have several message/chat sessions at the same time; usually this is not really required, many clients are even ignoring this thing but they should not of course!

* And here a very basic message:
<pre>
C: <message to='juliet@example.com'>
<subject>I love you!</subject>
<body>Meet at six? ;) Romeo</body>
</message>
</pre>
190

edits

Navigation menu