HOWTOs

Pre-requisites

Use console client

Local operations (no network communication)

Encrypt

java -jar threema-msgapi-tool.jar -e <privateKey> <publicKey>

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

Decrypt

java -jar threema-msgapi-tool.jar -d <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.

Hash Email Address

java -jar threema-msgapi-tool.jar -h -e <email>

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

Hash Phone Number

java -jar threema-msgapi-tool.jar -h -p <phoneNo>

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

Generate Key Pair

java -jar threema-msgapi-tool.jar -g <privateKeyFile> <publicKeyPath>

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

Derive Public Key

java -jar threema-msgapi-tool.jar -p <privateKey>

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

Network operations

Send Simple Message

java -jar threema-msgapi-tool.jar -s <to> <from> <secret>

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

Send End-to-End Encrypted Text Message

java -jar threema-msgapi-tool.jar -S <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 End-to-End Encrypted Image Message (deprecated, use the File Message type instead)

java -jar threema-msgapi-tool.jar -S -i <to> <from> <secret> <privateKey> <imageFilePath>

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 End-to-End Encrypted File Message

java -jar threema-msgapi-tool.jar -S -f <to> <from> <secret> <privateKey> <file> [thumbnail]

Encrypt the file (and thumbnail) and send a file 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

java -jar threema-msgapi-tool.jar -l -e <email> <from> <secret>

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

ID Lookup By Phone Number

java -jar threema-msgapi-tool.jar -l -p <phoneNo> <from> <secret>

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

Fetch Public Key

java -jar threema-msgapi-tool.jar -l -k <id> <from> <secret>

Lookup the public key for the given ID.

Fetch Capability

java -jar threema-msgapi-tool.jar -c <id> <from> <secret>

Fetch the capabilities of a Threema ID

Decrypt and download

java -jar threema-msgapi-tool.jar -D <id> <from> <secret> <privateKey> <messageId> <nonce> [outputFolder]

Decrypt a box (box from the stdin) message and download (if the message is an image or file message) the file(s) to the defined directory

Create a Connection

	String gatewayId = "*MYGWID1";
	String secret = "SECRET_OF_MY_GATEWAY_ID";

	APIConnector apiConnector = new APIConnector(gatewayId, secret, new PublicKeyStore() {
		@Override
		protected byte[] fetchPublicKey(String threemaId) {
			//TODO: implement public key fetch
			//(e.g. fetch from a locally saved file)
			return null;
		}

		@Override
		protected void save(String threemaId, byte[] publicKey) {
			//TODO: implement public key saving
			//(e.g. save to a locally saved file)
		});
		
		

Send a Text Message to a Threema-ID (Basic Mode)

	//create the connection
	String threemaId = "ABCD1234";
	String text = "Basic Mode Message";

	String messageId = apiConnector.sendTextMessage(threemaId, text);
		

Send a Text Message to a Threema-ID (End-To-End Mode)

	//create the connection
	String threemaId = "ABCD1234";
	String textMessage = "End-To-End Encrypted Message";
	byte[] privateKey = DataUtils.readKeyFile(new File("/path/to/my/private.key"), Key.KeyType.PRIVATE).key;

	E2EHelper e2EHelper = new E2EHelper(apiConnector, privateKey);
	String messageId = e2EHelper.sendTextMessage(to, textMessage);
		

Send a File Message to a Threema-ID (End-To-End Mode)

	//create the connection
	String threemaId = "ABCD1234";
	String textMessage = "End-To-End Encrypted Message";
	byte[] privateKey = DataUtils.readKeyFile(new File("/path/to/my/private.key"), Key.KeyType.PRIVATE).key;
	File fileToSend = new File("/path/to/my/pdf.pdf");
	File thumbnailFileToSend = new File("/path/to/my/pdf-thumbnail.jpg");

	E2EHelper e2EHelper = new E2EHelper(apiConnector, privateKey);
	String messageId = e2EHelper.sendFileMessage(to, fileToSend, thumbnailFileToSend);