The guides are designed as an overview to get you up and running. You will need a different guide depending on what task you want to perform (i.e. initial handshake or sending messages). The code in the guides are as an example only. They can be copy and pasted, however you may need to make one or two changes get them up and running (for exmaple you will need to change some code to connect to your database etc).

See also:
Roadmap
Technical Details / RFC
Setup
Guides
References

Things you should know before you start

There are 2 roles: a Server Node and a User.

• The Server Node (Node) is a computer server that can send and receive messages.
• The User has an account with the provider of a Node, and can log in to send and view messages.

The protocol is designed to work between Server Nodes, each of which can send and receive messages. Internally, Nodes have two main components:

• The Sending Component, which handles outbound messages
• The Receiving Component, which accepts and processes inbound messages

While it's possible to run a Node in send-only or receive-only mode, most setups include both for full communication.

To set up a Node you will need a domain name / website and a database. At the very least you will need to set up your database (to store auth_codes and ident_codes, store messages and user data etc) and set up your code (to be able to send / receive messages).

See: Setup

Accounts use a numeric address ID, followed by an asterix, then the domain, like so: 06290345*domain.com or 123456*openmsg.io
Because the address ID (the part left of the asterix) is stored as a string, it can start with zeros. However all the characters in the ID must be numeric. For example, 000000*openmsg.io is a valid address. However abcdefg*openmsg.io is not valid.

The numeric ID is unique per domain. So 1234*domain-a.com is a different to 1234*domain-b.com

• The initial handshake: The initial handshakes establishes a trust between two Nodes. It proves to the receiving Node that the sending Node has permission to connect, and then send messages to the User. Durin the handshake an authorizations code and an encryption key are created and stored by each server.
• Sending a message: Messages are encrypted and a unique hash is created using the message, auth code and timestamp to ensure that the sender is geniune (has the auth code), and to prevent replay attacks and ensure message integrity.
• Receiving a message: The receiving server Node verifies the hash.
• Verifying the sender: Before accepting the message, the receiving server Node contacts the original sender's server Node (established during the handshake) to confirm it actually sent this message, proving the message came from the correct domain.

1. One-Time Handshake: Establishing Trust

Before two users can exchange messages, a one-time handshake must take place. This is initiated when:

• User B has a valid pass code and address for User A.
• User B’s server contacts User A’s server node to initiate the handshake.

During this handshake:

• A shared identification code is generated and stored by both servers.
• A shared authorization code is generated and stored by both servers.
• A shared encryption key is exchanged.
• The servers remember each other’s domain and user identity.

This step is mutual and must be completed before messaging can begin.

See: Handshake

• 1. User A requests a new one-use pass_code from their provider, Node A. Node A stores the pass_code for 1 hour for later validation in step 4b.
• 2. User A passes thier Openmsg address and the one-use pass_code on to User B. (User B could be a friend, or a website where User A enters their details into a form)
• 3. User A's openmsg_address and the pass_code are submitted to server Node B. Node B stores these values in a 'pending handshake' table for verification in step 4c.
• 4
• 4a. Node B sends the Openmsg address and the pass_code to Node A as proof User B is permitted to message User A. Node B also passes along User B's Openmsg Address
• 4b. Node A checks the pass_code is valid for User A. It then performs a cURL callback to the domain in User B's address.
• 4c. Node A receives the callback, checks its table of pending handshakes and responds with SUCCESS .
• 4d. Node A receives the SUCCESS response, the generates auth_code, itent_code and message_crypt_key (encyption key). It sends these to Node B. Nodes A & B both use these values for future message validation.

See: Handshake

1. Sending a Message: Encryption and Hashing

When User B wants to send a message to User A, User B’s server creates a message package containing:

• The encrypted message
• The encryption nonce

Node B then creates a message bundle consisting of:

• The message package
• The current UNIX timestamp
• A hash, created from:
• The private auth code
• The message package
• The timestamp
• A random salt

2a. Node B sends the message bundle to Node A

Note: The auth code itself is never sent. Both servers already have it from the initial handshake.

Receiving a Message: Verifying Authenticity

When User A’s server receives the message bundle, it performs the following checks:

• Recreates the hash using:
• Its own copy of the auth code (stored from the handshake)
• The received encrypted message, nonce, the salt, and the timestamp
• Validates that:
• The hash matches → proves the sender knows the auth code
• The timestamp is genuine and recent (e.g., within 60 seconds) → prevents replay attacks
• The message wasn’t altered → ensures data integrity

If these checks pass, the message appears authentic on the cryptographic level.

2b. Verifying the Sender’s Server

Before accepting the message, the User A’s server Node (the receiving Node) callsback to the domain in User B’s address to confirm it actually sent this message:

• A cURL request is made to User B’s Node with the hash.

2c. Node B confirms the message.

• If User B’s server acknowledges the message was just sent, it proves:
• The message came from the correct domain
• No other server is impersonating User B or Node B

Only then does User A’s server accept the message.

Note: The original server is established in the handshake, and is taken from the domain name in the User's address.

See: Sending Message

Standard MIT Licence.

Copyright 2025 Openmsg.io

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.