What is a Port? 

When you use Port, you inevitably must use a “port” to form a connection.  

A port is our way to share information relevant to forming a connection without revealing any persistent unique identifiers to the person you’re connecting with. Ports take several forms: QR codes, one-time usable links, and even the “share contact” card within chats. 

To understand what a port truly is, let us dissect one. Below is one of my ports that has been closed. If you scan it, it won’t connect you to me, but you’re welcome to try. 

To begin, scan it with a generic QR code scanner. You will find that it encodes the following URL: https://porting.me/?portId=0f1b803d0fef4fe985341e63ac78fcb8&version=1.0.0&org=numberless.tech&target=0&name=Abhi&rad=240a69b38096a8019e873f71ded0640a&keyHash=70f46d48b27f0c2b89870809b9db9dde171a9341ea6e066e8e354cc714cf87e9&pubkey=e77fd0f8166ebbb911269bbbc7d7d3b429f8153ebfc6f322b24ee81f8a26ac23.  

We convert our ports into links that can then be displayed as QR codes to allow people to use any QR code scanner to scan our codes. If you scan it outside the app, you are redirected into the app using universal linking/deep-linking in a manner that does not allow our servers to access this content. 

The link is a little hard to read, but the important details are that information important to forming the connection is included in the URL as query parameters. 

Fields of the Port, and why they matter 

PortId  

A portId is a high-entropy UUID generated by the server. On the server’s side, this is mapped to the user who generated the port. Our servers store portIds until they are deleted by the user or “consumed” to form a connection. There are typically 5-15 unused portIds for each user to allow for a small number of connections to be initiated while disconnected from the internet, and sometimes more if a user has created and shared ports through other methods that haven’t been used by a peer yet. Creating a new portId is a process initiated by the client. 

Pubkey and keyHash 

The pubkey included in ports is part of a key pair that is associated with one and only one port and is never reused. When you share a port the peer you connect with expects you to use that pubkey to perform a Diffie-Hellman key exchange to form the basis of your end-to-end-encryption. The keyHash is a simple hash of the same public key to ensure its integrity. 

RAD 

This is a pretty rad feature that allows you, the sharer of the port, to be confident that no man-in-the-middle attack was performed during the connection process. 

The RAD is a locally generated high-entropy random number. Once you and your peer have established a secure channel, the peer sends you the RAD over said channel. At this point, you compare the RAD you generated to the RAD sent over the secure channel. If they match, you mark the chat as authenticated and can begin sending messages. 

If you’re ever using Port and see a header in one of your chats that is pending authentication, it’s because your device hasn’t yet been given the RAD that it expects. If you send messages then, they will stay cached on your device and only send when the authenticity can be verified. 

Our handshake ensures that we verify authenticity as soon as possible to allow you and your peer to send messages as soon as possible. In nearly all situations, you can verify the authenticity of a chat the moment you form your connection, but in exceptional cases where our servers may be compromised, you are still protected from forming connections with people you don’t intend to have a meaningful conversation with. 

Version and Org 

“Version” is a field that represents the “version” of the port, to allow us to support multiple protocols in the future, should we ever come up with a better way to connect, without invalidating older ports. 

“Org” is currently not used. We put them in there because it represents the organization that tracks the portId. We intend to use this in future features that will help democratize trust in Port. 

Name 

Based on our threat model, we never store any personally identifying information on our servers. The only personally identifying information that we include as part of the connection initiation process is your name, to allow the peer/scanner of the port to see your name, even if you’re not online to share your name with them. To support this without storing your name, we include it in Ports directly, which get shared directly from the screen of your phone to their camera.