Architecture 🛠️

Paralino uses end-to-end encryption backed by Libsodium to protect your data before it even leaves your device.
Here, you can find out how all that mathemagic works.

---

Authentication Flow

Our authentication system is designed with a multi-layered security approach to enhance the protection of user credentials and data. Users can access Paralino through two primary methods:

• Email & Password Login: Standard signup and login using an email address and password. This method allows users to log in on multiple devices.
• Guest Login: Account details, including the password, are generated on the device, allowing users to use Paralino without the need for an email or password. However, this is restricted to a single device.

Account Creation

Upon selecting the preferred login method, users proceed with account creation. For guest accounts, credentials are generated directly on the device.

The user’s email and password are processed through a multi-step key derivation process to create secure login credentials.

1. First, the user’s password is combined with their email address as a salt and processed using Argon2id (64 MB with 3 rounds) to derive a Seed Auth Key.
2. The Seed Auth Key is then combined with the user’s password as a salt and processed again using Argon2id (64 MB with 3 rounds) to derive the Master Auth Key.
3. The Master Auth Key is further hashed using the BLAKE2b algorithm to produce a 256-bit Login Password.

The Login Password and email address are sent to the server as authentication credentials. For additional security, the server processes the Login Password through Argon2id (64 MB with 4 rounds) before storing it.

Finally, the server creates the user account, registering the email address and assigning a unique user ID.

User Keys

The next step is to generate cryptographic keys that will be used to encrypt and decrypt user data.

After successful account creation, the user’s unique ID is additionally combined and hashed with a randomly generated Data Salt. This constructs a salt which is used to derive the Master Data Key from the user’s password using Argon2id (128 MB with 5 rounds).

The Master Data Key is hashed using BLAKE2b to generate a 256-bit Key Encryption Key, which is then used to encrypt the Master Key.

Key Generation

The user’s device generates the following keys:

• Master Key : A Random 256-bit Master Key used to encrypt the user’s data and identity keys.
• Identity Keys : A pair of Private and Public Keys used for user authentication and secure key exchange with other users.

The Master Key is encrypted using the Key Encryption Key with the XChaCha20-Poly1305 encryption algorithm, ensuring confidentiality and integrity.

Similarly, the Identity Keys are encrypted using the Master Key, also with XChaCha20-Poly1305, to ensure secure storage.

User Key Payload

The User Key Payload is securely stored on the server and contains:

• Encrypted Master Key
• Encrypted Identity Keys
• Plain Text Public Key: The unencrypted public key for identification purposes.
• Login Algorithm Details: Argon2id parameters used during key derivation for login credentials.
• Data Algorithm Details: Argon2id parameters used during key derivation for cryptographic keys.
• Data Salt: The original part of the salt used in deriving the Master Data Key.

Here is the full user account creation flow:

By following this authentication flow, the system ensures that user credentials and data are protected at every step, utilizing industry-standard cryptographic practices to safeguard against unauthorized access.

Login Flow

• Email & Password Login: Enables users to securely log in on multiple devices with their registered credentials.
• Guest Login: Credentials are stored only on the device, thus guest users are not able to log in on multiple devices.

Login Process Overview

When users provide their login details (email and password), the system follows these steps to authenticate the user:

Validating Login Details

The entered email is sent to the server, which checks if the account exists.

• If the account exists: The server retrieves the corresponding login algorithm details.
• If the account does not exist: Dummy details are returned for specific input to ensure no information about account existence is provided.

Deriving Login Keys

The login process involves multiple key derivation steps:

• The Master Seed Key is derived using the login algorithm with the user’s password as payload and email as salt.
• The Master Auth Key is derived using the login algorithm with the Master Seed Key as payload and password as salt.
• The Login Password is derived by hashing the Master Auth Key using BLAKE2b to produce a 256-bit key.

Verifying Credentials on the Server

The Login Password and email are sent to the server for authentication. If the credentials match, the user is logged in and granted access to their account data.

Decrypting User Keys

After successful authentication, the encrypted user keys are retrieved and decrypted on the device.

1. Retrieving the Encrypted Key Payload
   The User Key Payload, stored on the server, is sent to the device.
   This includes: Encrypted Master Key, encrypted Identity Keys, data algorithm details, and other key parameters.

2. Decrypting User Keys
   The user’s password, along with the User ID and Data Salt from the User Key Payload, is used to derive the Master Data Key. The Master Data Key is hashed using BLAKE2b to produce a 256-bit key. This key decrypts the Master Key using XChaCha20-Poly1305.
   The decrypted Master Key is then used to decrypt the Identity Keys (Private and Public Key Pair) with the same algorithm. These keys are stored locally in secure storage for subsequent use in communication and encryption.

Here is the full user login flow:

---

Password Change and Master Key Rotation

When a password is changed, a new Master Key is generated and encrypted with the updated password. The procedure for generating and encrypting the new Master Key is exactly the same as the one used during initial account creation.
The Identity Keys remain unchanged throughout the process since they guard user identity.
Older Master Keys are versioned and preserved as backups, encrypted with the new Master Key using the XChaCha20-Poly1305 algorithm, ensuring continued access to data encrypted with previous keys. All subsequent cryptographic operations will utilize the new Master Key.

---

App Session Keys

On every user login or account creation, a new symmetric key (Session Key) is generated. This key is used to encrypt the Master Key and Identity Keys before saving them locally on the device.

The Session Key is stored securely on the user’s device along with the encrypted Master Key and Identity Keys:

• Android: Stored in EncryptedSharedPreferences.
• iOS: Stored in Keychain.

Using an extra session key to encrypt other keys provides an additional layer of encryption and security. It also ensures that your actual keys are always stored in an encrypted form and are only decrypted when needed.

---

Paralino.ID

The Paralino.ID is an 8-character code that serves as the user’s unique, public identifier within the Paralino ecosystem. It is used for connecting with other users and facilitating secure communication while ensuring anonymity and privacy.

Paralino.ID is generated using cryptographically secure methods and is not known to the server.
It is not considered very secret since, since in the end it is meant to be shared with others, but we have still gone through the process of engineering it in a way that limits what information the server knows.

A Secure Random Generator creates a unique 8-character Paralino.ID for each user.

The Paralino.ID is input into key derivation functions to generate two different secure keys:

• ID Auth Key: Derived using Argon2id (32 MB with 2 rounds) and hashed once again with BLAKE2b, serving as the Paralino.ID identifier.
• ID Encryption Key: Derived using Argon2id (32 MB with 2 rounds) with salt in the form of User ID, used to encrypt payloads during communication.

This ensures that the only way to get info about the user (user name and image, plus user exchange keys) is to know both the User ID and the Paralino.ID.

Paralino.ID is also encrypted with the user’s Master Key to ensure it is readable to the current user.

The user’s unique details, such as User ID, Public Identity Key, and User Name/Image, are included in the Paralino.ID code Payload.
This payload is encrypted using the ID Encryption Key and the XChaCha20-Poly1305 algorithm, ensuring data confidentiality.

When reading Paralino.ID on another device, the server returns the user’s public key (which is stored in plain text), User-ID, and the encrypted Paralino.ID payload. After that payload is decrypted, the device can also verify that the User-ID and Public Key match the ones provided by the server. Combined with the fact that the server does not know the user’s Paralino.ID, it cannot easily pretend to be another user nor can it give you false information.
Your device verifies all this information locally; you just need to make sure that the Paralino.ID you entered matches the Paralino.ID on your friend’s device.

This is not a replacement for manual contact verification (e.g., with safety numbers in Signal) since the Paralino.ID code is too short (8 characters), but it is a quick and easy assurance you are in contact with the correct person.

We plan to add actual contact verification at a later point. This will allow you to manually check and compare public key signatures, ensuring better confidentiality.

The encrypted Paralino.ID code Payload is securely transmitted to and stored on the server, along with the ID Auth Key, Pre-Keys, and encrypted Paralino.ID.

Pre-Keys

Each Paralino.ID has multiple Pre-Keys assigned to it. The number varies and is replenished from your device if they are running low. Pre-Keys in this case work similarly to Pre-Keys in Signal.

• A pair of Pre-Key Pairs (random private and public keys) is generated locally for data exchange.
• These keys are then encrypted with the user’s Master Key, allowing access to the private key only to the Paralino.ID owner.
• The public Pre-Key is signed using the user’s private signature key to authenticate the key exchange process.
• Pre-Key Key ID is derived with a BLAKE2b hash and serves as an internal Pre-Key identifier.
• The Pre-Key payload contains the Paralino.ID, Key ID, User-ID, and signed Pre-Key public key. That is then encrypted with the ID Encryption Key.

Whenever someone tries to add you to a group or reads your Paralino.ID, one Pre-Key is fetched and invalidated.
A Pre-Key can only be read and used once, and it contains keys necessary for adding you to a group and for a first-time data exchange.

Managing Paralino.IDs

You can disable your Paralino.ID at any time directly in the app. Doing so will invalidate all Pre-Keys and remove the Paralino.ID code Payload.

You will then not be able to join any new group, and no one will be able to read your info with Paralino.ID.
You can at any point enable your Paralino.ID if you wish to join another group.
Paralino.ID cannot be deleted. If you delete your account, the ID Auth Key (hash of your Paralino.ID) is stored on the server, ensuring no other user can ever have the same Paralino.ID.

At the moment, only one Paralino.ID is active at a time, but we will soon enable support for multiple simultaneously active Paralino.IDs. This will also allow you to have different names and images in different groups and attach different data to different Paralino.IDs.

---

Group Encryption

Creating Groups

When a user creates a new group, several layers of encryption and signatures are applied to ensure the security and integrity of the group and its members.

Key Generation

The creator’s device generates the following keys:

• Group Master Key: A symmetric key used to encrypt group-wide data (name, image, etc.) and member profiles.
• Exchange Key Pair: A private and public key pair used for secure key distribution and membership verification within the group.

Data Encryption

The group’s metadata (name and image) and the creator’s member profile (name and image) are encrypted using the Group Master Key with the XChaCha20-Poly1305 algorithm.

Identity and Membership Verification

To prove identity and secure the membership:

• Public Key Hash: The creator’s Public Identity Key is hashed using BLAKE2b to derive a 256-bit key.
• Member Verification: This hash is then signed with the creator’s Private Identity Key using Ed25519.
• Membership Key Signature: The public part of the Exchange Key Pair is also signed with the owner’s Private Identity Key to create a Signed Public Membership Key.

Group Integrity

A Group Integrity Object is created to prevent unauthorized changes to the group structure. It includes:

• The Signed Public Membership Key.
• A Member ID Hash (the creator’s User ID hashed with BLAKE2b).
• The Signed Member Verification.

This entire object is then encrypted using the user’s Personal Key with XChaCha20-Poly1305. This one is available only to the group owner, but every other member will also have its own version of it.

Secure Key Distribution

Finally, a Group Creation Payload is sent to the server, containing:

• Encrypted & Signed Group Key: The Group Master Key is encrypted and signed for the owner using X25519 and XSalsa20-Poly1305.
• Encrypted Exchange Keys: The Exchange Key Pair is encrypted with the user’s Personal Key and available only to the group owner.
• Encrypted Data: All encrypted group metadata, member profiles, and the integrity object.
• Signatures: The signed membership key and member verification.

This multi-step process ensures that only authorized members can access actual group data, and the server cannot modify the group’s structure or membership without detection.
Mobile app checks this verification during every location update, key rotation, or other similar operations. If anything is missing, tampered with, or if there are slightest integrity changes, the group and/or member will be considered unverified and the app will not allow users to join the group or to continue sharing location data. If integrity itself is valid, further checks are performed to determine if the device needs to do key rotation or not.
Visually, users will also see the warning next to a group or specific member in the app if integrity of the group or member is invalid.

Here is the full group creation flow:

Adding Members

Currently, only the group owner can add new members. This process relies on the Paralino.ID system and Pre-Keys to securely share group keys without the server ever seeing them.

Fetching and Verifying Paralino.ID

The owner enters the potential member’s Paralino.ID, which triggers the retrieval of the data from the backend.

• The device derives the ID Encryption Key locally from the entered Paralino.ID.
• This key is used to decrypt the payload, which contains the member’s name and image, Public Identity Key, User ID, and a Signed Pre-Key (used as the public membership key).
• The device compares the decrypted data with the plain-text information provided by the server (User ID, Public Identity Key) and also verifies that the entered Paralino.ID matches the one in the payload.
• This ensures that the server cannot easily impersonate a user or provide false keys.

Confidentiality and Verification

While Paralino.ID provides a layer of confidentiality because it is unknown to the server, its 8-character length is not sufficient to guarantee equal degree of verification as manual contact verification.

Note: This process is a precursor to Manual Contact Verification, which will be added later to allow users to manually confirm and compare public key signatures for absolute certainty.

Secure Key Distribution

If all verification steps are successful, device can proceed with key distribution. To allow the new member to access group history, the owner’s device:

• Retrieves all Currently used Group Keys.
• Encrypts each key using X25519 and XSalsa20-Poly1305:
  • Signed with the owner’s Private Membership Key.
  • Encrypted with the new member’s Public Membership Key (retrieved from the verified payload).

Updating Group Integrity

The owner also updates their own Group Integrity Object to include the new member information. This ensures that the group structure remains verifiable:

• Member ID Hash: The new member’s User ID is hashed using BLAKE2b.
• Signed Membership Key: Public Pre-Key signed with the member’s private Identity Key.
• Member Verification: The member’s Public Identity Key is hashed and signed with the Group Owner’s Private Identity Key using Ed25519.
• The updated integrity object is then encrypted using the owner’s Personal Key with XChaCha20-Poly1305.

Member Profile Data

The new member’s profile data (name and image retrieved from the encrypted payload) is then encrypted with the currently Active Group Key. The final payload, containing the encrypted group keys, the updated integrity signature, and the encrypted member details, is then transmitted to the server. Other group members (including the new one) will update their own integrity objects locally when they next rotate their keys.

Here is the full member creation flow:

Removing Members

Members can be removed from a group either by leaving willingly, being removed by the group owner, or when their account data is deleted.

When a member is removed, all their associated data is immediately purged from the group, including:

• Encrypted membership and exchange keys.
• Device information and historical location data.
• Member profiles and signatures.
• All permissions are revoked for the removed user.

Group Integrity and Key Rotation

The addition or removal of a member triggers an immediate change in the group’s integrity state. And since every cryptographic operation or location update requires up-to-date integrity check, that is detected immediately and the following actions are performed:

• Group Key Rotation: The group owner generates a new Group Master Key.
• Membership Key Rotation: The owner and all remaining members rotate their own Key Exchange Keys.
• Sender Key Rotation: If a device is actively sharing its location, it will also rotate those keys.
• Location History Key Rotation: If the device has location history sharing enabled, the location history keys are also rotated to ensure the removed member cannot access future history data.

Key rotation is also performed periodically even if no specific event occurs to ensure that all members have the constantly fresh keys.

This process ensures that the group remains verified and secure, with all remaining members updating their local integrity objects to reflect the new membership structure. Doing proper cryptographic operations is crucial to ensure that all your location data is protected with forward secrecy. This means that even if server is compromised:

• New members cannot decrypt previous location data.
• Removed members cannot decrypt future location data.
• Only verified members can decrypt current location data.

Server itself does provide one layer of trust by ensuring each member has permissions to only access the encrypted data they are allowed to. End-to-end encryption ensures that even if server is compromised, no one can decrypt that data.

Location Encryption

Location data in Paralino is protected using a Sender Key mechanism, ensuring that only authorized users themselves in a Personal Space or verified members in a Group can decrypt real-time and historical location updates.

Sender Keys and Sharing Sessions

For every sharing session, the device generates a new Sender Key (a symmetric 256-bit key). This key acts as a base, key derivation key. Sender keys are not reused across groups, members, and personal spaces, so each and every device has its own unique Sender Key. From that Sender Key, the device derives a new, temporary, symmetric 256-bit Location Key for each and every location and/or device status update. Each recipient device must derive the Location Key using the Sender Key with attached Key ID locally, to decrypt the data.

Location Key Distribution

• Groups: The key is distributed to each verified member using asymmetric encryption (X25519 and XSalsa20-Poly1305). It is encrypted with the recipient’s Public Key Exchange Key and signed with the sender’s Private Key Exchange Key.
• Personal Space: The key is encrypted using the user’s Master Key. This encrypted key is stored on the server and is accessible only to the user, allowing their other devices to retrieve and decrypt it.

Here is the location sharing flow:

Local Group Integrity

In group settings, the device generates and stores its own version of the Group Integrity Object locally for every sharing session.

• The device continuously monitors the group’s state for any changes in membership or integrity.
• If a discrepancy is detected (e.g., a member or device is added or removed, or a signature is invalidated), the device will either immediately rotate all keys or stop the sharing session entirely.

Location History Encryption

If the user has enabled location history sharing, process is similar to the location sharing flow, but with separate keys used to encrypt location history data.

History Sender Key Generation

Similar to the Sender Key, a separate History Sender Key is generated for every sharing session (also separately for every group and personal space). This key also serves as a key derivation key. From it, device derives a new, temporary, symmetric 256-bit Location History Key for each and every location history update.

New History Sender Key is generated for the following events:

• Sharing sessions starts with history sharing enabled
• A member joins a group
• A member leaves a group
• Automatically after 14 days (if history sharing is enabled for the group)

Location points are first encrypted with user’s Master Key with the XChaCha20-Poly1305 algorithm and stored locally along with their own verification and currently active History Sender Key. Just like sender keys, History Sender Keys are also distributed to verified members of the group using asymmetric encryption with X25519 and XSalsa20-Poly1305 algorithm. In Personal Space, the History Sender Key is encrypted with the user’s Master Key and sent to the server during the history upload process. In groups, keys are encrypted with the recipient’s Public Key Exchange Key and signed with the sender’s Private Key Exchange Key.

To ensure that only members who were present and verified at the time of the specific location update can decrypt that history, History Sender Keys are stored with their own verification and each stored location point belongs to specific History Sender Key. Therefore, specific History Sender Key is only distributed to the member who was present and verified at the time of the specific location update. This way, new members who join the group later will not be able to access nor decrypt any history points stored before that device detects the new member. And since keys are rotated regularly, any future location updates can only be decrypted by currently verified members.

Place Encryption

Places allow group members to define custom areas and see when others enter or leave them. Place data is also end-to-end encrypted and all processing is done locally on the device.

When a user creates a place, they enter a name, icon and geographical location. The device generates:

• Encrypted Place Data: Name, icon and geographical location, encrypted with the Group Master Key using XChaCha20-Poly1305.
• 32-character random event seed: A cryptographically secure random value, also encrypted within the same payload.

Place Alerts Privacy

When a device detects that a place event occurred (user enters or exits a place), the device processes it further locally. To allow the server to relay events without learning what happened, the device only sends a hash derived from the place seed and event type to the server.

When a device is notified of a place event:

• The device decrypts the place data locally and thus has access to the event seed.
• The device generates the hashes again using the seed and possible event combinations.
• When the locally generated hash matches the hash from the notification, the device knows what occurred and can show whether the user entered or left the place.

Because the server never sees decrypted place data, it cannot determine whether someone entered or left the place.

Push Notifications Privacy

Push notifications, regardless of the service used to deliver them, are only “pings” to wake up the target device. They do not contain any data, ensuring maximum privacy of all possible events in Paralino.
The currently used push notification services are:

• Apple Push Notification Service (APNS) on iOS version
• Firebase Cloud Messaging (FCM) on Google Play Android version
• Direct WebSocket connection to our servers on de-googled Android version

Whenever significant event in the app occurs, like when new place is created, new member joins a group, etc., the server creates a database entry for that event for each device in the group or in personal space. It also sends an empty push notification using the service specified above.
When the device wakes up because of that push notification, it fetches the necessary list of notifications from the server. Retrieved notification data contains only the type of the event, not actual content of the notification. Then, depending on the type of the event, device decrypts the necessary information to display a notification locally on the device.

This way, no other party can see what notifications are sent to your device and when using direct connection on Android, there are no third parties involved at all.