Security guide

This is a small security guide to show you what things you should or should not do. As it is just a guide it's up to you what rules you follow and what not.

File list

Files which should never be accessible from the webserver

This is a list of files which should never be accessible to anyone accessing your site.

• Your private key file: privateKey.txt

• Your key store:

  • either your TXT key store: keystore.txt
  • or your PHP key store: keystore.php (already provides some protection if it is parsed by your webserver)

• Your downloaded images and other files

Files which should not be accessible from the webserver

This is a list of files which are recommend not to be accessible to anyone accessing your site. If they are accessible they do not provide an immediate security risk, but it is not advised to leave them in such a state.

• the PHP source

  • including the console tool threema-msgapi-tool.php
  • including the sample implementation of this SDK (directory: /samples)

• the documentation (/doc) if you downloaded it too; you can also delete this folder as it is not needed for the functionality of the SDK

Files which may be accessible from the webserver

This is a list of files which do not provide a security risk if they are accessible or which even have to be accessible.

• Your public key file: publicKey.txt
• Your callback URL if you also want to receive messages

Do's

1. Obviously for real security you should use the end-to-end-method.
2. Use a keystore. There are some implemented in this API, but you can also easily develop your own one.
3. By using it you not only prevent querying the server for every message, but also increase the security of the messages as it's more difficult to intercept the connection and spoof the public key.
4. Protect the private key file and the keystore. You may use an encrypted file system to protect all files or store your private key file in a directory which is not accessible from the webserver and not easy to guess.
5. For instance the PHP keystore already provides a basic protection as the PHP script is parsed, so that the file won't be publicly visible even if a user is able to access the site.
6. Use the TLS options of ConnectionSettings and choose strong settings for them. The example used in the Readme should include strong settings, but please be aware that this may change over the time as TLS develops.
7. The best way to securely get the public key of a receiver is to extract it from the QR code.
8. You can find the format of the QR code in the Threema whitepaper (page 3).
9. If you use the callback URL...
10. Use a unique - not easily guessable - one.
11. Check your own SSL/TLS configuration with tools like SSLLabs. You may even consider using a new subdomain with a new SSL configuration which only supports a few TLS versions and/or ciphers (which are supported by the Threema Gateway server) to prevent downgrade attacks.
12. In your implementation always check the MAC of the message before you do anything else. If the MAC is not valid cancel the process and possibly log the failure.
13. If possible use curl v7.39 or higher, so that key pinning can be used by this SDK.

Don'ts

1. Do not share your secret. If you also receive messages it is important that only you know your secret as this is the one which is used in the HMAC to verify the message.
   If the secret is compromised, generate a new one on the Threema Gateway site.