Skip to content

Latest commit

 

History

History
539 lines (435 loc) · 22.2 KB

specification.md

File metadata and controls

539 lines (435 loc) · 22.2 KB

Publisher Specifications

Table of Contents

Content Format

Content Format V0

Note

For detailed instructions on encrypting the content format using the Double Ratchet algorithm, refer to the smswithoutborders_lib_sig documentation.

  1. Email format: from:to:cc:bcc:subject:body[:access_token:refresh_token]

    • Example: Gmail
    • Square brackets ([]) indicate optional fields.

  2. Text format: sender:text[:access_token:refresh_token]

    • Example: Twitter
    • Square brackets ([]) indicate optional fields.

  3. Message format: sender:receiver:message

    • Example: Telegram

  4. Test format: test_id

Content Format V1

Note

For detailed instructions on encrypting the content format using the Double Ratchet algorithm, refer to the smswithoutborders_lib_sig documentation.

Note

All service types use the same structure, but fields not applicable to a specific service type will have their length bytes set to 0, and no value bytes will follow for those fields.

All 2-byte length fields are encoded as unsigned little-endian.

  1. Email format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field.
    • 2 bytes: Length of cc field.
    • 2 bytes: Length of bcc field.
    • 1 byte: Length of subject field.
    • 2 bytes: Length of body field.
    • 1 byte: Length of access_token field (optional).
    • 1 byte: Length of refresh_token field (optional).
    • Variable: Value of from field.
    • Variable: Value of to field.
    • Variable: Value of cc field.
    • Variable: Value of bcc field.
    • Variable: Value of subject field.
    • Variable: Value of body field.
    • Variable: Value of access_token field (if present).
    • Variable: Value of refresh_token field (if present).

  2. Text format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field (set to 0).
    • 2 bytes: Length of cc field (set to 0).
    • 2 bytes: Length of bcc field (set to 0).
    • 1 byte: Length of subject field (set to 0).
    • 2 bytes: Length of body field.
    • 1 byte: Length of access_token field (optional).
    • 1 byte: Length of refresh_token field (optional).
    • Variable: Value of from field.
    • Variable: Value of body field.
    • Variable: Value of access_token field (if present).
    • Variable: Value of refresh_token field (if present).

  3. Message format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field.
    • 2 bytes: Length of cc field (set to 0).
    • 2 bytes: Length of bcc field (set to 0).
    • 1 byte: Length of subject field (set to 0).
    • 2 bytes: Length of body field.
    • 1 byte: Length of access_token field (set to 0).
    • 1 byte: Length of refresh_token field (set to 0).
    • Variable: Value of from field.
    • Variable: Value of to field.
    • Variable: Value of body field.

  4. Test format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field (set to 0).
    • 2 bytes: Length of cc field (set to 0).
    • 2 bytes: Length of bcc field (set to 0).
    • 1 byte: Length of subject field (set to 0).
    • 2 bytes: Length of body field (set to 0).
    • 1 byte: Length of access_token field (set to 0).
    • 1 byte: Length of refresh_token field (set to 0).
    • Variable: Value of from field (considered the test ID).

Content Format V2

Note

For detailed instructions on encrypting the content format using the Double Ratchet algorithm, refer to the smswithoutborders_lib_sig documentation.

Note

All service types use the same structure, but fields not applicable to a specific service type will have their length bytes set to 0, and no value bytes will follow for those fields.

All 2-byte length fields are encoded as unsigned little-endian.

  1. Email format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field.
    • 2 bytes: Length of cc field.
    • 2 bytes: Length of bcc field.
    • 1 byte: Length of subject field.
    • 2 bytes: Length of body field.
    • 2 bytes: Length of access_token field (optional).
    • 2 bytes: Length of refresh_token field (optional).
    • Variable: Value of from field.
    • Variable: Value of to field.
    • Variable: Value of cc field.
    • Variable: Value of bcc field.
    • Variable: Value of subject field.
    • Variable: Value of body field.
    • Variable: Value of access_token field (if present).
    • Variable: Value of refresh_token field (if present).

  2. Text format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field (set to 0).
    • 2 bytes: Length of cc field (set to 0).
    • 2 bytes: Length of bcc field (set to 0).
    • 1 byte: Length of subject field (set to 0).
    • 2 bytes: Length of body field.
    • 2 byte: Length of access_token field (optional).
    • 2 byte: Length of refresh_token field (optional).
    • Variable: Value of from field.
    • Variable: Value of body field.
    • Variable: Value of access_token field (if present).
    • Variable: Value of refresh_token field (if present).

  3. Message format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field.
    • 2 bytes: Length of cc field (set to 0).
    • 2 bytes: Length of bcc field (set to 0).
    • 1 byte: Length of subject field (set to 0).
    • 2 bytes: Length of body field.
    • 2 byte: Length of access_token field (set to 0).
    • 2 byte: Length of refresh_token field (set to 0).
    • Variable: Value of from field.
    • Variable: Value of to field.
    • Variable: Value of body field.

  4. Test format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field (set to 0).
    • 2 bytes: Length of cc field (set to 0).
    • 2 bytes: Length of bcc field (set to 0).
    • 1 byte: Length of subject field (set to 0).
    • 2 bytes: Length of body field (set to 0).
    • 2 byte: Length of access_token field (set to 0).
    • 2 byte: Length of refresh_token field (set to 0).
    • Variable: Value of from field (considered the test ID).

Content Format V3

Note

For detailed instructions on encrypting the content format using the Double Ratchet algorithm, refer to the smswithoutborders_lib_sig documentation.

Note

This format improves efficiency by only including length fields for applicable fields per service type, rather than including all fields with zero lengths.

All 2-byte length fields are encoded as unsigned little-endian.

  1. Email format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field.
    • 2 bytes: Length of cc field.
    • 2 bytes: Length of bcc field.
    • 1 byte: Length of subject field.
    • 2 bytes: Length of body field.
    • 2 bytes: Length of access_token field (optional).
    • 2 bytes: Length of refresh_token field (optional).
    • Variable: Value of from field.
    • Variable: Value of to field.
    • Variable: Value of cc field.
    • Variable: Value of bcc field.
    • Variable: Value of subject field.
    • Variable: Value of body field.
    • Variable: Value of access_token field (if present).
    • Variable: Value of refresh_token field (if present).

  2. Text format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of body field.
    • 2 bytes: Length of access_token field (optional).
    • 2 bytes: Length of refresh_token field (optional).
    • Variable: Value of from field.
    • Variable: Value of body field.
    • Variable: Value of access_token field (if present).
    • Variable: Value of refresh_token field (if present).

  3. Message format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field.
    • 2 bytes: Length of body field.
    • Variable: Value of from field.
    • Variable: Value of to field.
    • Variable: Value of body field.

  4. Test format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • Variable: Value of from field (considered the test ID).

Content Format V4

Note

For detailed instructions on encrypting the content format using the Double Ratchet algorithm, refer to the smswithoutborders_lib_sig documentation.

Note

This format extends V3 by adding support for image content.

All 2-byte length fields are encoded as unsigned little-endian.

  1. Email format: Binary-encoded fields with the following structure:

    • Variable: Value of image field.
    • 1 byte: Length of from field.
    • 2 bytes: Length of to field.
    • 2 bytes: Length of cc field.
    • 2 bytes: Length of bcc field.
    • 1 byte: Length of subject field.
    • 2 bytes: Length of body field.
    • 2 bytes: Length of access_token field (optional).
    • 2 bytes: Length of refresh_token field (optional).
    • Variable: Value of from field.
    • Variable: Value of to field.
    • Variable: Value of cc field.
    • Variable: Value of bcc field.
    • Variable: Value of subject field.
    • Variable: Value of body field.
    • Variable: Value of access_token field (if present).
    • Variable: Value of refresh_token field (if present).

  2. Text format: Binary-encoded fields with the following structure:

    • Variable: Value of image field.
    • 1 byte: Length of from field.
    • 2 bytes: Length of body field.
    • 2 bytes: Length of access_token field (optional).
    • 2 bytes: Length of refresh_token field (optional).
    • Variable: Value of from field.
    • Variable: Value of body field.
    • Variable: Value of access_token field (if present).
    • Variable: Value of refresh_token field (if present).

  3. Message format: Binary-encoded fields with the following structure:

    • Variable: Value of image field.
    • 1 byte: Length of from field.
    • 2 bytes: Length of to field.
    • 2 bytes: Length of body field.
    • Variable: Value of from field.
    • Variable: Value of to field.
    • Variable: Value of body field.

  4. Test format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • Variable: Value of from field (considered the test ID).

Supported Payload Versions

Version Hexadecimal Value Decimal Value Description
v0 None None Legacy format with 4-byte ciphertext length and no version marker. Device ID has variable length without explicit length field.
v1 0x01 1 Introduces version marker, 2-byte ciphertext length, explicit device ID length field, and language code support. Uses Content Format V1 with 1-byte token length fields.
v2 0x02 2 Same payload structure as V1 but uses Content Format V2 with 2-byte token length fields for better support of longer access/refresh tokens.
v3 0x03 3 Same payload structure as V1/V2 but uses Content Format V3 with bitmap-based field presence indication for more efficient encoding.
v4 0x04 4 Same payload structure as V1/V2/V3 but uses Content Format V4 with support for image content.

Payload Format V0

See available versions

Message Payload

  • Format:
    • 4 bytes: Ciphertext Length.
    • 1 byte: Platform shortcode. For a list of supported platforms and their corresponding shortcodes, refer to the Supported Platforms section.
    • Variable: Ciphertext. (encrypted Content Format V0).
    • Variable: Device ID.

Note

For detailed instructions on using the Double Ratchet algorithm to create ciphertext, refer to the smswithoutborders_lib_sig documentation.

Visual Representation:

+-------------------+--------------------+-------------------+-----------------+
| Ciphertext Length | Platform shortcode | Ciphertext        | Device ID       |
| (4 bytes)         | (1 byte)           | (Variable size)   | (Variable size) |
+-------------------+--------------------+-------------------+-----------------+

platform_shortcode = b'g'
encrypted_content = b'...'
device_id = b'...'

payload = struct.pack("<i", len(encrypted_content)) + platform_shortcode + encrypted_content + device_id
encoded = base64.b64encode(payload).decode("utf-8")
print(encoded)

Payload Format V1

See available versions

Message Payload

  • Format:
    • 1 byte: Version Marker. See available versions.
    • 2 bytes: Ciphertext Length.
    • 1 byte: Device ID Length.
    • 1 byte: Platform shortcode.
    • Variable: Ciphertext. (encrypted Content Format V1).
    • Variable: Device ID.
    • 2 bytes: Language Code (ISO 639-1 format).

Note

For detailed instructions on using the Double Ratchet algorithm to create ciphertext, refer to the smswithoutborders_lib_sig documentation.

Visual Representation:

+----------------+-------------------+------------------+--------------------+-----------------+-----------------+---------------+
| Version Marker | Ciphertext Length | Device ID Length | Platform shortcode | Ciphertext      | Device ID       | Language Code |
| (1 byte)       | (2 bytes)         | (1 byte)         | (1 byte)           | (Variable size) | (Variable size) | (2 bytes)     |
+----------------+-------------------+------------------+--------------------+-----------------+-----------------+---------------+

version_marker = b'\x01'
platform_shortcode = b'g'
language_code = b'en'
device_id = b'...'
encrypted_content = b'...'

payload = (
   version_marker +
   struct.pack("<H", len(encrypted_content)) +
   bytes([len(device_id)]) +
   platform_shortcode +
   encrypted_content +
   device_id +
   language_code
)
encoded = base64.b64encode(payload).decode("utf-8")
print(encoded)

Payload Format V2

See available versions

Message Payload

  • Format:
    • 1 byte: Version Marker. See available versions.
    • 2 bytes: Ciphertext Length.
    • 1 byte: Device ID Length.
    • 1 byte: Platform shortcode.
    • Variable: Ciphertext. (encrypted Content Format V2).
    • Variable: Device ID.
    • 2 bytes: Language Code (ISO 639-1 format).

Note

For detailed instructions on using the Double Ratchet algorithm to create ciphertext, refer to the smswithoutborders_lib_sig documentation.

Visual Representation:

+----------------+-------------------+------------------+--------------------+-----------------+-----------------+---------------+
| Version Marker | Ciphertext Length | Device ID Length | Platform shortcode | Ciphertext      | Device ID       | Language Code |
| (1 byte)       | (2 bytes)         | (1 byte)         | (1 byte)           | (Variable size) | (Variable size) | (2 bytes)     |
+----------------+-------------------+------------------+--------------------+-----------------+-----------------+---------------+

version_marker = b'\x02'
platform_shortcode = b'g'
language_code = b'en'
device_id = b'...'
encrypted_content = b'...'

payload = (
   version_marker +
   struct.pack("<H", len(encrypted_content)) +
   bytes([len(device_id)]) +
   platform_shortcode +
   encrypted_content +
   device_id +
   language_code
)
encoded = base64.b64encode(payload).decode("utf-8")
print(encoded)

Payload Format V3

See available versions

Message Payload

  • Format:
    • 1 byte: Version Marker. See available versions.
    • 2 bytes: Ciphertext Length.
    • 1 byte: Device ID Length.
    • 1 byte: Platform shortcode.
    • Variable: Ciphertext. (encrypted Content Format V3).
    • Variable: Device ID.
    • 2 bytes: Language Code (ISO 639-1 format).

Note

For detailed instructions on using the Double Ratchet algorithm to create ciphertext, refer to the smswithoutborders_lib_sig documentation.

Visual Representation:

+----------------+-------------------+------------------+--------------------+-----------------+-----------------+---------------+
| Version Marker | Ciphertext Length | Device ID Length | Platform shortcode | Ciphertext      | Device ID       | Language Code |
| (1 byte)       | (2 bytes)         | (1 byte)         | (1 byte)           | (Variable size) | (Variable size) | (2 bytes)     |
+----------------+-------------------+------------------+--------------------+-----------------+-----------------+---------------+

version_marker = b'\x03'
platform_shortcode = b'g'
language_code = b'en'
device_id = b'...'
encrypted_content = b'...'

payload = (
   version_marker +
   struct.pack("<H", len(encrypted_content)) +
   bytes([len(device_id)]) +
   platform_shortcode +
   encrypted_content +
   device_id +
   language_code
)
encoded = base64.b64encode(payload).decode("utf-8")
print(encoded)

Payload Format V4

See available versions

Message Payload

  • Format:
    • 1 byte: Version Marker. See available versions.
    • 2 bytes: Ciphertext Length.
    • 1 byte: Device ID Length.
    • 1 byte: Platform shortcode.
    • Variable: Ciphertext. (encrypted Content Format V4).
    • Variable: Device ID.
    • 2 bytes: Language Code (ISO 639-1 format).

Note

For detailed instructions on using the Double Ratchet algorithm to create ciphertext, refer to the smswithoutborders_lib_sig documentation.

Visual Representation:

+----------------+-------------------+------------------+--------------------+-----------------+-----------------+---------------+
| Version Marker | Ciphertext Length | Device ID Length | Platform shortcode | Ciphertext      | Device ID       | Language Code |
| (1 byte)       | (2 bytes)         | (1 byte)         | (1 byte)           | (Variable size) | (Variable size) | (2 bytes)     |
+----------------+-------------------+------------------+--------------------+-----------------+-----------------+---------------+

version_marker = b'\x04'
platform_shortcode = b'g'
language_code = b'en'
device_id = b'...'
encrypted_content = b'...'

payload = (
   version_marker +
   struct.pack("<H", len(encrypted_content)) +
   bytes([len(device_id)]) +
   platform_shortcode +
   encrypted_content +
   device_id +
   language_code
)
encoded = base64.b64encode(payload).decode("utf-8")
print(encoded)