The atProtocol fundamentals

By Muralidharan Padmanaban & Anthony Prakash

Whether you’re a developer looking to get started on the atProtocol, an enterprise technologist trying to get a deeper understanding, or a casual Internet reader who randomly stumbled upon us, you’ve come to the right place. This article will give you a basic understanding of how our technology works. So let’s get started.

What is the atProtocol?

Developed by Atsign, the atProtocol is an open-source, P2P Internet protocol that enables developers and enterprises to handle personal data based on trust and permissions.

On the atProtocol, people will have the freedom to share, withhold, or retract their information at will through a unique identifier we’ve titled the atSign. They will no longer be unwittingly entrusting their data to companies.

Imagine that there are two entities with the atSigns @alice and @bob. The atProtocol gives @alice complete control over how information like email, websites, credit card numbers, and data like location or preferences is shared with other entities. To give @bob access to information, all @alice needs to do is share their atSign so that @bob can request specific data in the future.

In the future, business cards will use atSigns for people and roles. For example, the atSigns @alice and sales@acmeco allow you to always be able to contact Alice and the sales role at AcmeCo even if Alice’s contact details or if the people in the sales role change.

The “right to be forgotten” is another key aspect of the atProtocol. Since we believe that it is everyone’s fundamental right to change their choice of services on the Internet, people’s data should be forgotten and removed from entities that they no longer want to be associated with.

atRoot & secondary servers

The atProtocol has only two tiers of servers: the atRoot and atSecondary servers.

atRoot servers are the only centralized part of the atProtocol and are centralized to provide a single namespace and a global dependable platform. No data beyond the atSign and responding authoritative atSecondary server is held on the root servers. This information is considered public and no authentication is required to look up the atSecondary server for a particular atSign.

The atRoot servers have been designed to scale to billions of atSigns and handle the request for atSign lookups at near real-time, globally. To achieve this, in-memory databases are utilized and only the absolute minimum of data is stored.

atSecondary (personal atSign) servers provide the second tier of the atProtocol architecture and are responsible for answering lookups for specific atSigns. atSecondary servers provide the lookup service for a particular atSign and one name only. This ensures that the atSecondary server will not mix atSign data with any other atSign’s data. This is unlike web servers that can provide service to multiple websites at a time.

Schema

The atProtocol actually defines a secure URI (Universal Resource Identifier) for any data stored across the atProtocol (i.e. phone@alice) with one important difference — the value returned for an identifier is polymorphic, which means that it depends on who is accessing the resource or asking for the information. Besides, the addition of the atScheme, <atsign://>, creates a URL (Universal Resource Locator) that can be securely shared and interpreted.

For example, atsign://phone@alice can be identified and used to locate phone@alice with all the security and permissions features applied to that resource. This convention is easy to use and particularly useful for storing reference values to be returned by atProtocol requests.

atProtocol server verbs

A verb is a command used to communicate with an atServer through a secure socket.

from verb

Purpose: The from verb is used to tell the atServer what atSign you claim to be. The atServer will respond with a challenge in the form of a full at address and a cookie to place at that address.

Example 1:

@from:@alice // request to @alice server from @alice
data:_948da07a-01da-457f-a23b-aa851738e898@alice:29741692–6c08–408c-b93b-24d2758cc0f9

In this case the atServer will place the cookie 29741692–6c08–408c-b93b-24d2758cc0f9in a private location _948da07a-01da-457f-a23b-aa851738e898@alice.

The from verb response (challenge) will be signed by the pkam verb in this authentication flow.

Example 2:

@from:@bob // request to @alice server from @bob
data:proof:_64a27907-f555–44f8-bd86-b97838303805@bob:dfc6aedf-4618–4446–84bb-9d15838a7b10 //response from @alice server

In this case the atServer is asking for the cookie dfc6aedf-4618–4446–84bb-9d15838a7b10 to be placed at the location _64a27907-f555–44f8-bd86-b97838303805@bob with the header of proof:. The challenge being that, to actually place that cookie on @bob, the atServer requires access to the @bob atServer with public access. The public access is important as the @alice atServer will want to look up that cookie to prove the request is actually from @bob. The type of cookie and the location should be in the format of a uuid-v4 to ensure that the likelihood of a namespace clash is mathematically unlikely, especially when coupled with the timeout of any cookies placed within a few minutes or cleared once used.

pol verb

Purpose: The pol verb, which stands for proof of life, verifies whether the correct cookie was placed in the requesting atServer.

Example:

@from:@bob // request to @alice server from @bob
data:proof:_64a27907-f555–44f8-bd86-b97838303805@bob:dfc6aedf-4618–4446–84bb-9d15838a7b10 //response from @alice server
@pol
@bob@

In this case, the @alice server looks up the location of the @bob server through the root server. @alice server verifies whether the cookie dfc6aedf-4618–4446–84bb-9d15838a7b10 is placed in the public location _64a27907-f555–44f8-bd86-b97838303805@bob in the @bob server. If the cookie is present and valid, a prompt of requesting atsign(@bob) is returned.

pkam verb

Purpose: The pkam verb, short for public key authentication mechanism, is used to authenticate a client to an atServer. The challenge returned by the from verb is cryptographically signed with a private key by the client. The cryptographic signature is validated by the atServer using a public key.

Example:

@from:@alice // request to @alice server from @alice
data:_948da07a-01da-457f-a23b-aa851738e898@alice:29741692–6c08–408c-b93b-24d2758cc0f9
// snippet to sign challenge with private key
var key = RSAPrivateKey.fromString(privateKey);
var challenge = ‘_948da07a-01da-457f-a23b-aa851738e898@alice:29741692–6c08–408c-b93b-24d2758cc0f9’;
var signature = base64Encode
(key.createSHA256Signature(utf8.encode(challenge)));
// send pkam request to server
@pkam:<signature>
//prompt is returned if authentication is successful on @alice server
@alice@

update verb

Purpose: The update verb updates a key with a value in the atSign’s namespace. This value can be a user’s public, private, or shared data.

Example:

1. Sharing data publicly

update:public:phone@alice +1–111–111

The key phone@alice can be looked up by anyone.

2. Store confidential information

update:@alice:creditcard@alice 123–456–789

The key creditcard@alice is visible only to @alice and not to anyone else.

3. Share data with a specific @atsign

update:@bob:email@alice alice@atsign.com

The key email@alice is visible only to @bob and not to anyone else.

llookup verb

Purpose: An authenticated atSign can look up local keys using the llookup verb.

Example:

1. Local lookup public key

llookup:public:phone@alice 
data:+1–111–111

2. Local lookup key in private namespace

llookup:@alice:creditcard@alice 
 data:123–456–789

3. Local lookup shared key

llookup:@bob:email@alice 
 data:alice@atsign.com

plookup verb

Purpose: An authenticated atSign can look up public keys using the plookup verb.

Example:

lookup public key of @alice from @bob

@bob@pllookup:phone@alice 
data:+1–111–111

lookup verb

Purpose: The lookup verb is polymorphic in nature. If an atSign is authenticated, the lookup verb is used to retrieve data shared with authenticated atSign. If an atSign is unauthenticated, the lookup verb returns the public value of the key.

Example:

1. @bob is authenticated

@bob@lookup:email@alice 
data:alice@atsign.com

2. @alice is unauthenticated

lookup:phone@alice 
data:+1–111–111 //value of public:phone@alice

scan verb

Purpose: The scan verb lists all the keys stored in an atSign’s server. Like the lookup verb, the scan verb is polymorphic in nature. When executed without authentication, the verb returns all public keys. Upon authentication, the scan verb returns all keys (public, private and shared)

Example:

1. @alice is unauthenticated

@scan 
data:phone@alice //returns only the key shared publicly

2. @alice is authenticated

@alice@scan 
data:[public:phone@alice,@alice:creditcard@alice,@bob:email@alice] //returns all the keys in atSign’s server

delete verb

Purpose: The delete verb removes a key from the user’s server.

Example:

delete:@bob:email@alice

There are several other verbs that we will explain further in subsequent articles. Stay tuned!

Join our Discord Community: https://discord.gg/sRtXdAXN to stay up to date.

Muralidharan Padmanaban (murali@atsign.com) is a technical architect on the atProtocol core development team.

Anthony Prakash (anthony@atsign.com) leads Developer Relations and Strategic Partnerships for Atsign.

Atsign is the creator of an Open-source, P2P Internet protocol that enables developers and enterprises to handle personal data based on trust and permissions. Check out our GitHub repo.