threema-ios/protobuf/d2d.proto

syntax = "proto3";

package d2d;

option java_package = "ch.threema.protobuf.d2d";

import "common.proto";
import "safe.proto";

// Device to Device Protocol
// =========================
//
// General Information
// -------------------
//
// All messages are symmetrically encrypted with the Mediator Key (MK).
//
// Encryption format: 24 byte nonce prepended, followed by an NaCl box.
//
// All strings are UTF-8 encoded.



// Initial data sent to a device that wants to participate in the device
// group (i.e. a new device to be added by the user).
message InitialData {
  // Threema Safe Backup
  safe.Backup backup = 1;
}

// Data shared across all devices and transmitted during the handshake.
message SharedDeviceData {
  // Random amount of padding, ignored by the receiver
  bytes padding = 1;

  // MDM parameters to be applied on all devices
  MdmParameters mdm_parameters = 2;
}

// Metadata about a device, determined by the device itself.
message DeviceInfo {
  // Random amount of padding, ignored by the receiver
  bytes padding = 1;

  // Platform
  enum Platform {
    // Unknown platform
    UNSPECIFIED = 0;
    // Android
    ANDROID = 1;
    // Apple iOS
    IOS = 2;
    // Web application
    WEB = 3;
  }
  Platform platform = 2;

  // App version
  string app_version = 3;

  // Device description (smartphone model / browser)
  string description = 4;
}

// A transaction scope. Used in the d2m transaction messages.
message TransactionScope {
    enum Scope {
      USER_PROFILE_SYNC = 0;
      CONTACT_SYNC = 1;
      GROUP_SYNC = 2;
      DISTRIBUTION_LIST_SYNC = 3;
      SETTINGS_SYNC = 4;
    }
    Scope scope = 1;
}

// Root message
message Envelope {
  // Random amount of padding, ignored by the receiver
  bytes padding = 1;

  // The enveloped reflected message
  oneof content {
    OutgoingMessage outgoing_message = 2;
    IncomingMessage incoming_message = 3;
    UserProfileSync user_profile_sync = 4;
    ContactSync contact_sync = 5;
    GroupSync group_sync = 6;
    DistributionListSync distribution_list_sync = 7;
    SettingsSync settings_sync = 8;

    MdmParameters mdm_parameters = 9999;
  };
}



// Mobile device management parameters shared across Threema Work devices.
//
// More detailed parameter information is available here:
// https://work.threema.ch/en/docs/mdm_configuration
message MdmParameters {
  // Username required for activation of the app
  // References: `th_license_username`
  oneof license_username { string license_username_value = 1; }

  // Password required for activation of the app
  // References: `th_license_password`
  oneof license_password { string license_password_value = 2; }

  // Nickname to be used
  // References: `th_nickname`
  oneof nickname { string nickname_value = 3; }

  // First name of the user
  // References: `th_firstname`
  oneof first_name { string first_name_value = 4; }

  // Last name of the user
  // References: `th_lastname`
  oneof last_name { string last_name_value = 5; }

  // Customer specific identifier
  // References: `th_csi`
  oneof customer_specific_id { string customer_specific_id_value = 6; }

  // User category
  // References: `th_category`
  oneof category { string category_value = 7; }

  // Email address linked to the ID
  // References: `th_linked_email`
  oneof linked_email { string linked_email_value = 8; }

  // Phone number linked to the ID
  // References: `th_linked_phone`
  oneof linked_phone { string linked_phone_value = 9; }

  // Restore a Threema ID
  // References: `th_id_backup`
  oneof identity_restore { string identity_restore_value = 10; }

  // Password for restoring a Threema ID
  // References: `th_id_backup_password`
  oneof identity_restore_password {
    string identity_restore_password_value = 11;
  }

  // Threema Safe configuration
  // References: `th_safe_enable`
  enum ThreemaSafePolicy {
    // Configurable by the user
    SAFE_OPTIONAL = 0;
    // Forcibly enabled
    SAFE_MANDATORY = 1;
    // Forcibly disabled
    SAFE_DISABLED = 2;
  }
  ThreemaSafePolicy threema_safe_policy = 12;

  // Threema Safe password (predefined)
  // References: `th_safe_password`
  oneof threema_safe_password { string threema_safe_password_value = 13; }

  // Threema Safe password pattern
  // References: `th_safe_password_pattern`
  oneof threema_safe_password_pattern {
    string threema_safe_password_pattern_value = 14;
  }

  // Threema Safe password pattern error (mismatch) message
  // References: `th_safe_password_message`
  oneof threema_safe_password_pattern_error_message {
    string threema_safe_password_pattern_error_message_value = 15;
  }

  // Threema Safe server URL
  // References: `th_safe_server_url`
  oneof threema_safe_server_url { string threema_safe_server_url_value = 16; }

  // Threema Safe server username for authentication
  // References: `th_safe_server_username`
  oneof threema_safe_server_username {
    string threema_safe_server_username_value = 17;
  }

  // Threema Safe server password for authentication
  // References: `th_safe_server_password`
  oneof threema_safe_server_password {
    string threema_safe_server_password_value = 18;
  }

  // Restore policy for restoring from a Threema Safe backup
  // References: `th_safe_restore_enable`
  enum ThreemaSafeRestorePolicy {
    // Choosable by the user
    SAFE_RESTORE_OPTIONAL = 0;
    // Automatic restore
    SAFE_RESTORE_MANDATORY = 1;
    // Forcibly disabled
    SAFE_RESTORE_DISABLED = 2;
  }
  ThreemaSafeRestorePolicy threema_safe_restore_policy = 19;

  // Threema ID to be restored from Threema Safe
  // References: `th_safe_restore_id`
  oneof threema_safe_restore_identity {
    string threema_safe_restore_identity_value = 20;
  }

  // Override policy in regards to MDM parameters (profile, settings, ...)
  // References: `th_readonly_profile`
  enum OverridePolicy {
    // Allows the user to override some of the MDM parameter presets
    LOOSE = 0;
    // The user may not override any MDM parameter presets
    STRICT = 1;
  }
  OverridePolicy override_policy = 21;

  // Contact synchronisation policy
  // References: `th_contact_sync`
  enum ContactSyncPolicy {
    // Not synced
    NOT_SYNCED = 0;
    // Synced
    SYNC = 1;
  }
  ContactSyncPolicy contact_sync_policy = 22;

  // Inactive Threema ID display policy
  // References: `th_hide_inactive_ids`
  enum InactiveIdentityDisplayPolicy {
    // Show inactive IDs
    SHOW_INACTIVE = 0;
    // Hide inactive IDs
    HIDE_INACTIVE = 1;
  }
  InactiveIdentityDisplayPolicy inactive_identity_display_policy = 23;

  // Unknown contacts policy
  // References: `th_block_unknown`
  enum UnknownContactPolicy {
    // Allowed to contact the user
    ALLOW_UNKNOWN = 0;
    // Will be blocked by the user
    BLOCK_UNKNOWN = 1;
  }
  UnknownContactPolicy unknown_contact_policy = 24;

  // Auto-save media policy
  // References: `th_disable_save_to_gallery`
  enum AutoSaveMediaPolicy {
    // Allow auto-saving, configurable by the user
    ALLOW_AUTO_SAVE = 0;
    // Deny auto-saving
    DENY_AUTO_SAVE = 1;
  }
  AutoSaveMediaPolicy auto_save_media_policy = 25;

  // Screenshot policy
  // References: `th_disable_screenshots`
  enum ScreenshotPolicy {
    // Allow taking screenshots
    ALLOW_SCREENSHOT = 0;
    // Deny taking screenshots, if possible
    DENY_SCREENSHOT = 1;
  }
  ScreenshotPolicy screenshot_policy = 26;

  // Add contact policy
  // References: `th_disable_add_contact`
  enum AddContactPolicy {
    // Allow manually adding contacts
    ALLOW_ADD_CONTACT = 0;
    // Deny manually adding contacts
    DENY_ADD_CONTACT = 1;
  }
  AddContactPolicy add_contact_policy = 27;

  // Chat export policy
  // References: `th_disable_export`
  enum ChatExportPolicy {
    // Allow exporting chats
    ALLOW_CHAT_EXPORT = 0;
    // Deny exporting of chats
    DENY_CHAT_EXPORT = 1;
  }
  ChatExportPolicy chat_export_policy = 28;

  // Backup policy
  // References: `th_disable_backups`
  enum BackupPolicy {
    // Generally allow backups to be made
    ALLOW_BACKUP = 0;
    // Deny creating backups
    DENY_BACKUP = 1;
  }
  BackupPolicy backup_policy = 29;

  // Threema ID export policy
  // References: `th_disable_id_export`
  enum IdentityExportPolicy {
    // Allow exporting of the Threema ID
    ALLOW_IDENTITY_EXPORT = 0;
    // Deny exporting of the Threema ID
    DENY_IDENTITY_EXPORT = 1;
  }
  IdentityExportPolicy identity_export_policy = 30;

  // Data backup policy
  // References: `th_disable_data_backups`
  enum DataBackupPolicy {
    // Allow creating data backups
    ALLOW_DATA_BACKUP = 0;
    // Deny creating data backups
    DENY_DATA_BACKUP = 1;
  }
  DataBackupPolicy data_backup_policy = 31;

  // System backup policy
  // References: `th_disable_system_backups`
  enum SystemBackupPolicy {
    // The system may include app data
    ALLOW_SYSTEM_BACKUP = 0;
    // The system is denied from including app data
    DENY_SYSTEM_BACKUP = 1;
  }
  SystemBackupPolicy system_backup_policy = 32;

  // Message preview (in notifications)
  // References: `th_disable_message_preview`
  enum MessagePreviewPolicy {
    // Allow showing a message preview
    ALLOW_PREVIEW = 0;
    // Deny showing a message preview
    DENY_PREVIEW = 1;
  }
  MessagePreviewPolicy message_preview_policy = 33;

  // Profile picture sharing policy
  // References: `th_disable_send_profile_picture`
  enum ProfilePictureSharePolicy {
    // Allow the profile picture to be shared with contacts
    ALLOW_SHARE = 0;
    // Denied from sharing the profile picture with contacts
    DENY_SHARE = 1;
  }
  ProfilePictureSharePolicy profile_picture_share_policy = 34;

  // Threema Call policy
  // References: `th_disable_calls`
  enum CallPolicy {
    // Allow creating/receiving Threema Calls
    ALLOW_CALL = 0;
    // Denied from creating/receiving any Threema Calls
    DENY_CALL = 1;
  }
  CallPolicy call_policy = 35;

  // Setup wizard policy
  // References: `th_skip_wizard`
  enum SetupWizardPolicy {
    // Show the setup wizard
    SHOW_WIZARD = 0;
    // Skip the setup wizard (restores an ID or a backup and sets up the
    // profile automatically).
    SKIP_WIZARD = 1;
  }
  SetupWizardPolicy setup_wizard_policy = 36;

  // Group creation policy
  // References: `th_disable_create_group`
  enum CreateGroupPolicy {
    // Allow manually creating groups
    ALLOW_CREATE_GROUP = 0;
    // Deny manually creating groups
    DENY_CREATE_GROUP = 1;
  }
  CreateGroupPolicy create_group_policy = 37;

  // Share media policy
  // References: `th_disable_share_media`
  enum ShareMediaPolicy {
    // Allow unrestricted sharing of media
    ALLOW_SHARE_MEDIA = 0;
    // Deny sharing of media outside of Threema, if possible
    DENY_OUTSIDE_APP = 1;
  }
  ShareMediaPolicy share_media_policy = 38;
}

// Message type as defined by the Chat Server Protocol.
enum MessageType {
  // Invalid message type
  INVALID = 0x00;

  // Text message
  TEXT = 0x01;
  // Image message (deprecated, use `FILE_MESSAGE`)
  IMAGE = 0x02;
  // Location message
  LOCATION = 0x10;
  // Audio message (deprecated, use `FILE_MESSAGE`)
  AUDIO = 0x14;
  // Video message (deprecated, use `FILE_MESSAGE`)
  VIDEO = 0x13;
  // File message
  FILE = 0x17;
  // Create a poll
  POLL_CREATE = 0x15;
  // Cast a vote on a poll
  POLL_VOTE = 0x16;
  // Call offer
  CALL_OFFER = 0x60;
  // Call answer
  CALL_ANSWER = 0x61;
  // Call ICE Candidate
  CALL_ICE_CANDIDATE = 0x62;
  // Call hangup
  CALL_HANGUP = 0x63;
  // Call ringing
  CALL_RINGING = 0x64;
  // Call missed
  CALL_MISSED = 0x65;

  // Delivery receipt
  DELIVERY_RECEIPT = 0x80;
  // Typing indicator
  TYPING_INDICATOR = 0x90;

  // Set profile picture of a contact
  CONTACT_SET_PROFILE_PICTURE = 0x18;
  // Delete profile picture of a contact
  CONTACT_DELETE_PROFILE_PICTURE = 0x19;
  // Request profile picture of a contact
  CONTACT_REQUEST_PROFILE_PICTURE = 0x1a;

  // Create a group
  GROUP_CREATE = 0x4a;
  // Rename a group
  GROUP_RENAME = 0x4b;
  // Leave a group
  GROUP_LEAVE = 0x4c;
  // Set a group's profile picture
  GROUP_SET_PROFILE_PICTURE = 0x50;
  // Delete a group's profile picture
  GROUP_DELETE_PROFILE_PICTURE = 0x54;
  // Request group synchronisation
  GROUP_REQUEST_SYNC = 0x51;

  // Group text message
  GROUP_TEXT = 0x41;
  // Group location message
  GROUP_LOCATION = 0x42;
  // Group image message
  GROUP_IMAGE = 0x43;
  // Group audio message
  GROUP_AUDIO = 0x45;
  // Group video message
  GROUP_VIDEO = 0x44;
  // Group file message
  GROUP_FILE = 0x46;
  // Create a group poll
  GROUP_POLL_CREATE = 0x52;
  // Cast a vote on a group poll
  GROUP_POLL_VOTE = 0x53;
}

// A message receiver can be a single user or a group.
message MessageReceiver {
  // The recipient's Threema ID or a group identity.
  oneof receiver {
    string identity = 1;
    common.GroupIdentity group = 2;
  }
}

// An outgoing message, reflected to other devices.
message OutgoingMessage {
  // Recipient of the enclosed message.
  //
  // Note: If the receiver is a group identity, group and group creator id of
  //       the enclosed message must match the values of the supplied group
  //       identity. Otherwise, the message must be considered invalid.
  MessageReceiver receiver = 1;

  // Unique ID of the enclosed message
  fixed64 message_id = 2;

  // Unix-ish timestamp in milliseconds for when the message has been created
  uint64 created_at = 3;

  // Enclosed message's type
  MessageType type = 4;

  // The message's body as defined for `Message` (0x01/0x02) of the Chat
  // Server Protocol.
  bytes body = 5;
}

// An outgoing message has been delivered to the chat server.
//
// Note: This indicates that the message has been successfully stored in the
//       message queue of the server. It does NOT indicate that the message has
//       been delivered to the intended receiver.
message OutgoingMessageDelivered {
  // Recipient of the delivered message.
  MessageReceiver receiver = 1;

  // Unique ID of the delivered message
  fixed64 message_id = 2;
}

// An incoming message, reflected to other devices.
message IncomingMessage {
  // Sender's Threema ID
  string sender_identity = 1;

  // Sender's public nickname
  string sender_nickname = 2;

  // Unique ID of the enclosed message
  fixed64 message_id = 3;

  // Unix-ish timestamp in milliseconds for when the message has been created
  uint64 created_at = 4;

  // Enclosed message's type
  MessageType type = 5;

  // The message's body as defined for `Message` (0x01/0x02) of the Chat
  // Server Protocol.
  bytes body = 6;
}

// User profile synchronisation message.
message UserProfileSync {
  // Update the user's profile
  message Set {
    safe.UserProfile user_profile = 1;
  }

  // Synchronisation type
  oneof action {
    Set set = 1;
  }
}

// Contact synchronisation message.
message ContactSync {
  // Set a Threema contact
  message Set {
    safe.Contact contact = 1;
  }

  // Delete a Threema contact
  message Delete {
    string delete_identity = 1;
  }

  // Synchronisation type
  oneof action {
    Set set = 1;
    Delete delete = 2;
  }
}

// Group synchronisation message.
message GroupSync {
  // Set a group
  message Set {
    safe.Group group = 1;
  }

  // Delete a group
  message Delete {
    // Unique group identity
    common.GroupIdentity group_identity = 1;
  }

  // Synchronisation type
  oneof action {
    Set set = 1;
    Delete delete = 2;
  }
}

// Distribution list synchronisation message.
message DistributionListSync {
  // Set a distribution list
  message Set {
    safe.DistributionList distribution_list = 1;
  }

  // Delete a group
  message Delete {
    // Unique ID of the distribution list
    fixed64 distribution_list_id = 1;
  }

  // Synchronisation type
  oneof action {
    Set set = 1;
    Delete delete = 2;
  }
}

// Settings synchronisation message.
message SettingsSync {
  // Apply settings
  message Set {
    safe.Settings settings = 1;
  }

  // Synchronisation type
  oneof action {
    Set set = 1;
  }
}