HOWTOs

Note

The Python SDK requires Python 3.7+.

On operating systems where Python 3 is not the default Python runtime, you should use pip3 instead of pip.

Prerequisites

Install Python 3, pip and the virtual environment for Python (optional).

sudo apt-get install python3 python3-pip

We recommend creating an isolated Python environment (virtualenv) for your development:

python3 -m venv threema-gateway-venv

You can switch into the created virtual environment threema-gateway-venv by running the following command:

source threema-gateway-venv/bin/activate

To deactivate the virtual environment, just run:

deactivate

Installation

If you are using a virtual environment, activate it first.

Then, install the module from the Python Package Index (PyPI) by running:

pip install threema.gateway

The required dependencies will be installed automatically. However, you may need to install libsodium.

Use console client

Local operations (no network communication)

Encrypt

threema-gateway encrypt <privateKey> <publicKey>
	

Encrypt standard input using the given sender private key and recipient public key. Two lines to standard output: first the nonce (hex), and then the box (hex).

Decrypt

threema-gateway decrypt <privateKey> <publicKey> <nonce>
	

Decrypt standard input using the given recipient private key and sender public key. The nonce must be given on the command line, and the box (hex) on standard input. Prints the decrypted message to standard output.

$ echo -n 'aff0...' | threema-gateway decrypt private:[PRIVATE_KEY] public:[PUBLIC_KEY] [NONCE]

Hash Email Address

threema-gateway hash -e <email>
	

Hash an email address for identity lookup. Prints the hash in hex.

Hash Phone Number

threema-gateway hash -p <phoneNo>
	

Hash a phone number for identity lookup. Prints the hash in hex.

Generate Key Pair

threema-gateway generate <privateKeyFile> <publicKeyFile>
	

Generate a new key pair and write the private and public keys to the respective files (in hex).

Derive Public Key

threema-gateway derive <privateKey>
	

Derive the public key that corresponds with the given private key.

Network operations

Send Simple Message

threema-gateway send_simple <to> <from> <secret>
	

Send a message from standard input with server-side encryption to the given ID. is the API identity and 'secret' is the API secret. the message ID on success.

Send End-to-End Enrypted Text Message

threema-gateway send_e2e <to> <from> <secret> <privateKey>
	

Encrypt standard input and send the message to the given ID. 'from' is the API identity and 'secret' is the API secret. Prints the message ID on success.

Send a End-to-End Encrypted Image Message (deprecated, use the File Message type instead)

threema-gateway send_image <to> <from> <secret> <privateKey> <imageFile>
	

Encrypt the image file and send the message to the given ID. 'from' is the API identity and 'secret' is the API secret. Prints the message ID on success.

Send a End-to-End Encrypted File Message

threema-gateway send_file <to> <from> <secret> <privateKey> <file> -i <thumbnailFile>
	

Encrypt the file (and thumbnail if given) and send the message to the given ID. 'from' is the API identity and 'secret' is the API secret. Prints the message ID on success.

ID-Lookup By Email Address

threema-gateway lookup <from> <secret> -e <email>
	

Lookup the ID linked to the given email address (will be hashed locally).

ID-Lookup By Phone Number

threema-gateway lookup <from> <secret> -p <phoneNo>
	

Lookup the ID linked to the given phone number (will be hashed locally).

Fetch Public Key

threema-gateway lookup <from> <secret> -i <id>
	

Lookup the public key for the given ID.

Fetch Capability

threema-gateway capabilities <from> <secret> <id>
	

Fetch the capabilities of a Threema ID

Remaining credits

threema-gateway credits <from> <secret>
	

Fetch remaining credits