From fcaca09e78ff6671956b1d91a61cb9bfd99dd90b Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Tue, 6 Dec 2022 18:50:47 +0100 Subject: [PATCH] Changed secondary and secondary server to atServer | root server to atDirectory --- content/docs/atplatform/_index.md | 10 +- content/docs/atplatform/rootServer/index.md | 10 +- content/docs/atplatform/specification.md | 186 ++++++++++---------- content/docs/start/iot/index.md | 2 +- 4 files changed, 108 insertions(+), 100 deletions(-) diff --git a/content/docs/atplatform/_index.md b/content/docs/atplatform/_index.md index da7c95edf..a24c2914f 100644 --- a/content/docs/atplatform/_index.md +++ b/content/docs/atplatform/_index.md @@ -3,11 +3,17 @@ layout: list title: "The atPlatform" # The title (ON THE PAGE) lead: | # The lead below the title (ON THE PAGE) - Learn about how we created our shortcodes on the dev site! + +The atPlatform is built on the atProtocol, a new open network protocol, together with a robust set of tools and open source SDKs that makes building end-to-end encryption data exchange easy, and can: + +Enhanced security +Faster implementation times +Cost Savings (Operating and Capital Expenses) +Improved latency description: | # SEO Description of the page (Shows in google and atsign.dev search) - What is the atPlatform? +The atPlatform is an open-source source solution designed to help developers build end-to-end, cross-platform applications and IoT solutions, with privacy built in. draft: false # Change this to "true" to hide the page toc: true # Change this to "false" to hide the table of contents diff --git a/content/docs/atplatform/rootServer/index.md b/content/docs/atplatform/rootServer/index.md index 38675a4dd..333b42690 100644 --- a/content/docs/atplatform/rootServer/index.md +++ b/content/docs/atplatform/rootServer/index.md @@ -1,10 +1,10 @@ --- layout: list -title: "Root Server" # The title (ON THE PAGE) -lead: Learn about the root server behind the atPlatform +title: "atDirectory" # The title (ON THE PAGE) +lead: Learn about the atDirectory behind the atPlatform -description: Learn about the atPlatform root server +description: atDirectory is a service that stores the location of the atServer for each atSign as well as the atSign’s public encryption key (previously called the root server). draft: false # Change this to "true" to hide the page toc: true # Change this to "false" to hide the table of contents @@ -12,8 +12,8 @@ autolinks: true # Change this to "false" to hide the automatic links below your weight: 4 # For list pages, higher is first. --- -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. +atDirectories 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 atServer is held on the atDirecory. This information is considered public and no authentication is required to look up the atServers for a particular atSign. {{< image class="bg-none" src="findSecondary.png" type="page" >}} -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. +The atDirectory 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. diff --git a/content/docs/atplatform/specification.md b/content/docs/atplatform/specification.md index f411ff627..2947b8bec 100644 --- a/content/docs/atplatform/specification.md +++ b/content/docs/atplatform/specification.md @@ -1,8 +1,8 @@ --- layout: list -title: "Protocol Specification" # The title (ON THE PAGE) -lead: Learn about how the atProtocol works +title: "Protocol Specification" # The title (ON THE PAGE) - can we change this to "Under the hood" I feel it is more literal. +lead: This page gives an overview of how the internal of the atPlatform works. description: The specification of the atProtocol on the atPlatform @@ -14,48 +14,48 @@ weight: 3 # For list pages, higher is first. ## Introduction -The atProtocol is the underlying protocol that the atPlatform implements. It is a simple internet protocol for interacting with the Root Server and Secondary Server. The atPlatform builds on top of the atProtocol by taking full advantage of the features of the atProtocol. +The atProtocol is the underlying protocol that the atPlatform implements. It is a simple internet protocol for interacting with the atDirectory and atServer. The atPlatform builds on top of the atProtocol by taking full advantage of the features of the atProtocol. See our [Protocol Specification](https://github.com/atsign-foundation/at_protocol/blob/trunk/specification/at_protocol_specification.md) on our GitHub page under our [at_protocol](https://github.com/atsign-foundation/at_protocol) repository. If you see a typo, mistake, or want to suggest a feature, please see our [contributing guidelines](/start/other/#contributing-to-the-developer-site). All contributions are welcome. -## Root Server +## atDirectory -A Root Server should provide a lookup of where a Secondary Server for an atSign is running. This is similar to a DNS server. +The atDirectory provides a lookup of where an atServer for an atSign is running. This is similar to a DNS server. -When asking a Root Server for the lookup of a particular atSign the Root Server should respond with a null if the name does not exist and if the name exists the DNS name or address of the atServer and the IP port number for that atSign should be returned. +When asking an atDirectory for the lookup of a particular atSign the atDirectory should respond with a null if the name does not exist and if the name exists the DNS name or address of the atServer and the IP port number for that atSign should be returned. Response: `:` -The Root Server only has one verb - `@exit` and all other inputs are considered to be lookup requests. +The atDirectory only has one verb - `@exit` and all other inputs are considered to be lookup requests. -## Secondary Server +## atServer -A Secondary Server is where an atSign user's personal data should be stored. One interacts with a secondary using the verbs exposed by the protocol. +An atServer is where an atSign user's personal data should be stored. One interacts with an atServer using the verbs exposed by the protocol. -A Secondary Server should have 4 major sub components: +An atServer should have 4 major sub components: 1. Key Store 2. Commit Log 3. Access Log 4. Notification Log -Verbs described in the document should be used to create, update, delete and retrieve information from the above sub components. +Verbs described in the document should be used to create, update, delete, and retrieve information from the above sub components. ### 1. Key Store -Key store is a place where user data in a Secondary Server should be saved as key and value pairs. Apart from the value, an atSign user should be able to add certain metadata for a key. +Key store is a place where user data in an atServer should be saved as key and value pairs. Apart from the value, an atSign owner should be able to add certain metadata for a key. #### Key -A key in the atProtocol can be formed by using any alphanumeric and special characters (UTF-8) excluding "@", ":" and a white space (" "). A key in a secondary can be any of the following 5 types: +A key in the atProtocol can be formed by using any alphanumeric and special characters (UTF-8) excluding "@", ":" and a white space (" "). A key in an atServer can be any of the following 5 types: 1. Public Key -- A public key is a key which can be looked up by any atSign user. +- A public key is a key which can be looked up by any atSign owner. - A public key should be part of the *scan* verb result. - Format of the public key should be `public::<@sign>`. @@ -63,11 +63,11 @@ Example: `public:location@alice` -> The owner of the secondary should be allowed to update or delete the value of a public key. +> The owner of the atServer should be allowed to update or delete the value of a public key. 2. Private Key -- A private key is a key which cannot be looked up by any atSign user other than the one who created it. +- A private key is a key which cannot be looked up by any atSign owner other than the one who created it. - A private key should not be returned in a *scan* verb result. - Format of the private key should be `privatekey::<@sign>`. @@ -75,11 +75,11 @@ Example: `privatekey:pk1@alice` -> The owner of the secondary should be allowed to update or delete the value of a private key. +> The owner of the atServer should be allowed to update or delete the value of a private key. 3. User key -- A user key can only be looked up by an atSign user with whom the data has been shared. +- A user key can only be looked up by an atSign owner with whom the data has been shared. - A user key should be part of the *scan* verb result only for the user who created it and the specific user it has been shared with. - Format of the key shared with someone else should be `::`. @@ -89,15 +89,17 @@ Example: > Note: Above Key should be part of scan verb result only for @alice and @bob -> The owner of the secondary should be allowed to update or delete the value of a user key. +> The owner of the atServer should be allowed to update or delete the value of a user key. 4. Internal Key -- Internal keys start with an underscore(_) and are not displayed in scan results. Internal keys can be looked up only by the owner of the secondary +- Internal keys start with an underscore(_) and are not displayed in scan results. Internal keys can be looked up only by the owner of the atServer. 5. Cached Key - -- A cached key is a key that was originally created by another atSign user but is now cached on the Secondary Server of another user's atSign as they were given permission to cache it. + +- A cached key is a key that was originally created by another atSign owner but is now cached on the atServer of another user's atSign as they were given permission to cache it. - A cached key should be listed in the *scan* verb result for the atSign user who cached it. - Format of the key shared with someone else should be `cached:::`. @@ -105,7 +107,7 @@ Example: `cached:@bob:phone@alice` -> The user who has cached the key should not be allowed to update the cached key. +> The person who has cached the key should not be allowed to update the cached key. > An atSign user who has created and shared the key should be allowed to update a cached key, and if the "autoNotify" config parameter is set to true, the updated value should be notified (please refer to the `notify` verb) and the cached key updated with the new value. @@ -113,21 +115,21 @@ Example: #### Value -Text or binary values can be saved in a Secondary Server. The size of the valuue saved in a secondary is bound by the config parameter "maxBufferSize". +Text or binary values can be saved in an atServer. The size of the value saved in an atServer is bound by the config parameter "maxBufferSize". > A user should be made aware of this limitation by using the `stats` verb. -> If a binary value is being saved on a Secondary Server, the "isBinary" attribute on the metadata should be set to true by the convention. +> If a binary value is being saved on an atServer, the "isBinary" attribute on the metadata should be set to true by the convention. 1. Reference Value -A Secondary Server should support referencing another key's value. +An atServer should support referencing another key's value. A reference value should be in the format "atsign://". For example, 'phone@bob(key)' is 1234 (value). Now another key called altPhone@bob can refer to phone@bob by referencing it as altPhone@bob == atsign://phone@bob. -When the user does a lookup on the key that contains a reference, the Secondary Server should return a fully resolved value. +When the user does a lookup on the key that contains a reference, the atServer should return a fully resolved value. 2. Metadata @@ -137,7 +139,7 @@ Metadata of a key should describe the following properties of the value being in |----------------|--------------|-------------| | createdOn | Yes | Date and time when the key has been created. | | createdBy | Yes | atSign that has created the key | -| updatedOn | Yes | Date and tiem when the key has been last updated | +| updatedOn | Yes | Date and time when the key has been last updated | | sharedWith | No | atSign of the user with whom the key has been shared. Can be null if not shared with anyone. | | ttl | No | Time to live in milliseconds. | | expiresOn | Yes | A Date and Time derived from the ttl (now + ttl). A Key should be auto deleted once it expires. | @@ -152,50 +154,50 @@ Metadata of a key should describe the following properties of the value being in ### 2. Commit Log -A Secondary Server should record any create, update and delete operations in a commit log. The Commit Log should record these operations with a unique commit id so that users of the secondary can lookup operations that happened on or after a given commit id. +An atServer should record any `create`, `update`, and `delete` operations in a commit log. The Commit Log should record these operations with a unique commit id so that users of the atServer can lookup operations that happened on or after a given commit id. -A Secondary Server should provide a way to compact the Commit Log based on time and size. +An atServer should provide a way to compact the Commit Log based on time and size. ### 3. Access Log -A Secondary Server should record the following user actions: user login, user authentication and lookup. The Access Log should record these operations so that users of the secondary can retrieve various statistics such as the most visited atSign or most visited keys. +An atServer should record the following user actions: user login, user authentication, and lookup. The Access Log should record these operations so that users of the atServer can retrieve various statistics such as the most visited atSign or most visited keys. -A Secondary Server should provide a way to compact the Access Log based on time and size. +An atServer should provide a way to compact the Access Log based on time and size. ### 4. Notification Log -A Secondary Server should record any notifications that have been received and sent. Please check the `notify` verb specification for details on how a notification should be sent. +An atServer should record any notifications that have been received and sent. Please check the `notify` verb specification for details on how a notification should be sent. -A Secondary Server should provide a way to compact the Notification Log based on time and size. +An atServer should provide a way to compact the Notification Log based on time and size. ## Standard Keys -A Secondary Server should have the following standard keys: +An atServer should have the following standard keys: | Key | Description | |-----|-------------| -| public:publickey@ | Public key used by other atSigns for encryption | -| public:signing_publickey@ | Public key used on a pol handler to a verify a signed challenge | -| @signing_privatekey@ | Private key used to sign a challenge on a pol request | -| :shared_key@ | Symmetric key used to encrypt/decrypt self atSign data | +| public:publickey@ | Public key used by other atSigns for encryption. | +| public:signing_publickey@ | Public key used on a pol handler to a verify a signed challenge. | +| @signing_privatekey@ | Private key used to sign a challenge on a pol request. | +| :shared_key@ | Symmetric key used to encrypt/decrypt self atSign data. | ## Configuration Parameters -A Secondary Server should honor the following configuration parameters. +An atserver should honor the following configuration parameters. | Key | Valid Values | Description | |-----|--------------|-------------| -| autoNotify | true/false | If set to true, a Secondary Server should automatically notify another atSign user when a key has been shared with them. Please refer to the `notify` verb spec for details. | -| bufferLimit | Number of bytes | Maximum size of a value for a key that can be transferred to a Secondary Server | -| inbound_max_limit | An Integer | Maximum number of inbound connections that a Secondary Server can accept | -| outbound_max_limit | An Integer | Maximum number of outbound connections that a secondary can make to another Secondary Server | +| autoNotify | true/false | If set to true, an atServer should automatically notify another atSign user when a key has been shared with them. Please refer to the `notify` verb spec for details. | +| bufferLimit | Number of bytes | Maximum size of a value for a key that can be transferred to an atServer | +| inbound_max_limit | An Integer | Maximum number of inbound connections that an atServer can accept | +| outbound_max_limit | An Integer | Maximum number of outbound connections that an atServer can make to another atServer | | inbound_idle_time_millis | Time in milliseconds | Maximum time the inbound connection can active | | outbound_idle_time_millis | Time in milliseconds | Maximum time the outbound connection can be active. | ## Block List -A user of the Secondary Server should be able to decide who is allowed to connect to a Secondary Server. The `config` verb should be used to configure this. Once added, a Secondary Server should honor the list at the time of accepting new connections from an atSign user using the `from` verb. +A user of the atServer should be able to decide who is allowed to connect to their atServer. The `config` verb should be used to configure this. Once added, an atServer should honor the list at the time of accepting new connections from an atSign user using the `from` verb. ## Verbs @@ -203,7 +205,7 @@ A user of the Secondary Server should be able to decide who is allowed to connec **Synopsis:** -The `from` verb is used to tell a secondary whom you claim to be. +The `from` verb is used to tell an atServer whom you claim to be. Following regex represents the syntax of the `from` verb: @@ -215,33 +217,33 @@ Following regex represents the syntax of the `from` verb: **Response**: -If the user who is trying to connect is the owner of the Secondary Server, then the `from` verb should respond with the following response. +If the user who is trying to connect is the owner of the atServer, then the `from` verb should respond with the following response. `key:` -If the user who is trying to connect is not the owner of the Secondary Server, then the `from` verb should respond with the following response. +If the user who is trying to connect is not the owner of the atServer, then the `from` verb should respond with the following response. `proof:@<@sign>:` -If the user is not allowed to connect to the Secondary Server, then it should respond back with the following error and close the connection to the server. +If the user is not allowed to connect to the atServer, then it should respond back with the following error and close the connection to the server. `error:AT0013-Connection Exception` **Description:** -The `from` verb is used to tell the Secondary Server what atSign you claim to be. With the `from` verb, one can connect to one's own Secondary Server or someone else's Secondary Server. In both cases, the Secondary Server responds back with a challenge to prove that you are who you claim to be. This is part of the authentication mechanism of the atProtocol. +The `from` verb is used to tell the atServer what atSign you claim to be. With the `from` verb, one can connect to one's own atServer or someone else's atServer. In both cases, the atServer responds back with a challenge to prove that you are who you claim to be. This is part of the authentication mechanism of the atProtocol. -This authentication mechanism varies based on whether you are connecting to your own secondary (cram) or someone else's secondary (pol). +This authentication mechanism varies based on whether you are connecting to your own atServer (cram) or someone else's atServer (pol). **Options:** -`` Required: Yes. atSign with which you are connecting to a Secondary Server +`` Required: Yes. atSign with which you are connecting to an atServer ### The `cram` verb **Synopsis:** -The `cram` verb is used to bootstrap authenticate one's own self as the 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 `cram` verb is used to bootstrap authenticate one's own self as the owner of an atServer. 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: @@ -255,7 +257,7 @@ The following regex represents the syntax of the `cram` verb: If the user gets the challenge right, the prompt should change to the atSign of the user. -`<@sign>@` +`@` If the user gets the cram authentication wrong, then it should respond back with the following error and close the connection to the server. @@ -263,7 +265,7 @@ If the user gets the cram authentication wrong, then it should respond back with **Description:** -The `cram` verb follows the `from` verb. As an owner of the Secondary Server, you should be able to take the challenge thrown by the `from` verb and encrypt using the shared key that the server has been bound with. Upon receiving the `cram` verb along with the digest, the server decrypts the digest using the shared key and matches it with the challenge. If they are the same, then the secondary lets you connect to the Secondary Server and changes the prompt to your atSign. +The `cram` verb follows the `from` verb. As an owner of the atServer, you should be able to take the challenge thrown by the `from` verb and encrypt using the shared key that the server has been bound with. Upon receiving the `cram` verb along with the digest, the server decrypts the digest using the shared key and matches it with the challenge. If they are the same, then you can connect to the atServer and change the prompt to your atSign. **Options:** @@ -273,7 +275,7 @@ The `cram` verb follows the `from` verb. As an owner of the Secondary Server, yo **Synopsis**: -The `pol` verb is part of the `pkam` process to authenticate oneself while connecting to someone else's Secondary Server. The term 'pol' means 'proof of life' as it provides a near realtime assurance that the requestor is who it claims to be. +The `pol` verb is part of the `pkam` process to authenticate oneself while connecting to someone else's atServer. The term 'pol' means 'proof of life' as it provides a near realtime assurance that the requestor is who it claims to be. Following regex represents the syntax of the `pol` verb: @@ -295,7 +297,7 @@ If the user gets the cram authentication wrong, then it should respond back with **Description:** -The `pol` verb follows the `from` verb. 'pol' indicates another secondary that the user who is trying to connect is ready to authenticate himself. For example, if @bob is trying to connect to @alice, @bob would take the key and value from the proof response of the verb and create a public key and value which then can be looked up by @alice. After @alice looks up @bob's secondary @alice's secondary should change the prompt to @bob. +The `pol` verb follows the `from` verb. 'pol' indicates another atServer that the user who is trying to connect is ready to authenticate himself. For example, if @bob is trying to connect to @alice, @bob would take the key and value from the proof response of the verb and create a public key and value which then can be looked up by @alice. After @alice looks up @bob's atServer, @alice's atServer should change the prompt to @bob. **Options:** @@ -305,7 +307,7 @@ NA **Synopsis:** -The scan verb is used to see the keys in an atSign's secondary server. +The scan verb is used to see the keys in an atSign's atServer. Following regex represents the syntax of the `scan` verb: ```r'^scan$|scan(:showhidden:(?true|false))?(:(?@[^:@\s]+))?(:page:(?\d+))?( (?\S+))?$'``` @@ -319,14 +321,14 @@ Following regex represents the syntax of the `scan` verb: **Response:** -The Secondary Server should return the keys within the secondary server if the scan verb executed successfully. The Secondary Server will respond accordingly to whether the atSign is authenticated or not. +The atServer should return the keys within the atServer if the scan verb executed successfully. The atServer will respond accordingly to whether the atSign is authenticated or not. ```data:[]``` ### The `update` verb **Synopsis:** -The `update` verb is used to insert key/value pairs into a Key Store. An update can only be run by the owner of a Secondary Server on his/her own Secondary Server. +The `update` verb is used to insert key/value pairs into a Key Store. An update can only be run by the owner of an atServer on his/her own atServer. Following regex represents the syntax of the `update` verb: @@ -342,7 +344,7 @@ Following regex represents the syntax of the `update` verb: **Response:** -The Secondary Server should return the commit id from Commit Log if the update is successful. +The atServer should return the commit id from Commit Log if the update is successful. `data:` @@ -352,9 +354,9 @@ If the user provides the invalid update command, then it should respond with the **Description:** -The `update` verb should be used to perform create/update operations on the Secondary Server. The `update` verb requires the owner of the secondary to authenticate himself/herself to the Secondary Server using `from` and `cram` verbs. +The `update` verb should be used to perform create/update operations on the atServer. The `update` verb requires the owner of the atServer to authenticate himself/herself to the atServer using `from` and `cram` verbs. -If a key has been created for another @sign user, the Secondary Server should honor "autoNotify" configuration parameter. +If a key has been created for another atSign user, the atServer should honor "autoNotify" configuration parameter. **Options:** @@ -368,11 +370,11 @@ If a key has been created for another @sign user, the Secondary Server should ho `` Required: No. Description: A value of "true" indicates that the cached key needs to be deleted when the atSign user who has originally shared it deletes it. -`` Required: Yes, (Not required when the key is a public key). Description: atSign of the user with whom the key has been shared +`` Required: Yes, (Not required when the key is a public key). Description: atSign of the user with whom the key has been shared. `<@sign>` Required: Yes. Description: atSign of the owner. -`` Required: Yes. DEscription: Value for the key. +`` Required: Yes. Description: Value for the key. ### The `update:meta` verb @@ -392,19 +394,19 @@ Following is the regex for the `update:meta` verb **Response:** -The Secondary Server should return the commit id from Commit Log if the update is successful. +The atServer should return the commit id from Commit Log if the update is successful. `data:` -If the user provides the invalid update meta command, then it should respond with the following error and close the connection to the server. +If the user provides the invalid update meta command, then it should respond with the following error and close the connection to the atServer. `error:AT0003-Invalid Syntax` **Description:** -The `update:meta` verb should be used to perform create/update operations on the Secondary Server. The `update:meta` verb requires the owner of the secondary to authenticate himself/herself to the Secondary Server using `from` and `cram` verbs. +The `update:meta` verb should be used to perform create/update operations on the atServer. The `update:meta` verb requires the owner of the atServer to authenticate himself/herself to the atServer using `from` and `cram` verbs. -The Secondary Server should allow creation of keys with null values. If a key has been created for another @sign user, the Secondary Server should honor "autoNotify" configuration parameter. +The atServer should allow creation of keys with null values. If a key has been created for another atSign user, the atServer should honor "autoNotify" configuration parameter. **Options:**: @@ -418,9 +420,9 @@ The Secondary Server should allow creation of keys with null values. If a key ha `` Required: No. Description: A value of "true" indicates that the cached key needs to be deleted when the atSign user who has originally shared it, deletes it. -`` Required: Yes (Not required when the key is a public key). Description: atSign of the user with whom the key has been shared +`` Required: Yes (Not required when the key is a public key). Description: atSign of the user with whom the key has been shared. -`<@sign>` Required: Yes. Description: atSign of the owner +`<@sign>` Required: Yes. Description: atSign of the owner. ### The `lookup` verb @@ -442,7 +444,7 @@ The following is the regex of the `lookup` verb: **Response**: -If the operation is not specified the Secondary Server should just respond back with the value saved by the user as is. +If the operation is not specified the atServer should just respond back with the value saved by the user as is. `data:` @@ -505,15 +507,15 @@ data: } ``` -If the other Secondary Server on which the lookup needs to be performed is down then the secondary should return the following error and keep the connection alive. +If the other atServer on which the lookup needs to be performed is down then the atServer should return the following error and keep the connection alive. -`error:AT0007-Secondary Server not found.` +`error:AT0007-atServer not found.` -If the lookup command is not valid, then the Secondary Server should return the following error and close the connection: +If the lookup command is not valid, then the atServer should return the following error and close the connection: `error:AT0003-Invalid Syntax` -For whatever reasons, If the handshake with another secondary fails, then the Secondary Server should return the following error: +For whatever reasons, If the handshake with another atServer fails, then the atServer should return the following error: `data:AT0008-Handshake failure` @@ -541,15 +543,15 @@ Following is the regex of the `plookup` verb: **Response:** -The Secondary Server should return the value or metadata or the value and metadata together based on the option specified. +The atServer should return the value or metadata or the value and metadata together based on the option specified. The response structure should be exactly the same as the `lookup` verb. -If the other Secondary Server on which the `lookup` needs to be performed is not available, then the secondary should return the following error and keep the connection alive. +If the other atServer on which the `lookup` needs to be performed is not available, then the atServer should return the following error and keep the connection alive. -`error:AT0007-Secondary Server not found.` +`error:AT0007-atServer not found.` -If the `lookup` command is not valid, then the Secondary Server should return the following error and close the connection: +If the `lookup` command is not valid, then the atServer should return the following error and close the connection: `error:AT0003-Invalid Syntax` @@ -557,7 +559,7 @@ If the `lookup` command is not valid, then the Secondary Server should return th **Synopsis:** -The `llookup` verb should be used to look up one's own secondary and this should return the value as is (i.e. without any resolution). +The `llookup` verb should be used to look up one's own atServer and this should return the value as is (i.e. without any resolution). The following is the regex of the `llookup` verb: @@ -571,21 +573,21 @@ The following is the regex of the `llookup` verb: **Response:** -The Secondary Server should return the value or metadata or the value and metadata together based on the option specified. +The atServer should return the value or metadata or the value and metadata together based on the option specified. The response structure should be exactly the same as the `lookup` verb. -If the other Secondary Server on which the lookup needs to be performed is down then the secondary should return the following error and keep the connection alive. +If the other atServer on which the lookup needs to be performed is down then the atServer should return the following error and keep the connection alive. -`error:AT0007-Secondary Server not found.` +`error:AT0007-atServer not found.` -If the lookup command is not valid, then the Secondary Server should return the following error and close the connection: +If the lookup command is not valid, then the atServer should return the following error and close the connection: `error:AT0003-Invalid Syntax` **Description:** -The `llookup` verb should be used to fetch the value of the key in the owner's secondary store as is without resolving it. For example if a key contains a reference as a value, the `lookup` verb should resolve it to a value whereas `llookup` should return the value as is. +The `llookup` verb should be used to fetch the value of the key in the owner's atServer store as is without resolving it. For example if a key contains a reference as a value, the `lookup` verb should resolve it to a value whereas `llookup` should return the value as is. **Example:** @@ -595,7 +597,7 @@ If `phone@bob` is "1234" and `altphone@bob` is "atsign://phone@bob", then `looku **Synopsis:** -The `pkam` verb is used to authenticate one's own self as an owner of a Secondary Server using a PKI style authentication. +The `pkam` verb is used to authenticate one's own self as an owner of an atServer using a PKI style authentication. Following regex represents the syntax of the `pkam` verb: @@ -617,7 +619,7 @@ If the user gets the pkam authentication wrong, then it should respond back with **Description:** -The `pkam` verb follows the `from` verb. As an owner of the Secondary Server, you should be able to take the challenge thrown by the `from` verb and encrypt using the private key of the RSA key pair with what the server has been bound with. Upon receiving the `cram` verb along with the digest, the server decrypts the digest using the public key and matches it with the challenge. If they are the same then the secondary lets you connect to the Secondary Server and changes the prompt to your atSign. +The `pkam` verb follows the `from` verb. As an owner of the an atServer, you should be able to take the challenge thrown by the `from` verb and encrypt using the private key of the RSA key pair with what the server has been bound with. Upon receiving the `cram` verb along with the digest, the server decrypts the digest using the public key and matches it with the challenge. If they are the same then the atServer lets you connect to the atServer and changes the prompt to your atSign. **Options:** @@ -657,7 +659,7 @@ data: [{"id":"1","name":"activeInboundConnections","value":"1"}] ### The `sync` verb -The `sync` verb enables to synchronize the keys between the local Secondary Server and remote Secondary Server. +The `sync` verb enables to synchronize the keys between the local atServer and remote atServer. Following is the regex: @@ -776,7 +778,7 @@ The `monitor` verb accepts an optional parameter to filter the notifications by | AT0001 | Server exception | Exception occurs when there is an issue while starting the server. | | AT0002 | Datastore exception | Exception occurs during keystore operations (GET/PUT/DELETE). | | AT0003 | Invalid syntax | Exception occurs if we give any invalid command to the server. | -| AT0004 | Socket error | Exception occurs when socket connection to secondary cannot be established. | +| AT0004 | Socket error | Exception occurs when socket connection to an atServer cannot be established. | | AT0005 | Buffer limit exceeded | This exception occurs when input/output message size reaches the maximum limit configured in the server. | | AT0008 | Handshake failure | this exception is for any exception during the handshake process of two secondaries. | | AT0009 | Unauthorized client in the request | Occurs when an unsuccessful handshake happens between two secondaries. | @@ -785,6 +787,6 @@ The `monitor` verb accepts an optional parameter to filter the notifications by | AT0012 | Inbound connection limit exceeded | This exception will occur when the number of active clients reaches the maximum limit configured. | | AT0401 | Client authentication failed | This exception occurs when client authentication fails or client tries to execute any verb which needs authentication before successful authentication. | | AT0013 | Connection exception | This will occur when a blocked user tries to connect to the secondary. | -| AT0014 | Unknown AtClient exception | This exception will be thrown while performing any operations (GET/UPDATE/DELETE) using AtClient SDK. | +| AT0014 | Unknown AtClient exception | This exception will be thrown while performing any operations (GET/UPDATE/DELETE) using atClient SDK. | | AT0015 | Key not found | This exception will be thrown when the key is not available for encryption/decryption. | -| AT0021 | Unable to connect to secondary | This exception will occur when we are unable to connect to secondary. | +| AT0021 | Unable to connect to the atServer | This exception will occur when we are unable to connect to atServer. | diff --git a/content/docs/start/iot/index.md b/content/docs/start/iot/index.md index 2c6e764d5..c28b74fe9 100644 --- a/content/docs/start/iot/index.md +++ b/content/docs/start/iot/index.md @@ -21,7 +21,7 @@ IoT–Internet of Things–is a system of interconnecting devices, mechanical or In simple terms, an IoT device is any device (such as a camera, a smart phone, a thermostat, a TV, a computer, etc) that is connected to the internet. IoT devices have sensors that are always collecting data and sending it through the Internet. However, these data are usually precious data that are valuable to the owner. For example, a person may own a camera connected to the internet which is constantly surveilling the living room of their house. It is important that outside parties have no access to this data and that the data the camera is collecting is sent securely over the internet. This is where the atPlatform comes in. The atPlatform adds security to this IoT camera device and sends the data securely to whomever the owner chooses. -As said on our website [atsign.com](https://atsign.com/iot-internet-of-things/#overview), the atPlatform strips things down to the protocol level, creating both zero trust and zero configuration environments–completely without passwords–eliminating all attack surfaces created by over-complexity, and simplifying the administration of devices in the process. +As said on our[website] (https://atsign.com/iot-internet-of-things/#overview), the atPlatform strips things down to the protocol level, creating both zero trust and zero configuration environments–completely without passwords–eliminating all attack surfaces created by over-complexity, and simplifying the administration of devices in the process. ## IoT Network Architecture