docs(GITBOOK#123): No subject

docs/SUMMARY.md

@@ -29,3 +29,16 @@
 * [atsign.com](https://atsign.com/)
 * [noports.com](https://noports.com)
 * [atProtocol specification](https://github.com/atsign-foundation/at\_protocol/blob/trunk/specification/at\_protocol\_specification.md)
+* [Reference](reference/README.md)
+  * [atsign](reference/atsign.md)
+  * [cram](reference/cram.md)
+  * [encryption](reference/encryption.md)
+  * [namespace](reference/namespace.md)
+  * [notification](reference/notification.md)
+  * [pkam](reference/pkam.md)
+  * [polymorphism](reference/polymorphism.md)
+  * [pricing and costs](reference/pricing-and-costs.md)
+  * [privacy](reference/privacy.md)
+  * [public and private keys](reference/public-and-private-keys.md)
+  * [self encryption key](reference/self-encryption-key.md)
+  * [synchronization](reference/synchronization.md)

docs/reference/README.md

@@ -0,0 +1,2 @@
+# Reference
+

docs/reference/atsign.md

@@ -0,0 +1,21 @@
+# atsign
+
+### What is an atSign
+
+An atSign is a handle (e.g. @alice) that functions as your digital identity. It uses end-to-end encryption to ensure that your data is 100% owned and controlled by you.
+
+An atSign has two states: deactivated and activated. To activate an atSign, CRAM authenticate into your secondary server. After successful CRAM authentication, your atSign is activated where a PKAM key pair is generated by your device and the CRAM key will be invalid; so that only you own the keys to your secondary server.
+
+Each atSign has a unique key that is used to verify whether you are the atSign’s rightful owner. After first activating an atSign, be sure to save its corresponding key in a secure location. You’ll need it to sign back into the app or use other apps on the atPlatform.
+
+### Example
+
+Alice has created their own atSign called @alice. Anyone who looks up @alice can only view the information that they’ve made public through [atWavi](https://atsign.com/apps/wavi/), an app that lets them set up and customize their public profile. They’ll have the freedom to adjust it as needed, and those changes will be viewable in a matter of seconds.
+
+### What you can do with an atSign
+
+At the moment, you can pair your atSign with any app on the atPlatform (the underlying technology behind atSigns) to enable the app to access, but not store, your data. The number of things you can do with your atSign will increase as more and more of these atApps are built.
+
+While we wait for the rest of the Internet to catch up, you can get ahead of the game by downloading the first batch of recently launched atApps. These include @atmospherePro, an end-to-end encrypted file sharing app, @buzz, an entirely new and private way to connect with others, and more.
+
+Discover these atApps [here](https://atsign.com/apps/).

docs/reference/cram.md

@@ -0,0 +1,36 @@
+# cram
+
+### Definition
+
+CRAM is a term you may have heard of when reading about the atPlatform. CRAM stands for challenge response authentication mechanism. It is an algorithm/mechanism used in cryptography commonly used for authentication in protocols.
+
+### atPlatform
+
+You use your CRAM secret to activate your atSign and authenticate into your (secondary server)\[/atplatform/secondary-server] secondary server for the first time. Once authenticated, you may add, update, delete, and lookup keys in your own secondary server.
+
+When users get their atSign from \{{< a target="\_blank" href="https://atsign.com/" >\}}atsign.com\{{< /a >\}}, they receive their CRAM secret in the form of a QR code. A CRAM secret is just a long string of randomly generated characters. The CRAM secret can also be fetched from a REST API since sometimes the QR code can be cumbersome. It is recommended that you let the SDK handle these API requests as it is easier and safer.
+
+CRAM is made easy with the atPlatform. Since the CRAM secret was generated and given by Atsign, that would be like Atsign generating your password for you. To opposite this, atPlatform's SDKs and authentication services (such as at\_onboarding\_flutter) make it easy to generate a `.atKeys` file for subsequent logins to your secondary. This `.atKeys` file is generated by your device and contains the necessary keys to encrypt/decrypt data in your secondary server and the secondary server of other atSigns. The `.atKeys` file is closely related to PKAM which you can read more about here.
+
+### atProtocol
+
+In the atProtocol, CRAM is a verb.
+
+The cram verb is used to bootstrap authenticate one's own self as an owner of a Secondary Server. It is intended to be used once until a set of PKI keys are cut on the owner's mobile device and from then on we use the pkam verb.
+
+The following regex represents the syntax of the cram verb: `r'^cram:(?<digest>.+$)'`
+
+Learn more about the cram verb \{{< a rel="canonical" target="\_blank" href="https://github.com/atsign-foundation/at\_protocol/blob/trunk/specification/at\_protocol\_specification.md#the-cram-verb"
+
+> \}} here \{{< /a >\}}.
+
+### Key Definitions
+
+* **CRAM**: challenge response authentication mechanism
+* **CRAM Secret**: a long string of characters associated with each atSign for activation
+* **.atKeys file**: holds encryption keys for PKAM authenticating
+* **OTP**: one-time password
+
+### Related Resources
+
+\{{< card/breadcrumb href="/atplatform/specification" first="Protocol Specification" >\}} \{{< card/breadcrumb href="/atplatform/secondary-server" first="Secondary Server" >\}} \{{< card/breadcrumb href="/reference/encryption" first="Encryption" >\}} \{{< card/breadcrumb href="/reference/pkam" first="PKAM" >\}}

docs/reference/encryption.md

@@ -0,0 +1,27 @@
+# encryption
+
+### Definition
+
+Encryption is a means of achieving privacy. It is a part of cryptography which has the Greek origin meaning of "secret writing". The goal of encryption is that assuming that an unwanted third party is eavesdropping on an insecure channel, said person would not be able to comprehend the transmitted information. Decryption is the process of converted encrypted information into a comprehensible format. Encryption and Decryption algorithms are known as ciphers. Encryption uses a key which is a set of values that the cipher, as an algorithm, will operate on. Encryption and Decryption go back a long way with one of the most well known ciphers being the [Caesar Cipher](https://en.wikipedia.org/wiki/Caesar\_cipher)
+
+### Video
+
+Check out our video on Encryption [here](https://www.youtube.com/watch?v=A12jdKPa4WE)!
+
+\{{< youtube src="https://www.youtube.com/embed/A12jdKPa4WE" >\}}
+
+### atPlatform
+
+The atPlatform implements end-to-end encryption that is best illustrated with the following example: @alice wishes to share her phone number with her friend @bob. To do this, @alice, who is on her own device, prompts her own secondary server to direct phone @alice at her friend @bob's secondary server. From here, a shared key is generated for @bob (@bob:shared\_key@alice).
+
+This shared key uses the same encryption process as the Symmetric Key Encryption, which is called AES (Advanced Encryption Standard) and involves three block ciphers: AES-128, AES-192 and AES-256.
+
+The atProtocol specifically uses AES-256 for Data Encryption Keys.
+
+The RSA (Rivest-Shamir-Adleman) encryption algorithm is then used to encrypt the shared key from the above example with @bob's public key. The atProtocol specifically utilizes RSA 2048. Note, that because the RSA algorithm is an Asymmetric Key Encryption method, a public and private key are generated.
+
+If you want to read more about Encryption and how it works on the atPlatform check this [Medium](https://atsigncompany.medium.com/data-encryption-caching-with-the-protocol-debe9efc0f49) article!
+
+### Related Resources
+
+\{{< card/breadcrumb link="/reference/public\_private\_keys/" first="Public and Private Keys" >\}} \{{< card/breadcrumb link="/reference/self\_encryption\_key/" first="Self-Encryption Key" >\}} \{{< card/breadcrumb link="/reference/privacy/" first="Privacy" >\}}

docs/reference/namespace.md

@@ -0,0 +1,30 @@
+# namespace
+
+### Definition
+
+Atsign's CTO, Colin Constable says this in an interview on Namespaces: \{{\
+\}} "Most people are familiar with DNS (domain name system): for example, if you type “cnn.com”, “fox.com”, or “bbc.com”, you get news sites. But you can’t just type in “news” and expect the Internet to tell you which particular flavor of news you want. We need to create namespaces so that humans can remember the name and computers can translate it to Internet protocol. Once there is a namespace like “bbc.com,” you can reliably know that somebody owns that particular space, and it needs to be managed so that there are no clashes. For instance, you don’t want to type “bbc.com” and get sent to Amazon’s home page. That’s why they have to be unique, and we at Atsign created a new namespace with @Namespace."
+
+Feel free to read more on namespaces \{{< a rel="canonical" target="\_blank" href="https://atsigncompany.medium.com/the-hidden-beauty-of-protocol-namespaces-6f5fab7f7a09" >\}}here\{{< /a >\}}.
+
+### atPlatform
+
+Namespace is a common term that may occur when reading about the atPlatform. To put it simply, a namespace is a unique container to place data in. More in the context of the apps, namespaces are just atSigns associated with each app so a secondary server can be aware of which data belongs to who. See an example below.
+
+### Example
+
+When you ask someone “What is my name?” you will get a different answer for every person you ask. If you ask your parents, they may answer with a sweet nickname they gave you. If you ask your friends, they may answer with your first name. This is how namespaces work. You can ask different namespaces for data and get a different answer every time.
+
+In the context of the atProtocol, refer to the example below to improve your understanding.
+
+Example:
+
+* `phone.mospherepro` (phone is the key, mospherepro is the namespace) will answer with data=`123-123-1234`
+* `phone.alice` (phone is the key, alice is the namespace) will answer with data=`444-444-4444`
+* `phone.wavi` (phone is the key, wavi is the namespace) will answer with data=`555-555-5555`
+
+This is the beauty of the atProtocol. Each namespace replied with different information. People control their own data and which applications get what data. With the atPlatform, the people become in control of their own data privacy.
+
+### Related Resources
+
+\{{< card/breadcrumb href="/atplatform/specification" first="Protocol Specification" >\}} \{{< card/breadcrumb href="/atplatform/secondary-server" first="Secondary Server" >\}} \{{< card/breadcrumb href="/reference/polymorphism" first="Polymorphism" >\}}

docs/reference/notification.md

@@ -0,0 +1,124 @@
+# notification
+
+### atPlatform
+
+#### Notification
+
+Notification enables developers to **notify** another atSign of some data event. It is used to **notify** another atSign that data from your secondary server was modified (updated or deleted). Some example notifications include: the key's value is updated, the key is deleted, the key's metadata changed, and more.
+
+The atPlatform takes care of all of the heavy lifting with encryption, verb building, transmission, etc.
+
+Read more [here](https://blog.atsign.dev/part-1-the-notify-verb-cko97bv8f00l5gws13umb0nvz).
+
+#### Monitor
+
+Monitor uses notifications.
+
+The monitor is used to receive notifications from the other secondary server.
+
+Read more \{{< a href="https://github.com/atsign-foundation/at\_client\_sdk/blob/trunk/packages/at\_client/lib/src/manager/monitor.dart" target="\_blank" rel="canonical" >\}}here\{{\</ a >\}}.
+
+### atProtocol
+
+#### notify verb
+
+The notify verb enables you to notify the atSign user of some data event.
+
+The following is the regex for the `notify` verb.
+
+```
+notify:((?<operation>update|delete):)?(ttl:(?<ttl>\d+):)?(ttb:(?<ttb>\d+):)?(ttr:(?<ttr>(-)?\d+):)?(ccd:(?<ccd>true|false):)?(@(?<forAtSign>[^@:\s]-)):(?<atKey>[^:]((?!:{2})[^@])+)@(?<atSign>[^@:\s]+)(:(?<value>.+))?
+```
+
+| Regex Snippet                     | Explanation, \[argument details], (example)                                                                                                                                                                            |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `(?<operation>update\|delete):)?` | Operation of the notification (update\|delete)                                                                                                                                                                         |
+| `(ttl:(?<ttl>\d+):)?`             | TTL (time to live), \[integer, 1 or more digits, optional argument]                                                                                                                                                    |
+| `(ttb:(?<ttb>\d+):)?`             | TTB (time to birth), \[integer, 1 or more digits, optional argument]                                                                                                                                                   |
+| `(ttr:(?<ttr>(-)?\d+):)?`         | TTR (time to refresh), \[integer, 1 or more digits, can be negative, optional argument], (e.g.: 86400 will refresh once a day)                                                                                         |
+| `(ccd:(?<ccd>true\|false):)?`     | CCD (cascade delete), \[boolean, true\|false, optional argument], (e.g.: if the sender deletes their original key and ccd is true, the cached key gets deleted on both the sender's server and the recipient's server) |
+
+Following the metadata for creating the notification, next, we mention the AtKey the notification pertains to.
+
+| AtKey Regex Snippet                  | Explanation, \[argument details], (example)                                  |
+| ------------------------------------ | ---------------------------------------------------------------------------- |
+| `(@(?<forAtSign>[^@:\s]-))`          | The atSign the notification is for, \[string, required argument], (`@alice`) |
+| `(?<atKey>[^:]((?!:{2})[^@])+)`      | AtKey name, \[string, required argument], (e.g. 'signing\_publickey')        |
+| `@`                                  | at separator                                                                 |
+| `(?<atSign>[^@:\s]+)(:(?<value>.+))` | sharedBy/creator atSign, \[string], (e.g. 'bob')                             |
+
+Example use of the `notify` verb:
+
+```
+notify:update:@farinataanxious:test@33thesad
+```
+
+Response:
+
+If the notification was successfully sent, then the id of the notification is returned.
+
+```
+data:0ce0d150-52bf-4f09-a473-5c64777b1c53
+```
+
+Read more \{{< a href="https://github.com/atsign-foundation/at\_protocol/blob/trunk/specification/at\_protocol\_specification.md#the-sync-verb" target="\_blank" rel="canonical" >\}}here\{{\</ a >\}}.
+
+#### notify:list verb
+
+Notify list returns a list of notifications
+
+Regex
+
+```
+notify:(list (?<regex>.-)|list$)
+```
+
+Response:
+
+If the user is the owner, returns a list of received notifications. if a user is pol authenticated user, return a list of sent notifications
+
+```
+data:[{"id":"0e5e9e89-c9cb-423b-8972-8c5487215990","from":"@alice","to":"@bob","key":"@bob:phone@alice","value":12345,"operation":"update","epochMillis":1603714122636}]
+```
+
+#### notify:remove verb
+
+Notify remove will remove a notification from the Notify List
+
+Not to be confused with `notify:delete` which notifies another atSign of a key change event.
+
+Example:
+
+```
+notify:remove:<notification-id>
+```
+
+Response
+
+```
+data:success
+```
+
+#### monitor verb
+
+The monitor verb streams received notifications.
+
+The following is the regex
+
+```
+^monitor$|^monitor ?(?<regex>.-)?)$
+```
+
+Response:
+
+Returns a stream of notifications
+
+```
+@alice@monitor notification: {"id":"773e226d-dac2-4269-b1ee-64d7ce93a42f","from":"@bob","to":"@alice","key":"@alice:phone@bob","value":null,"operation":"update","epochMillis":1603714720965}
+```
+
+Read more \{{< a href="https://github.com/atsign-foundation/at\_protocol/blob/trunk/specification/at\_protocol\_specification.md" target="\_blank" rel="canonical" >\}}here\{{\</ a >\}}.
+
+### Related Resources
+
+\{{< card/breadcrumb link="/atplatform/specification/" first="Protocol Specification" >\}}

docs/reference/pkam.md

@@ -0,0 +1,33 @@
+# pkam
+
+### Definition
+
+PKAM stands for public key authentication mechanism. It is a mechanism for encrypting/decrypting data between two parties.
+
+### atPlatform
+
+The atPlatform's packages and SDKs help apps generate a RSA PKAM public/private keypair and save this in a `.atKeys` file containing these keys. Since Atsign provided the CRAM secret, this poses an vulnerability since this is a shared secret between you and Atsign. To avert this, a new RSA PKAM keypair is generated on your device and the CRAM secret is no longer valid. The PKAM keypair is used for all subsequent authentications, and as you are the only one with access to the private key, you are the only one who is able to authenticate.
+
+The PKAM public key is given out to other clients who want to send data to you. The data they send to you is encrypted using your public key and is decrypted using your private key. Read more on asymmetric encryption here.
+
+The PKAM private key used by the client to authenticate into their own secondary server. It is just like the CRAM secret except it was generated by you (as opposed by Atsign) and completely owned by you.
+
+### atProtocol
+
+In the atProtocol PKAM is a verb.
+
+The pkam verb is used to authenticate one's own self as an owner of a Secondary Server using a PKI style authentication.
+
+The following regex represents the syntax of the pkam verb: `^pkam:(?<signature>.+$)`
+
+Learn more about the pkam verb \{{< a target="\_blank" href="https://github.com/atsign-foundation/at\_protocol/blob/trunk/specification/at\_protocol\_specification.md#the-cram-verb" >\}}here\{{< /a >\}}.
+
+### Key Definitions
+
+* **PKAM**: public key authentication mechanism
+* **PKI**: public key infrastructure
+* **RSA**: "Rivest-Shamir-Aldeman" is an assymetric encryption algorithm. Read more \{{< a target="\_blank" href="/reference/encryption" >\}} here\{{< /a >\}}
+
+### Related Resources
+
+\{{< card/breadcrumb href="/atplatform/specification" first="Protocol Specification" >\}} \{{< card/breadcrumb href="/atplatform/secondary-server" first="Secondary Server" >\}} \{{< card/breadcrumb href="/reference/encryption" first="Encryption" >\}} \{{< card/breadcrumb href="/reference/cram" first="CRAM" >\}}