Xtomp handbook

Auth sha1

STOMP protocol defined two heades for authentication in the CONNECT frame.

  • login - this is akin to username
  • passcode - this is typically a password

There are a few different mechanisms to login to a xtomp server.

No auth

If login, passcode, and secret are missing or commented out of the xtomp.conf file no passcode is required to login.

Connection can be made by simply sending


Username & Password

If the login and passcode configuratino items are uncommented these are treated as plain text and should be supplied verbartim in the CONNECT frame.


login      xtomp;
passcode   password;

Connect frame


Sha1 shared secret

To integrate with third party systems a shared secret can be setup so that other systems can generate logins valid for xtomp. The secret and secret_timout should be set, secret_timeout is a value in milliseconds.

secret           correcthorsebatterystaple;
secret_timout    60000;

The login format is

login = username + " " + unix_epoc() + " " + random()

N.B. the date is seconds since 1 jan 1970 the Unix epoc, not milliseconds. e.g. in JavaScript

unix_epoc() {
    return Math.floor(new Date().getTime() / 1000);

The passcode should be the sha1 hash of the login concatenated with the shared secret.

passcode = sha1_hash(login + secret);

Clearly, both login and passcode should be generated by a backend system, not a browser. The sha1 system is designed so that clients never know the secret. A server can be setup that validates a user using some existing method, (e.g. lookup user/pass in a db) and that server generates both the login and the passcode for xtomp clients.

On sha1 suitability

Sha1 has theoretically and practically for some usecases been broken.


Collision attacks

Sha1 is not a secure hashing algorithm anymore for message digests, it is possibleto make two documents with the same hash.
xtomp is paritally using sha1 for a digest and parially for an Hmac.
The ability to make a collision from new data from an existing hash has limitations. To use the "shattered" attack against xtomp, the attacker would have to obtain a sha hash from a valid login and then create a collision where the first part is different and the later part the same. The later part is unknonw to the attacker.

It is the author's understanding that this is not yet possible, even with 1000's of years of compute time, because larger block of data are needed that used in the xtomp auth protocol. It is not yet a practical attack against logins. Rotating the secret will mitigate this, and annoy whoever spent $100,000 on CPU/GPU time to compute the collision O͝O
Since xtomp is deisgned to work on low power devices, applying the highest grade security is not necessarily the best approach.

There is a compile time flag to use sha256 if sha1 is a concern.

Dictionary attacks

Dictionary attacks are feasible with either type of hashing.

If a weak secret is used a hacker who has access to one passcode (e.g. they login with their own username)

They could try

sha1hash(login + dictionary_next())

and if they ever find a match they have the discovered the shared secret and can log in as any user.

The complexity of the password is important, a plain text English word password is likley to be breakable very fast.

It is recommneded to create the secret with xtomp-auth/make-secret.sh providing a very long password, at least 12 characters. make-secret.sh will perform 1000 sha256 hashes on this password to harden it.

Thus, a dictionary attack would need to perform 1000 sha256 hashes and one sha1 hash for each iteration, xtomp can authenticate by performing only one sha1 hash.

A >12 random character password with hardening by make-password.sh should be practically impossible to perform a dictionary attack.

by teknopaul