Crate threema_gateway

Threema Gateway SDK for Rust

This library makes it easy to use the Threema Gateway from Rust programs.

Documentation of the HTTP API can be found at gateway.threema.ch.

Note: This library is fully asynchronous (because the underlying HTTP client is async as well). To call the async methods, either call them from an async context, or wrap the returned future in a block_on method provided by an executor like tokio, async-std or smol.

Example: Send simple (transport encrypted) message

use threema_gateway::{ApiBuilder, Recipient};

let from = "*YOUR_ID";
let to = Recipient::new_email("user@example.com");
let secret = "your-gateway-secret";
let text = "Very secret message!";

// Send
let api = ApiBuilder::new(from, secret).into_simple();
match api.send(&to, &text).await {
    Ok(msg_id) => println!("Sent. Message id is {}.", msg_id),
    Err(e) => println!("Could not send message: {:?}", e),
}

Example: Send end-to-end encrypted message

use threema_gateway::{ApiBuilder, RecipientKey};

let from = "*YOUR_ID";
let to = "ECHOECHO";
let secret = "your-gateway-secret";
let private_key = "your-private-key";
let text = "Very secret message!";

// Create E2eApi instance
let api = ApiBuilder::new(from, secret)
    .with_private_key_str(private_key)
    .and_then(|builder| builder.into_e2e())
    .unwrap();

// Fetch recipient public key
// Note: In a real application, you should cache the public key
let recipient_key = api.lookup_pubkey(to).await.unwrap();

// Encrypt
let encrypted = api.encrypt_text_msg(text, &recipient_key)
    .expect("Could not encrypt text msg");

// Send
match api.send(&to, &encrypted, false).await {
    Ok(msg_id) => println!("Sent. Message id is {}.", msg_id),
    Err(e) => println!("Could not send message: {:?}", e),
}

For more examples, see the examples/ directory.

Modules

• errors
  Error types used in this library.

Structs

• ApiBuilder
  A convenient way to set up the API object.
• BlobId
  A 16-byte blob ID.
• Capabilities
  A struct containing flags according to the capabilities of a Threema ID.
• E2eApi
  Struct to talk to the E2E API (with end-to-end encryption).
• EncryptedFileData
  Encrypted bytes of a file and optionally a thumbnail.
• EncryptedMessage
  An encrypted message. Contains both the ciphertext and the nonce.
• FileData
  Raw unencrypted bytes of a file and optionally a thumbnail.
• FileMessage
  A file message.
• FileMessageBuilder
  Builder for FileMessage.
• IncomingMessage
  An incoming message received from Threema Gateway.
• Key
  Key type used for nacl secretbox cryptography
• PublicKey
  A crypto_box public key.
• RecipientKey
  The public key of a recipient.
• SecretKey
  A crypto_box secret key.
• SimpleApi
  Struct to talk to the simple API (without end-to-end encryption).

Enums

• LookupCriterion
  Different ways to look up a Threema ID in the directory.
• MessageType
  A message type.
• Recipient
  Different ways to specify a message recipient in basic mode.
• RenderingType
  The rendering type influences how a file message is displayed on the device of the recipient.

Functions

• decrypt_file_data
  Decrypt file data and optional thumbnail data with the provided symmetric key.
• encrypt
  Encrypt a message with the specified msgtype for the recipient.
• encrypt_file_data
  Encrypt file data and an optional thumbnail using a randomly generated symmetric key.
• encrypt_raw
  Encrypt raw data for the recipient.

Type Aliases

• Nonce
  Nonce type.