How Can We Help?

GiniConnect Protocol: Secure & Trustless Communications (Tech Specs)

You are here:
< Back

Before Gini released the open source GiniConnect Protocol, there was no simple way for people to communicate securely without centralized communication tools. When we say "centralized", we mean that every time you communicate with somebody, your private data is routed through a centralized server infrastructure controlled by a centralized entity before the recipient receives it. You might trust that entity today. But how do you know if that entity will be trustworthy tomorrow?

What's Wrong with Trusted Systems? Trusted systems become a problem when corrupt and/or tyrannical governments and giant, profit-obsessed corporations act in their own self-interest to collude against their citizens/users.

Is Your Existing Messaging App Centralized? All other messaging apps today (including WhatsApp, Signal, iMessage, Telegram, Facebook, Keybase, Slack, Discord, Skype, Hangouts . . .) are fully centralized services. Additionally, most chat apps store your phone number and other personal details, which gives the company that controls those services significant power over you and your ability to communicate freely.

Gini is Different. The secure, decentralized GiniConnect Protocol is fundamentally designed to create the most secure and private communication experience technically possible. The GiniConnect Protocol is completely trustless, which means you don't need to trust it. Specifically, if the Gini servers were hijacked by a tyrannical government, compromised by a malicious hacker, or abused by one of Gini's own employees, there's no way that they could harm any Gini stakeholders.

GiniConnect is Secure by Design. "Secure by design" means the security guarantees provided by the GiniConnect Protocol do not depend on any unproven cryptography or unproven mathematics. In fact, all the cryptographic primitives used in the GiniConnect Protocol have been proven for years in many real-world applications.

GiniConnect is Technically Unbreakable. We designed the GiniConnect Protocol to make it technically unbreakable by structurally preventing any party (including the Gini Foundation) from ever having access to any information that could be exploited. There is no centralized entity storing phone numbers, emails, user IDs, passwords, credit card numbers, or any other exploitable data. No matter how powerful a computer is (even quantum computers) and no matter how powerful an attacker is, without exploitable data, there's nothing to exploit. This is why decentralized systems are so powerful and secure. This is why Gini is different.

For a deeper understanding of why this is true, below we've provided a functional summary and diagram of how the GiniConnect Protocol works. Keep in mind that the entire protocol is fully automated and it securely connects users within a few seconds, but we provide a detailed technical description here to help stakeholders understand how the protocol actually works under the hood. (You can also see a less technical overview of how GiniConnect is powering Gini's Account Center software.)

GiniConnect Protocol: Secure & Trustless Communications by

Meet Alice and Bob

Since the early days of modern cryptography in the 1970s, virtually every encryption protocol begins by meeting our friends Alice and Bob. Let's say Alice and Bob want to securely, simply and privately exchange their contact details, Gini payment addresses, and communicate privately over an encrypted peer-to-peer channel without the Gini Foundation or any other third-party service constantly in the middle. This is how we accomplish that. . . .

Gini Signaling Service

Alice knows Bob, but Alice's computer needs a way to find Bob's computer in the vast ocean of computers on the Internet. In fact, every node on a network needs to know the IP address of other nodes before they can communicate. Additionally, there are many routers, firewalls and other network devices between Alice and Bob. Without a way to connect Alice and Bob through this ocean of network devices, how will they ever communicate?

Overcoming the Trusted Connection Bootstrapping Problem. At Gini, we call this the "Trusted Connection Bootstrapping Problem". Most engineers take the easy way out and create a completely centralized server infrastructure that forces all their users to constantly communicate through their centralized services. By centralizing everything, they can ignore many security and authentication issues. However, everything we do at Gini is focused on creating truly private and decentralized tools and systems. Thus, the easy centralized way is not acceptable. But, we still need to overcome the Trusted Connection Bootstrapping Problem.

Solution: The Gini Signaling Service. The Gini Signaling Service (GSS) is the solution. The sole purpose of GSS is to help Alice and Bob overcome the Trusted Connection Bootstrapping Problem. To do this requires a one-time connection to GSS so that GSS can help Alice and Bob find each other. After that, Alice and Bob are able to connect directly to each other at any time in the future without GSS in the middle.

Now that we have met Alice, Bob and GSS, let's dive into the actual GiniConnect Protocol.

Flash Code Stage

The Flash Code (FC) Stage is the first stage within the GiniConnect Protocol. This stage verifies that two peers have the same shared secret, which no other entity could possibly know within the strict rules of the GiniConnect Protocol. The protocol begins. . . .

1. Create Flash Code

Alice creates a simple, human-friendly Gini FC from within her secure and user-friendly Gini software. The FC is easy for humans to read (e.g.: "5H7M8G"), but as you will see, the GiniConnect Protocol makes it technically impossible for hackers and tyrannical governments to attack GSS to discover the FC (even if they have quantum computers).

2. Alice Submits FC Hash to GSS

Alice hashes the FC; opens a secure, TLS-encrypted, anonymous WebSocket (WS) connection with GSS; and sends the FC hash to GSS. The FC is hashed so even GSS does not know the FCs actual value. (You will see why this is important later.) The hash transforms the human-friendly FC ("5H7M8G") into the following long sequence of random characters:


GSS saves the random FC hash and Alice's anonymous WS session for up to 3 minutes in a table called NewConnections with the following fields:

FlashCode (Text, Primary Key, Required)

MFC (Text) // Mutated Flash Code (MFC; more on this later)

Offer (Text) // The WebRTC "Offer" sent by Alice (as defined by the WebRTC spec; more on this later).

Answer (Text) // The WebRTC "Answer" sent by Bob (as defined by the WebRTC spec; more on this later).

Session (Text, Required) // The anonymous session path for each client connection to GSS.

TempKeys (Text) // Temporary public keys submitted by anonymous peers (more on this later).

Timestamp (Integer, Required)

For maximum privacy, FC hashes, offers, answers and all session data associated with each anonymous connection expire and are immediately deleted from GSS after 3 minutes

3. Alice Shares FC with Bob

Alice trusts Bob because they are already friends. Alice gives Bob the simple plaintext FC via another trusted channel (e.g., voice call, Signal, WhatsApp, ProtonMail, etc.).

4. Bob Submits Hashed FC

Bob takes the simple FC from Alice and enters it into Bob's GiniConnect box in his Gini client, which then hashes it; opens a secure, TLS-encrypted, anonymous WebSocket (WS) connection with GSS; and sends the FC hash to GSS.

5. FC Hash Match Verification

GSS searches the NewConnections table to see if Bob's FC hash matches any existing FC hashes. If a matching FC hash is found, we move on to the Peer Verification Stage. If no match is found, it means Bob is a hacker or trying to submit an expired FC. In either case, GSS can safely ignore Bob, terminate Bob's WS session (with error message: "No matching Flash Code") and terminate the GiniConnect Protocol.

Peer Verification Stage

The previous FC Stage verifies two facts:

(1) At least one party (Alice) is legitimate. (She wouldn't initiate the FC Stage to invite a trusted friend to connect with her if she wasn't legitimate within the context of the protocol. Whether she has good intentions for Bob or not is another question, but that's a personal relationship issue, not a protocol issue.)

(2) There are two FC hashes that match.

However, the FC Stage does not actually verify whether Bob is a legitimate peer. In this theoretical attack scenario, "Bob" could be a hacker or tyrannical government that has hijacked GSS. In this case, the attacker could scan incoming FC hashes from the inside, wait for Alice's FC hash, then quickly initiate a WS session with GSS before the real Bob, then submit the same FC hash to GSS even without knowing the actual FC value. That would trick Alice into believing the attacker was her trusted friend. This would enable the attacker to perform several other actions that could potentially reveal Alice's identity to the attacker.

This attack is only possible if GSS is hijacked, which is a very low-probability attack. However, this theoretical attack reveals one of the fundamental reasons why it's important to design secure and decentralized protocols that don't require trust in centralized entities. This is why we have the following steps within the Peer Verification Stage of the GiniConnect Protocol.

Assuming GSS has already found a matching FC hash, GSS now has two independent and anonymous WS connections open with Alice and Bob. Now the GiniConnect Protocol continues. . . .

6. Peers Send Temporary Public Keys to GSS

Alice and Bob send their temporary public keys (TPKs) to GSS over their existing TLS-encrypted WS channels. These are one-time TPKs generated only for the Peer Verification and Peer Connection Stages. The TPKs are long random sequences of characters, which do not reveal any identity information at all. Using TPKs prevents an attacker from learning anything about Alice and Bob that could be used to identify them in the future.

7. GSS Relays Temporary Public Keys

GSS relays Alice’s TPK to Bob and GSS relays Bob’s TPK to Alice.

8. Mutate FC Into MFC

Recall the simple, human-friendly FC was "5H7M8G". When that FC was hashed and sent to GSS the first time, it looked like this:


In virtually all real-world scenarios, that long hash would be very secure. But in the theoretical attack scenario described above, that hash might be captured in a hijacked GSS. To eliminate that risk, this time both Alice and Bob independently add the plaintext FC to itself so that it looks like this: 5H7M8G5H7M8G. In plaintext, this is a simple duplication operation, but after Alice or Bob encrypt it with their respective TPKs using the unique sequence "5H7M8G5H7M8G" as the nonce, it's a totally different random sequence of characters:


That means GSS can't read the simple mutated FC (MFC) because it is now encrypted and only Alice and Bob's private keys can decrypt it. Since GSS never has access to any user's private keys, it's technically impossible for GSS to know the actual MFC value, but Alice and Bob can easily decrypt and verify it. Additionally, recall that GSS could never see the original FC value because it was always hashed by Alice and Bob before they sent it to GSS. Thus, GSS can never know what sequence of characters to duplicate in the simple pre-encryption FC duplication operation. That means GSS can never know the unique nonce that is required to decrypt the MFC, even if an attacker hijacked GSS and replaced a peer's TPK with the attacker's TPK.

9. Peers Send MFCs to GSS

Alice and Bob confidently send their encrypted MFCs to GSS and they know that GSS will never be able to read the actual MFC values.

10. GSS Relays MFCs

GSS relays Alice's encrypted MFC to Bob and GSS relays Bob's encrypted MFC to Alice.

11. Peers Verify Each Other

If the MFCs match when Alice and Bob decrypt them on their local machines, then they know two new facts:

(1) They are both legitimate peers.

(2) No attacker has hijacked their connections.

Now the peers can enter the next stage of the GiniConnect Protocol. However, if the MFCs do not match, that means a hacker or tyrannical government has attempted to impersonate Bob either on Bob's client side or from inside GSS. In either case, the peers reject the MFCs (with error message: "Incorrect MFC"). GSS relays the error message to both peers and terminates the WS session and the GiniConnect Protocol.

Peer Connection Stage

Alice and Bob are now securely authenticated. The GiniConnect Protocol continues. . . .

12. Generate Encrypted WebRTC Offers/Answers

Alice encrypts her WebRTC Offer with Bob’s TPK and Bob encrypts his WebRTC Answer with Alice’s TPK. This protects their WebRTC Offers/Answers from potential attacks.

Example Code for Creating, Encrypting & Decrypting WebRTC Offers/Answers. Below is an example of how to encrypt/decrypt Offers/Answers on the client before they are sent to GSS.

// Create Bob's WebRTC Offer
let OfferBob = {
    'WebRTCField1': 'data',
    'WebRtcField2': 'data',
    'WebrtcField3': 'data',

// Bob encrypts his Offer with a random nonce, his private key and Alice's TPK.
let nonce = randombytes_buf(crypto_box_NONCEBYTES)
let EncryptedOfferBob = crypto_box_easy(OfferBob, nonce, alice.publicKey, bob.privateKey)

// Alice decrypts Bob's Offer with the same nonce, her private key and Bob's TPK.
let DecryptedOfferBob = crypto_box_open_easy(EncryptedOfferBob, nonce, bob.publicKey, alice.privateKey)

13. Send WebRTC Offers/Answers to GSS

Through their existing anonymous TLS-encrypted WS connections with GSS, Alice sends her encrypted WebRTC Offer to GSS & Bob sends his encrypted WebRTC Answer to GSS. Then GSS temporarily saves their encrypted Offers/Answers in the previously specified NewConnections table.

14. GSS Relays WebRTC Offers/Answers

GSS relays Alice’s encrypted WebRTC Offer to Bob and GSS relays Bob’s encrypted WebRTC Answer to Alice.

15. Reveal WebRTC Offers/Answers

Bob decrypts Alice’s WebRTC Offer with Alice’s TPK and Alice decrypts Bob’s WebRTC Answer with Bob's TPK.

16. Establish Secure P2P Connection

Alice and Bob now know each other’s private WebRTC coordinates and they can make a direct, DTLS-encrypted, private peer-to-peer (P2P) connection without GSS in the middle of their communications.

Contact Sync Stage

Now that the peers are authenticated and connected, they can begin exchanging data over the secure P2P channel.

17. Save Connection Details

Alice and Bob's private Gini clients (not GSS) save their new trusted WebRTC connection details to their respective WebRtc metadata tables associated with their respective contact records. This ensures that Alice and Bob can establish direct, private, encrypted, P2P chat, voice, video and data communications with each other in the future without any middlemen.

18. Secure Contact Sync

Over the direct, private, encrypted, P2P channel, Alice sends her vCard and permanent public key to Bob. Bob also sends his vCard and permanent public key to Alice. (Note: Permanent private and public key pairs are already created for every Gini user during the Gini Account Center software installation process.)

19. Update Contact Lists

The users' respective vCard details now appear in their Gini Account Center contact lists.

20. Purge All Data from GSS

All the metadata produced through the entire GiniConnect Protocol is anonymous, but to provide the highest level of privacy for our Gini users, all data associated with each connection bootstrapping event is purged from GSS immediately after each successful connection or after 3 minutes, whichever occurs sooner.

Ongoing P2P Communications Stage

The previous stages are all necessary to overcome the Trusted Connection Bootstrapping Problem. Now that Alice and Bob have their respective connection details, they can reconnect directly and securely any time without GSS in the middle. However, to ensure perfectly secure communications, each time they reconnect to each other, Alice and Bob must generate and exchange a new shared secret (SharedSecret), which is easily and automatically generated on their local machines without GSS.

SharedSecret Generation

The SharedSecret is a random secret session key that each Gini client automatically generates at the beginning of every new peer connection with, e.g.:

crypto_kx_client_session_keys(alice.pubkey, bob.pubkey, initiator.privkey)

This encryption function is based on the strong BLAKE2B-512 cryptographic hash function. The arguments to crypto_kx_client_session_keys() are the two peers' existing Gini permanent public keys and the Gini private key of the session initiator.

The "session initiator" is the peer that starts a connection session. Thus, the SharedSecret is generated on the initiating peer's machine. (Obviously the private key is never shared.) Then the SharedSecret is securely transferred over the private DTLS-encrypted WebRTC channel directly to the other peer at the beginning of every new WebSocket session. (GSS is not in the middle.) The SharedSecret may also be sent by both peers to GSS over encrypted SSL/TLS if the peers ever enter the Unreachable state and need to start the Connection Restore Protocol (see below).

The SharedSecret is a long, random 512-bit sequence of hexadecimal characters, which looks like this:


Nobody except the two trusted peers could ever know the unique SharedSecret, which changes every time they start a new WebSocket session. This provides Perfect Forward Secrecy, which protects future messages/data from being compromised even if a past session key(s) is somehow discovered by an attacker. Additionally, the SharedSecret cannot be linked to any user's real identity even if a tyrannical government hijacked GSS.

Connection Restore Protocol

Under certain conditions, it's possible that two peers will change their IP addresses, but their Gini clients might not be launched and/or not connected to the Internet for many days, weeks or months. In this scenario, both peers would have unknown IP addresses, and thus, they would no longer be able to find each other on the Internet. If a peer has been unreachable for 3 days, both peers enter an Unreachable state for that particular P2P connection. In this case, the Gini client displays a dark orange dot next to the contact in the user's contact details page and in their contact list. Then the clients automatically initiate the following Connection Restore Protocol (CRP), which is a sub-protocol of the core GiniConnect protocol.

1. Register SharedSecret

SharedSecret Registration. The two peers submit a request to be reconnected to their peer by registering their encrypted SharedSecret with GSS. If it doesn't already exist, the SharedSecret is stored in a RestoreConnections table with the following fields:

SharedSecret (Text, Primary Key, Required)

Offer (Text) // WebRTC Offer, as previously specified in the core protocol.

Answer (Text) // WebRTC Answer, as previously specified in the core protocol.

Session (Text, Required) // The anonymous session path for each client connection to GSS. To maximize privacy, this session path is deleted every 24 hours, but it is refreshed every x interval (as defined below) whenever a peer repeats the CRP registration process.

Timestamp (Integer, Required)

NOTE: Like the WebRTC Offers/Answers in the core protocol, the WebRTC Offers/Answers during the CRP must be encrypted on the clients before sending them to GSS. However, during the CRP, the clients use their permanent public keys (PPKs) because the peers already securely exchanged their PPKs on a P2P basis during the "Contact Sync Stage" of the core protocol, which means their PPKs were never sent to GSS.

As a result, they don't need TPKs, FCs or MFCs anymore after that initial bootstrapping process. They also don't need to hash the SharedSecret because it's already encrypted by their respective PPKs and can only be decrypted by their respective private keys. Additionally, their encrypted WebRTC Offers/Answers are encrypted with their respective PPKs. Thus, there's no way for any attacker to hijack GSS to attack the peers.

Repeat Registration Interval. For the fastest and most secure peer re-connection possible, and to ensure that GSS has an open WS connection with each reconnecting peer, the peers repeat the registration process every x seconds in gradually increasing intervals until GSS detects a SharedSecret match or 365 days have passed, whichever occurs sooner. To minimize the impact on GSS, the gradually increasing interval x is based on the following schedule:

  • Every 60 seconds until the 3rd day of the CRP.
  • Every 300 seconds (5 mins) after the 3rd day of the CRP.
  • Every 600 seconds (10 mins) after the 10th day of the CRP.
  • Every 3600 seconds (1 hr) after the 20th day of the CRP.
  • Every 43200 seconds (12 hrs) after the 30th day of the CRP.
  • Every 86400 seconds (24 hrs) after the 40th day and until the 365th day of the CRP.

2. GSS Verifies SharedSecrets Match

Every time a new SharedSecret registration occurs, GSS searches the RestoreConnections table to see if the SharedSecret matches any existing SharedSecret. If a matching SharedSecret is found, GSS relays the SharedSecret to both peers for further verification. If no match is found, the SharedSecret remains in the DB until a match is eventually submitted by another peer or 365 days have passed (whichever comes sooner), then it is deleted.

3. Peers Verify SharedSecrets

After GSS relays the SharedSecret to the peers, they decrypt the SharedSecret to confirm that it is correct based on the fact that the SharedSecret was generated with crypto_kx_client_session_keys(alice.pubkey, bob.pubkey, initiator.privkey) on Alice and Bob's respective local machines. That means it can only be decrypted by Alice and Bob.

If the SharedSecret is not correct, that means one or both of the peers have submitted an incorrect SharedSecret or a hacker has tried to hijack their connection. In either case, the peers reject the SharedSecret (with error message: "Incorrect SharedSecret"). GSS relays the error message to both peers and terminates the WS session and the Connection Restoration Protocol.

4. Jump to Peer Connection Stage

If the SharedSecret is correct, then the peers are authenticated, which means they can jump to the "Peer Connection Stage" of the core GiniConnect Protocol.

Maximum CRP Period

After 365 days, all contacts are still available in the user's private Gini contact list, but the SharedSecret is deleted from GSS and the peers need to repeat all steps in the core GiniConnect Protocol again if they want to securely communicate with an old, unreachable peer. This is an important security precaution to protect users from various theoretical risks associated with trying to interact with and make payments to dormant accounts. (Remember, the SharedSecret is just a random string of text; so, it's useless to hackers and tyrannical governments. Thus, there are no privacy concerns about leaving it in GSS' DB for a while as a convenience to Gini users that might want their clients to automatically re-connect with their peers.)


The secure and trustless GiniConnect Protocol provides the highest level of communication privacy and data protection. Unlike other popular secure messaging apps like Signal, WhatsApp, Telegram, etc., the GiniConnect-powered GiniChat instant messenger embedded within the secure Gini Account Center software provides truly private, decentralized, encrypted, peer-to-peer connections without any centralized servers constantly in the middle. And unlike other messaging apps, Gini does not store any personally identifiable information (e.g., phone numbers, emails, etc.).

Additionally, to protect the IP addresses of Gini stakeholders so that even GSS cannot know the IPs of anonymous users, soon we will implement the Invisible Internet Protocol (I2P) for all privacy-focused Gini services, including GiniChat. I2P is similar to Tor, but I2P has proven for many years to be significantly more private, much faster, more decentralized, among many other technical benefits.

For all those reasons, the GiniConnect Protocol is a significant contribution to the open source community and the field of secure communications. GiniConnect provides significant benefits to all our Gini stakeholders and others who implement their communication systems based on the open source GiniConnect Protocol.

Misc Technical Details

The following sections provide supplemental details that help to clarify various aspects of the core GiniConnect Protocol.

Contact Data Format

Every Gini user's private contacts are stored in their secure Gini Account Center software on their local machine using the standard vCard format. Unlike CSV and other older formats, the vCard specification handles text, images, audio and other media. Using the vCard format ensures that contact data is compatible with other contact management systems that our Gini users might want to use in the future.


A STUN/TURN/ICE service works in combination with any network communications protocol to ensure that messages are successfully sent/received through NAT routers/firewalls. All network communication over the Internet requires this functionality. Thus, all references to GSS throughout the GiniConnect Protocol documentation implicitly include STUN/TURN/ICE functionality. This functionality is achieved by integrating Coturn into GSS. Coturn is the most popular and reliable open source STUN/TURN/ICE technology today.

Periodic Connection Confirmations

WebRTC is typically implemented with WebSockets in "secure mode" (wss://), which ensures that the signalling path between WebRTC nodes is hidden from eavesdroppers. WebSockets have a built-in ping-pong mechanism to automatically handle virtually all connection maintenance activities between peers. Technically, a WebSocket can stay alive forever, but there are certain situations when peers might change their IP addresses. In this case, we implement a mechanism to reconnect and update each peer's WebRTC Offer/Answer details. This is necessary to enable future encrypted P2P communication sessions and vCard syncing between trusted contacts without repeating the entire bootstrapping process.

For example, let's say Alice travels frequently and connects from many different IP addresses. Alice's Gini client announces these IPs to all the contacts/peers in her trusted Gini contact list, then those new IP addresses are saved by each acknowledging peer to each peer's own private WebRtc metadata table associated with their Alice contact record. This ensures that all of Alice's contacts can initiate future private P2P communications with Alice (without the GSS in the middle) even while she is traveling. In other words, her contacts can always connect with her by trying each of the previously saved IP addresses associated with Alice (and vice-versa).

Privacy Considerations

Any user that has created a trusted contact in their private Gini contacts list should not mind if their trusted contact's client automatically saves their IP addresses. This is generally how all decentralized technologies work (including Bitcoin, BitTorrent, etc.) and it's the only way to avoid using a centralized signaling server for all connections and content transfers.

The GiniConnect Protocol eliminates the centralization problem and protects the content of users' data. However, it's possible for sophisticated entities to use packet sniffing technologies to expose unprotected IP addresses, which could potentially enable them to locate their targets. This is only possible if one (or both) of the peers is under surveillance by sophisticated entities (e.g., large governments and corporations). This is a rare but plausible scenario.

For those reasons, we will soon implement the Invisible Internet Protocol (I2P), as explained previously.

Creating Non-Secure Contacts

Use "New Secure Contact" Whenever Possible. We strongly encourage all Gini stakeholders to add their trusted contacts to their private Gini contacts list by using the simple "New Secure Contact" feature in their Gini Account Center software. This automatically triggers and completes the entire secure GiniConnect Protocol described above, which makes the entire process invisible to the end-user.

When to Use "New Non-Secure Contact" Feature. We understand that some users might want to manually add certain contacts to their list without sharing any of their own personal details with the contact. This may be desirable in situations when users want to make anonymous payments to other stakeholders without disclosing any personally identifiable information. That's what the "New Non-Secure Contact" feature is for.

Adding Non-Secure Contacts. When a user clicks the "New Non-Secure Contact" menu option, the user is simply presented with an empty contact form. The user can then enter the contact's details (name, picture, address, etc.) and save it. If the user includes the contact's anonymous Gini payment address, then the user can click the Gini currency icon, which loads the contact's name, payment address and picture (if already saved) into the Account's payment screen just like a payment to a secure contact. However, no chat or vCard syncing features are possible with non-secure contacts.

Did You Like This Resource?

Gini is doing important work that no other organization is willing or able to do. Please support us by joining the Gini Newsletter below to be alerted about important Gini news and events and follow Gini on Twitter.