FAQ
Traditionally web services used passwords to check if a user is allowed to login. However, as history shows, this system is fundamentally flawed. Users forget passwords; use very weak ones (the most-used passwords are passwort, 123456 and similar ones), which are easy to guess; re-use passwords on multiple sites; etc. When breaches occur these passwords are often revealed and many users get harmed as their weak passwords allowed hackers to login into mail, payment and banking accounts.
Fortunately two-factor authentication (2FA) can help you here. In addition to a password (something you know) you have to prove you own something only you can have, which is in most cases you smartphone. As a result hackers would need to have both access to your phone and know your password to be able to login. Using Threema for this purpose is both easy and secure.
More resources:
I'd like to use the 2FA with Threema for my own forum, but I don't use XenForo. Will there be any ports for other forum software?
Currently there are no plans to do so. However it is certainly possible and any developer can do so as the PHP SDK and this add-on are both open-source.
Basically it would be very good to have already some support for two-factor-authentication implemented in the forum software. (see next two questions)
The main reason was that XenForo v1.5 added two-factor-authentication as native feature of XenForo and allowed it to be expanded by add-ons. Many users requested SMS 2FA. However SMS is insecure (see "Why not just SMS?") and the Threema Gateway is just perfectly suitable for such a task as sending one time passwords to users.
The reason is that XenForo 1.5 introduced two-factor-authentication and the 2FA modes of this add-on work as a 2FA provider internally. As the add-on depends on this feature, it does not work with earlier versions of XenForo.
This has several reasons:
- WhatsApp is not privacy aware.
- WhatsApp does not have an easy-to-use, secure API which allows sending or receiving of such messages.
The advantages of Threema (Gateway) are:
- The messages can be sent end-to-end encrypted.
- It is cheap. (cheaper than SMS)
- It works internationally without problems.
- Threema users can stay anonymous without having to reveal their phone number.
- The messages are all sent through servers in Switzerland.
- Threema allows you to accept/decline messages, which is used in the "Fast login" method.
Of course the secure-messaging app Threema itself has many other advantages and on the official Gateway website some other advantages of the Threema Gateway are listed.
More information about Threema and Threema's user base can be found in the press paper (German version).
These two messengers also have no easy and secure API for sending messages to users. Telegram uses some self-built cryptographic algorithm for end-to-end-encrypted messages, which cannot be considered secure.
In case you ask for a messenger which actually has this, I'm interesed in hearing about it. However I currently have no plan to implement this for other messengers. You may do it by yourself and get inspired by this addon or even reuse some code (it's open-source).
SMS is insecure, especially for 2FA. Also the NIST advocates not to use SMS for 2FA. The Threema Gateway is just perfectly suitable for such tasks as sending OTP (one time passwords) to users. Additionally sending messages with the Threema Gateway is cheaper than sending SMS messages and it works internationally without any problems.
Yes, it is as it works completely offline. That's also the reason why it is shown above the Threema 2FA methods when the user goes to the 2FA settings.
However 2FA verification with Threema is nearly as secure as the TOTP verification (that's how the app verification is called), but it may be much more convenient and the user can choose from several 2FA methods. Additionally it is always good to have a second 2FA method activated as a backup.
Sure, but as explained above for XenForo it was more easy to implement than (potentially) other boards as they already have a 2FA system build-in.
If your aim is however not to use Threema for 2FA, but as something else, it may of course be possible to implement it in an easier way. In any case however it all depends on the exact case and on the time I have left for doing it.
As always with FLOSS software you can just do it by yourself and reuse some code from this project.
We will see. Currently I assume some things have to be modified, but this really depends on what is exactly chnaged in XenForo v2.
I am using their PHP library, licensed under the MIT license as stated in my LICENSE file in the repo, but apart from that the whole add-on was created by rugk. That's also why I ask for donations, because I do not got or get any money from Threema.
This is a nice idea and from a technical point of view certainly possible. All incoming messages are already saved in the database and sending messages is as simple as calling a method in the Sender action handler.
However a web interface implementation is a huge tasks, if it is considered to be a complete implementation. This feature request is tracked in issue #6 and if you want to help, please have a look there.
There are three possible 2FA modes. Whether they are available depends on your server admin.
Generally all modes which are listed first in the 2FA mode overview are more secure and these which are listed last are less secure. In general the ones listed below however provide more convenience.
You can just try them out or read the detailed and somewhat technical description of the different modes to get more details of how they work and what advantages and disadvantages they have.
If you lose access to your Threema ID you cannot use the 2FA method anymore, which used this ID. You may use a backup code of XenForo or another 2FA method if set one up.
Remember you can choose a different Threema IDs for each 2FA mode. Thus you can use one Threema ID even when you loose access to another one.
Always remember to create a backup of your Threema ID to prevent such issues. If you have a backup you can just restore it and receive and send messages again.
Yes. At first if the modes "reversed" or "fast login" are available, which require the server admin to receive messages, you can be sure that end-to-end encryption is used as this is a requirement by Threema.
If only the "conventional" mode is available, you can see it in the description of all available modes as the last sentence of this mode clearly states when E2E encryption is used:
The message is sent end-to-end encrypted.
If this sentence is not shown there, no end-to-end encryption is used.
Note that bad server admins could of course manipulate this system, but if your server admin does this, you might rethink your membership in the forum again.
See Setup.
At first note that this is not needed as the database is used by default to store the public keys of Threema IDs. However when you think you want to use a PHP keystore follow this steps:
- Create a php file in
library/ThreemaGateway, e.g.library/ThreemaGateway/mykeystore.php. - Make sure it is writable. If not e.g. use
chmodto make it writable. You will get an error later if it is not writable.
Also make sure to make it inaccessible for other users on the system, so only the process running PHP with XenForo can read (& write) to it. - Go to the Threema Gateway settings in the ACP and select "Use PHP Keystore (not recommend)".
- Enter the filename (and extension) of your PHP keystore, e.g.
mykeystore.php. - Save the changes.
When you do so, please be aware that every update of this addon overwrites these changes and therefore you have to do them again when updating this add-on.
-
Open the file
library/ThreemaGateway/Handler/Settings.php. There you see the following code snippet:/** * @var string $gatewayId Your own Threema Gateway ID */ private $gatewayId = ''; /** * @var string $gatewaySecret Your own Threema Gateway secret */ private $gatewaySecret = ''; /** * @var string $privateKey Your own private key */ private $privateKey = '';
-
Replace the values in such a way that they e.g. look like this:
/** * @var string $gatewayId Your own Threema Gateway ID */ private $gatewayId = '*MYAPIID'; /** * @var string $gatewaySecret Your own Threema Gateway secret */ private $gatewaySecret = 'ab2defghijKlmnOp'; /** * @var string $privateKey Your own private key */ private $privateKey = 'private:94af3260fa2a19adc8e82e82be598be15bc6ad6f47c8ee303cb185ef860e16d2';
Of course, you do not have to enter all data there. You can also leave some data in the ACP.
-
Now you can remove all data in the ACP options (just set them to a blank field) and if everything is correct you will still see your remaining credits. If not, there will be an error.
Note that the health check displays an error for the edited file afterwards. If you do not want this you can calculate the checksum (MD5) of the changed file and replace it in library/ThreemaGateway/Listener/Data/FileSums.php.
The debug log saves information about the message processing of the Gateway Callback in a text file on your server. This means when you have errors with receiving messages you can use the debug mode log to investigate this.
When enabled also some (less detailed) status messages are shown when the Threema Gateway Callback is accessed. This makes it possible to "emulate" message sending and get some useful results. This is mostly only useful for development.
The log does not help you in any way with debugging sending messages or so. (except that you may potentially see when you get incoming receive acknowledgements)
As the logging mode of this add-on saves secret information (plain-text message content and meta-data such as sender) into a log file, it is recommend to only enable this temporary for debugging reasons. To make it harder to accidentially enable it or leave it enabled, it is required that the XenForo debug mode is enabled. Aditionally when disabling the option the log file should automatically be deleted.
To enable logging, first activate XenForo's debug mode. Afterwards go intop the ACP options and at the bottom you will find some new settings including one to log all messages into a text file.
Important: Please make sure that the text file cannot be accessed by anyone else than yourself! Especially prevent it from being accessed from the web, i.e. place it outside of your web root if possible.
I get the server error "Message cannot be processed: [Threema\MsgApi\Exceptions\UnsupportedMessageTypeException]". What does it mean?
This means that someone tried to send you a message, which is not yet supported by the Threema Gateway. This could e.g. include video messages, which are a different type of messages than e.g. file messages and are not yet supported by the Threema Gateway. What message types are supported depends on the Threema MSGAPI PHP-SDK.
You can savely ignore this error messages. If you want to get more information about it (e.g. who is sending the message) you can use the debug logging.
Note that when this exception occurs usually two errors will be logged, where the first one is the original one returned by the Threema PHP-SDK (that's the error with no text) and the second one is a more user-friendly message.
I get the server error "Message […] has already been received and is already saved. This may indicate a replay attack." or "Message could not be saved: [Zend_Db_Statement_Mysqli_Exception] Mysqli statement execute error : Duplicate entry '[…]' for key 'PRIMARY'". What does it mean?
This indicates that something or someone tried to send you a message to your Threema Callback, which you have already received. The message ID is included in the error in the part which I replaced with […] here.
To debug the reason for this you may enable debug logging. As this Exception is thrown as a part of the mechanism to prevent replay attacks (see question below), it could of course happened that someone tried to carry out such an attack. In this case I'd suggest you to investigate the case and change your callback secret (in the ACP).
If you get the MySQLi exception, you will always get two logged exceptions for each issue as the original exception is also logged, so you can get more details about the issue.
A replay attack is an attack where a message (e.g. a 2FA login message) is send to your XenForo instance again although it has already been received before. All included 2FA modes however have replay attack protection built-in (which is technically assured through the different secrets/codes they rely on). However as this add-on also provides an API for other add-ons, it might be useful to enable this setting if another application cannot ensure this.
When the option is disabled "only" the "defaults" for this protection are applied. The server stores all message IDs for at least 14 days (or whatever number you set in "Reject old messages when receiving") and afterwards may delete them if they are not needed anymore. When a message is received it can never have the same message ID as a previously saved one, which prevents that such already sent messages can be received.
14 days are the default limit as the Threema server stores messages at most for 14 days and deletes them afterwards.
If such an attack happens, you should get one of the messages outlined in the question above.
The Gateway server could theoretically act maliciously and resent these messages after 14 days and they would not be rejected by default, but this assumes a hacked or misbehaving Threema Gateway server, which is usually not your threat model.
When the option is enabled the message IDs are never deleted, which makes sure all messages can always be verified no matter when they were sent. Naturally this stores some more (meta) data in your database and may slow down your queries/message receiving processing a bit.
So the reason for not using such a hard replay attack protection is that we can minimize the amount of meta data stored on the server and delete useless messages.
Note that changing this setting does not affect previously received messages.
Yes, you can! Your custom user field just have to has the ID threemaid and this add-on will automatically use it. In the 2FA methods it is however only entered as the default value and users can override it if they want.
The best thing is: This user field will be added automatically when installing this add-on so you do not even have to set it up manually.
Also mail addresses will be automatically looked up if the corresponding option is activated in the settings.
-
Create a custom user field where your users can enter their phone number. You may configure this to be publicly visible or not.
-
The new user field gets added:
-
Go to the 2FA settings, activate the phone lookup and enter the field ID you choose earlier there:
Note that your users have to include the country calling codes in the phone number. So e.g. they have to write "+41 791 234567" instead of "0791 234567". However spaces and the "+" sign at the beginning are not required.
If it does not work also make sure that the users have the "lookup" permission.
You should make sure you setup everything correctly. Visit the ACP options page and look at the status. There you will maybe see error messages. Also make sure you have enough credits to send messages.
If this does not help, consider opening an issue.
This add-on has multiple ways which deactivate one or more 2FA methods. Please make sure that...
- Your server setup is complete (look at the status message in the ACP)
- Your credentials are correct
- The user group has enough permissions to use the specific 2FA method. E.g. for the conventional mode the users must have permission to use the Gateway, send messages, fetch public keys (lookup) and use the 2FA mode.
- The 2FA method is activated in the settings.
Note that the Reversed and Fast mode require the end-to-end mode.
There are multiple way to do this. You can hide it...
- for all users by disabling it in the settings
- for some user groups by removing the permission to use the Gateway. Note that this affects all 2FA modes.
When you disable a 2FA mode this only prevents users from activating this mode. Users, who had this mode activated before, do not notice any difference and can still login with this mode. This makes sure that no users get locked out. When they disable the mode however, they should not be able to enable it again.
If you want to prevent users from using the 2FA at all, you can limit the permissions for the user/user group, so that they cannot use the Threema Gateway or the 2FA of the Threema Gateway anymore. However be careful when doing so as this may cause serious problems, because when users do not use any other 2FA method, they will not only get errors, but will also have no way to login anymore. So be careful when disabling 2FA modes!
These messages are saved as phrases. Just search for "threema" and/or "message" and you should find them. E.g. tfa_threemagw_conventional_message contains the long message sent in the conventional 2FA mode.
All messages this add-on sends are saved as phrases. Unicode emotions cannot be saved in phrases directly.
However you can use Unicode characters in the format \u<hexnum>. You can use the same format as in C, C++ or Java source code (where UTF-16 is used). There are also converters for this task.
You do not have to, but it is the best and easiest way to get current, signed releases of the official project. Much work has been put into this projects since I started developing it in 2015 and although I provide it in an open and free (as in freedom) manner, it is nice to get something back. And last but not least it also ensures that I can develop on it in the future ad this project does not die.
I do not really sell it, because you can always get it for free (I mean you've got the source code here.), but even if I would sell the source code under a FLOSS license, it would be completly legal. You can even do it when using much stricter licenses than I use, e.g. when using the GPL.
I don't think so. Just why should this be unethical? You pay for other things and even for many (closed-source) software products, so is not supporting an open-source project a good idea? Or to say it in another way: If this software would be closed-source and with a fixed price you surely would not say it is a problem to require money for it. And BTW: You need to pay money for using the Gateway anyway, so this here should not be a big investment.
However most people are just accustomed to click-through any donation options or ignore them even if they could easily pay some money and would think the project is worth it. But when they can get it free, they use it. That's why I offer the release files as a "gift" after donating. They are neigher secured by anti-ad-block-software nor require you to use shady installers, which automatically populate your computer with toolbars, but you can show your respect by spending some money for this project.
No, not at all. As long as I provide releases and you have access to them (which you get after donating) you can download them.
I may however require another "payment" for a new mayor release (1.x.y to 2.x.y), which may e.g. be released when I adapt this project to XenForo v2, but this does really depend on the changes done in the add-on and currently I do not see any mayor release coming.
Sure, there are donation options, but currently you only get the release files when using PayPal to donate the required amount I list on the release page. However when you donate an equal amount of money using another payment method, you can also drop me a mail with a screenshot, your used user name/account for the payment and the exact date/time when you donated. I will then get back to you as soon as possible, to send you the release files.
In case you use Gratipay.com I cannot reliablily determinate who and what amount you are sending. This is intentional and I can do nothing about this, so unfortunately I cannot yet support Gratipay here. Maybe use another payment method first or so, although I very much like the concept of Gratipay.
Well, no. It's a donation and you even get the release files as a reward. If you do not like it, I am very sorry and I would very much appreciate it if you could give me some feedback, so I can potentially improve the add-on so you like it. However please do not be disappointed when something is out of scope of this project or cannot easily be done.