RelaySMS - Android

---

Connecting the world, one SMS at a time.

Contents

• About
• Encryption and Security
• Token Storage and Vault
• Getting Started
  • Prerequisites
  • Installation
• Build Instructions
  • Building from Source
• Contribution Guidelines
• Publishing Payload
• Platform Specific Publications
• Resources and Further Reading
• Contact

About

RelaySMS (also known as swob, short for SMSWithoutBorders) is a tool that lets you send secure online messages via SMS without needing an internet connection. RelaySMS allows you to stay connected even when offline by securely storing OAuth2 tokens for services like Gmail, Twitter, and Telegram in encrypted online Vaults.

Gateway Clients

RelaySMS utilizes gateway clients (identified by their MSISDN) to route SMS messages. You can manage these gateway clients within the app, allowing you to add new clients or switch between existing ones. To learn more about gateway clients and how they work, refer to the following resources:

• Contributing: Gateway Client
• Gateway Clients Guide
• API V3: Get Gateway Clients

Encryption and Security

RelaySMS employs robust encryption methods to protect your data and ensure secure communication. For a detailed explanation of the cryptographic methods used in the vault, please refer to the security documentation.

• AES (Advanced Encryption Standard): Encrypts and decrypts data at rest in the vault.

• Fernet Encryption: Fernet encryption with a 32-byte key is used for encrypting and decrypting identity tokens used by the vault.

• HMAC (Hash-based Message Authentication Code): Generates and verifies HMACs for unique values in the vault.

• Double Ratchet Algorithm: The Double Ratchet algorithm is used to provide End-to-Vault encryption with perfect forward secrecy for secure messaging.

These cryptographic methods work together to provide a layered security approach, safeguarding your data and communications within the RelaySMS ecosystem.

Token Storage and Vault

RelaySMS utilizes a secure vault to store OAuth2 tokens for various services. These tokens allow you to access your accounts and send messages through these services without repeatedly entering your credentials.

Here's how the vault works:

1. Token Encryption: When you grant RelaySMS access to a platform (e.g., Gmail), the app receives an OAuth2 token. This token is immediately encrypted using AES-256 with a unique key.

2. Vault Storage: The encrypted token is then stored in the RelaySMS vault. The vault itself is protected by various security measures, including access controls and encryption. You can learn more about the vault specifications in the documentation.

3. Token Retrieval: When you need to send a message through a service/platform, RelaySMS retrieves the encrypted token from the vault. It then decrypts the token and uses it to authenticate with the platform (e.g Gmail).

This secure token storage and retrieval process ensures that your sensitive credentials are never stored in plain text and are protected from unauthorized access.

Getting Started

Prerequisites

• Android Studio (latest stable version recommended)
• Android SDK
• Git
• Basic understanding of Android development and Kotlin

Installation

You can install RelaySMS directly from the following sources:

• F-Droid: Link to F-Droid
• Google Play Store: Link to Google Play Store

Build Instructions

Building from Source

1. Clone the repository:

   git clone https://github.com/smswithoutborders/SMSWithoutBorders-App-Android.git

2. Open the project in Android Studio.
3. Create a release.properties file in the project's root directory (refer to release.properties.example for a template).
4. Build and run the app on your device or emulator.

Contribution Guidelines

We welcome contributions from the community! Here's how you can get involved:

1. Clone the repository.
2. Create a new branch from the dev branch for your feature or bug fix.
3. Make your changes and commit them with descriptive messages.
4. Push your changes and submit a pull request to the dev branch

Please ensure your code follows our coding style guidelines and includes appropriate tests.

Publishing Payload

RelaySMS uses a specific payload structure for publishing messages. Refer to the code snippet below for details on packing and unpacking the payload:

import struct
import base64

platform_letter = b'g'
encrypted_content=b'...'
device_id=b'...'

payload = struct.pack("<i", len(encrypted_content)) + pl + encrypted_content + device_id
incoming_payload = base64.b64encode(payload)

# unpacking in Python
payload = base64.b64decode(incoming_payload)
len_enc_content = struct.unpack("<i", payload[:4])[0]
platform_letter = chr(payload[4])
encrypted_content = payload[5 : 5 + len_enc_content]
device_id = payload[5 + len_enc_content :]

# getting header from published messages
encrypted_payload = base64.b64decode(encrypted_content)
len_header = struct.unpack("<i", encrypted_payload[0:4])[0]
header = encrypted_payload[4: 4 + len_header]
content_ciphertext = encrypted_payload[4 + len_header:]

Platform Specific Publications (Encrypted Content)

RelaySMS supports publishing encrypted content to various platforms with specific formatting:

""" Email (Gmail etc)
"""
# to:cc:bcc:subject:body

""" Messages (Telegram etc)
"""
# to:body

""" Text (X; Twitter etc)
"""
# body

Resources and Further Reading

• Official Documentation: https://docs.smswithoutborders.com/
• Blog: https://blog.smswithoutborders.com/
• GitHub Repository (Backend): https://github.com/smswithoutborders/SMSwithoutborders-BE

Special thanks to:

• @mikropsoft for adding Turkish localization.

Contact

• Website: https://relay.smswithoutborders.com/
• Email: developers@smswithoutborders.com
• X(Formerly Twitter): @RelaySMS

We appreciate your interest in RelaySMS. Don't forget star this repo :)