atRecord

The format atServers use to store and share data.

At Atsign, whenever we mention the word "key" we are normally talking about a cryptographic key.

The main exception being the atKey, this is the "key" of a "key value pair" that makes up every atRecord.

It's unfortunate that the word "key" is polymorphic in computer science, and we have tried in the past to move to other words, but we have decided to stick with keys and the developer will have to understand the context of cryptographic key or key value pair (sorry!)

atRecords are the data records that are stored by the atServers. We use the common key-value pair format.

atKey

An atKey is the identifier half of the "key-value" pair. Similar to the primary key of a tabular database, the atKey must be a unique string which represents the data.

There are 5 different types of an atKey.

Type	Purpose
Public	Store and share public data which can be seen by anyone.
Self	Store data which can only be seen by the owner.
Shared	Store and share private data which can only be seen by the owner and intended recipient.
Private	Store data which can only be seen by the owner, hidden by default.
Cached	Cache shared data from other atSigns for performance and offline mode.

Structure of an atKey

[cached:]<visibility scope>:<record ID><owner’s atSign>

Cached

A marker for whether it is a cached key or not.

Visibility Scope

A marker for who has access to the key.

Record ID

A unique string used to represent the atRecord.

Owner's atSign

The owner (i.e. creator's) atSign for that particular atRecord. The shared by atSign of an atRecord is synonymous to the owner atSign of an atRecord.

Rules for atKeys

1. Length of an atKey should not be more than 240 characters (a limitation of the current implementation of the atServer, not a protocol limitation)

2. A maximum of 55 7-bit characters for the atSign (unicode is translated to UTF-7)

3. Allowed characters in an entity are: [\w._,-"']

4. Namespace is mandatory in the current implementation of the protocol i.e entity must follow the notation: <identifier>.<namespace>

5. Cached atKeys should have a different owner than the current atSign

6. Visibility scope and owner cannot be the same for a shared atKey

7. Reserved atKeys cannot be modified or notified

8. For newly created atKeys, the owner must match the current atSign

Reserved atKeys

The following is a list of reserved atIKeys which the atServer requires to function.

Don't try to delete or overwrite these keys, the atServer cannot function without them.

• privatekey:at_pkam_privatekey

• privatekey:at_pkam_publickey

• public:publickey

• privatekey:privatekey

• shared_key

• privatekey:self_encryption_key

• signing_privatekey

• public:signing_publickey

• privatekey:at_secret

• privatekey:at_secret_deleted

Example atKeys

Public atKey

1. A public atKey with a record id of location shared by @alice. This atKey typically holds public data that any atSign can access.

public:location@alice

2. A public atKey with a record id of publickey shared by @bob. Note that this is a reserved atKey.

public:publickey@bob

Private atKey

1. A private atKey with a record id of pk1 shared by @alice.

privatekey:pk1@alice

Shared atKey

1. A shared atKey with a record id of phone shared with @bob, shared by @alice.

@bob:phone@alice

2. A shared atKey with the record id of name, a namespace of wavi, shared with @alice, and shared by @bob.

@alice:name.wavi@bob

Internal atKey

1. An internal atKey with a record id of _latestnotificationid, namespace of at_skeleton_app and is shared by @alice.

_latestnotificationid.at_skeleton_app@alice

Cached atKey

1. A cached atKey with a record id of phone, shared with @bob, and is shared with @alice.

cached:@bob:phone@alice

atMetadata

Metadata of the atRecord is also stored and describes the following properties of the atValue.

Meta Attribute	Auto create?	Description
availableFrom	Yes	A Date and Time derived from the ttb (now + ttb). A Key should be only available after availableFrom.
ccd	No	Indicates if a cached key needs to be deleted when the atSign user who has originally shared it deletes it.
createdBy	Yes	atSign that has created the key
createdOn	Yes	Date and time when the key has been created.
expiresOn	Yes	A Date and Time derived from the ttl (now + ttl). A Key should be auto deleted once it expires.
isBinary	No	True if the value is a binary value.
isCached	No	True if the key is cached.
isEncrypted	No	True if the value is encrypted.
refreshAt	No	A Date and Time derived from the ttr. The time at which the key gets refreshed.
sharedWith	No	atSign of the user with whom the key has been shared. Can be null if not shared with anyone.
updatedOn	Yes	Date and time when the key has been last updated.
ttb	No	Time to birth in milliseconds.
ttl	No	Time to live in milliseconds.
ttr	No	Time in milliseconds after which the cached key needs to be refreshed. A ttr of -1 indicates that the key can be cached forever. ttr of 0 indicates do not refresh. ttr of > 0 will refresh the key. ttr of null indicates the key is impossible to cache, hence, refreshing does not make sense (which has the same effect as a ttr of 0).

atValue

Text or binary values can be saved in an atServer.

Small objects are fine to use the atServer but large objects should be used by reference.

For example, derive a new encryption key, encypt a file, upload that file to location, then notify other atSigns of the location and the encyption key. This is how atmospherePro works.

The size of the value saved in an atServer is bound by the atProtocol's config parameter "maxBufferSize".