RAIDA API Standards

From CloudCoin Wiki
Jump to: navigation, search

Directory Services: V 5.5.2017

Purpose:

The purpose of the Directory Service API is to provide a backup system for a program (or user) to learn the names or IP addresses of the RAIDA servers so they can be contacted. The Directory Service may provide the RAIDA contact information in a different (and yet uninvented) format if convenient to the application. In other words, a separate, non-JSON service could easily be created. A dynamic RAIDA Directory is planned for the future but may not be necessary for years. THE DIRECTORY SERVICE HAS YET TO BE IMPLEMENTED.

For network 1, the default locations that can be tried first, before accessing the directory. The names are case insensitive. are:

https://RAIDA0.CloudCoin.Global
 https://RAIDA1.CloudCoin.Global
 ...
 https://RAIDA23.CloudCoin.Global 
 https://RAIDA24.CloudCoin.Global

For future networks (should network multiplication occur) the names of the servers will have a network extension such as RAIDA0Net2 through RAIDA24Net2 where Net2 means they are on network 2.

Default Names:

https://RAIDA0net2.CloudCoin.Global
 https://RAIDA1net2.CloudCoin.Global
 ...
 https://RAIDA23net2.CloudCoin.Global
 https://RAIDA24net2.CloudCoin.Global

Directory Request:

Client uses HTTPS to GET the directory page located on different marketing servers. Note that directory uses extension-less urls.

Example of a Directory Request:

//www.cloudcoin.ch/service/directory  (This is not yet implemented as of 5/5/2017)

A test directgory can be found at:

//www.cloudcoin.co/servers.html

Directory Response:

Server returns a JSON string that describes the URLs of the RAIDAs, the status, the milliseconds required to contact, and a port to use.

Example of a Directory Response:

 {
   "server": [
     {
      "name": "RAIDA0",
       "url": "RAIDA0.CloudCoin.Global",
       "bkurl": "RAIDA0.CloudCoin.ch",
       "status": "unknown",
       "ms": "0",
       "location":"USA",
       "img":"cloudcoin.global\/flags\/usa1.png",
       "protocol":"https",
       "port": "443"
     },
     {
       "name": "RAIDA1",
       "url": "212.120.69.50",
       "bkurl": "RAIDA1.CloudCoin.ch",
       "status": "ready",
       "ms": "230",
       "location":"Macedonia",
       "img":"cloudcoin.global\/flags\/macedonia.png",
       "protocol":"http",
       "port": "80"
     },
      //NOTE: RAIDA3 through RAIDA22 have been left out to save space
   {
       "name": "RAIDA23",
       "url": "RAIDA23.CloudCoin.Global",
       "bkurl": "RAIDA23.CloudCoin.ch",
       "status": "unknown",
       "ms": "0",
       "location":"USA",
       "img":"cloudcoin.global\/flags\/usa1.png",
       "protocol":"https",
       "port": "443"
     },
     {
       "name": "RAIDA24",
       "url": "RAIDA24.CloudCoin.Global",
       "bkurl": "RAIDA24.CloudCoin.ch",
       "status": "down",
       "ms": "0",
       "location":"Taiwan",
       "img":"cloudcoin.global\/flags\/twain.png",
       "protocol":"https",
       "port": "443"
     }
   ]
 }

KEY

  • url: The Fully Qualified Domain name of the Server
  • bkurl: a backup URL in case the DNS of one goes down.
  • name: The name of the Server
  • status: When we have a dynamic system, this might tell the people that the server is down and why.
  • ms: Milliseconds. Time to echo (This could be used if have mirrors of the same server up in the future)
  • location: Where or who runs the RAIDA
  • img: An image file that can be associated with the RAIDA
  • protocol: http, or https. Could be something different in the future such as smtp, TFTP, FTP, sms
  • port: Port number. Usually 80 or 443

Rules:

The Directory Service may not respond if it is unavailable.

It is possible to add backup - or secondary - RAIDA by adding items with the same "name" to the directory. Then, RAIDA with the smallest ms could be contacted first.

The Directory may be cached in case it becomes unavailable or even hard-coded in an application as a backup for fault tolerance.

The values are case-insensitive and should be compared accordingly.

bkurl is the Backup URL in case name resolution fails for the url.

All the services use extension less urls.

Typically, the ms (milliseconds required to contact) and the status are to be determined by the client using the Echo Service.

The possible statuses are:

  • "unknown" because no attempt has been made to contact the RAIDA.
  • "ready" because an echo request was sent to the RAIDA and it came back "ready."
  • "error" because an echo request was sent to the RAIDA but there was an error.
  • "no_contact" because an echo request was sent to the RAIDA and it did not return any response.
  • "down" because the server is off-line for some reason.

Echo Service V 5.5.2017

Purpose:

The purpose of the echo API is to allow a program (or user) to establish that a RAIDA is ready to detect the authenticity of CloudCoins and how many milliseconds the contact requires.

The client sends the RAIDA an Echo Request and the RAIDA will respond with a Echo Response.

Echo Request:

Client uses HTTPS and GET method for the echo url located in the service folder on the RAIDA server.

Echo Request Example:

https://RAIDA0.CloudCoin.Global/service/echo

Echo Response Example:

Server returns a Response Object using JSON that describes the name of the server, the status, a message, and a timestamp:

{
"server":"RAIDA0",
"status":"ready",
"message":"Up: Detection agent ready to detect authenticity.",
"time":"2016-49-21 7:49:PM"
}

Rules:

  • The RAIDA may not respond if it is unavailable.
  • All Return Objects' key values are case in-sensitive and should be compared accordingly.
  • The names of the servers on Network 1 will always be one of 25 servers: RAIDA0 through RAIDA24. Note: server names are case-insensitive and should be compared accordingly.
  • In the future, if Doubling occurs, the names of the servers will have a network extension such as RAIDA0Net2 through RAIDA24Net2 where Net2 means they are on network 2.
  • The status will always be ready otherwise it will return an error. See General Errors.
  • The message will always be divided in two parts with a colon: The Subject and the Details.
  • The subject of the echo response will always be "Up" and the details will always be "Detection agent ready to detect authenticity." otherwise it will return an error. See General Errors.
  • The time is in GMT.

Echo Service Brief Mode V 5.5.17

Purpose:

Brief mode allows for the a shorter "ready" response. The RAIDA would only return one word. The hope is that it would use less bandwidth and may be faster.

Echo Request:

Client uses HTTPS to GET the echo page located in the service file on the RAIDA server. An extra "b=t" is added on the end of the request. It means brief=true.

Echo Request Example:

https://RAIDA0.CloudCoin.Global/service/echo?b=t

Echo Response Example:

ready

Detection Service V 5.5.17

Purpose:

The purpose of the Detect API is to allow the program or user to change the Authenticity Number in the RAIDA to a Proposed Authenticity Number so that ownership change of CloudCoin is possible.

Detection Request:

The program sends the RAIDA server an HTTPS GET request including the NN (network number), SN (Serial Number), AN (Authenticity Number), PAN(Proposed Authenticity Number) and Denomination of the CloudCoin that is to change ownership. The SN and the Denomination are like the CloudCoin's username.The AN is like the CloudCoins' password. The PAN is like a new password.

Detection Request Example:

https://RAIDA20.cloudcoin.global/service/detect?nn=1&sn=1&an=1836843d928347fb22c2142b49d772b5&pan=1836843d928347fb22c2142b49d772b5&denomination=1

Detection Response:

Server returns a Response Object using JSON that describes the name of the server, the status, a message, and a time stamp.

Detection Response Example If Passed:

{
 "server":"RAIDA1",
 "status":"pass",
 "sn":"1",
 "nn":"1",
 "message":"Authentic:1 is an authentic 1-unit. Your Proposed Authenticity Number is now the new Authenticate Number. Update your file.",
 "time":"2016-44-19 7:44:PM"
}

Note that the 1 after the word Authentic: is the serial number of the unit that was tested.

Detection Response Example If failed to authenticate:

{
 "server":"RAIDA1",
 "status":"fail",
 "sn":"1",
 "nn":"1",
 "message":"Counterfeit: The unit failed to authenticate on this server. You may need to fix it on other servers.",
 "time":"2016-44-19 7:44:PM"
}

Detection Response Example If failed because the denomination of the coin is not its real denomination (Someone is trying to falsify the denomination):

{"server":"RAIDA1","status":"fail","sn":"1","nn":"1""message":"Denomination: The item you are authenticating is a 250 units. However, the request was for a 25 units. Someone may be trying to pass you a money unit that is not of the true value ","time":"2016-11-21 9:11:PM"}

If failed because of missing or out-of-range GET NN parameter:
{"server":"RAIDA1","status":"error","message":"NN: The unit's network number was out of range or not on this server.","time":"2016-15-21 9:15:PM"}

If failed because of missing or out-of-range GET SN parameter:
{"server":"RAIDA1","status":"error","message":"SN: The unit's serial number was out of range.","time":"2016-15-21 9:15:PM"}

If failed because of missing or out-of-range GET Denomination parameter:
{"server":"RAIDA1","status":"error","message":"Denomination: The unit's Denomination was out of range.","time":"2016-04-21 9:04:PM"}

If failed because of missing or out-of-range GET PAN parameter:
{"server":"RAIDA1","status":"error","message":"PAN: The unit's Proposed Authenticity Number was out of range.","time":"2016-06-21 9:06:PM"}

If failed because of missing or out-of-range GET AN parameter:
{"server":"RAIDA1","status":"error","message":"AN: The unit's Authenticity Number was out of range.","time":"2016-07-21 9:07:PM"}

Otherwise Detect should return a General Error

Detection Service Brief:

The RAIDA responds with one word. A b=t is added to the GET request. Brief = True;

Detection Request Example in Brief Mode:

https://RAIDA20.cloudcoin.global/service/detect?nn=1&sn=1&an=1836843d928347fb22c2142b49d772b5&pan=1836843d928347fb22c2142b49d772b5&denomination=1&b=t

Detection Response Example in Brief Mode:

Server returns one word, either pass, fail or error.

pass

Fix Process:

Purpose:

The purpose of the Fix API is to allow the program or user to repair "fractured" CloudCoins. A fractured CloudCoin is a CloudCoin that has some RAIDA servers failing authenticity. The CloudCoin owners can request that the fractured server ask its trusted servers (Neighbors) to vouch for them. By default, each RAIDA requires three servers to vouch for CloudCoin in order to self-repair. There are four combinations of servers that the each RAIDA will trust. They will trust the three "corner" RAIDA on any of their four corners. With the numbers arranged in a circle like a clock, and the RAIDA being repaired being zero, the three servers needed to trust are -1.-5.-6 OR +1, -4, -5 OR -1, +4, +5 OR +1, +5 and +6. RAIDA12, for example, will trust RAIDA11 AND RAIDA7 AND RAIDA6 together, OR the three other combinations of three servers. Note that the Administrator for each RAIDA can change the server that their RAIDA trusts. Circle of tru

Ticket Service

Trusted Server Identification:

The program or user that has the fractured CloudCoin will identify the fractured RAIDA's trusted servers.

Rules:

  • There are four combination of three corner servers that are trusted. See the four-corner diagram above. Note the numbers wrap around like a clock (see image above).
  • In order to repair, a fractured RAIDA must receive three tickets from specific triad of these trusted servers.

Ticket Request:

Client makes a Ticket Request to trusted server triad. Note that there are three separate requests going to three separate RAIDAs.

Ticket Request Examples of an attempt to fix a fractured RAIDA1:

https://raida0.cloudcoin.global/service/get_ticket?nn=1&sn=16777005&toserver=1&an=7ac477841f5cce2889e4329a0e994ee3&pan=7ac477841f5cce2889e4329a0e994ee3&denomination=250

 https://raida2.cloudcoin.global/service/get_ticket?nn=1&sn=16777005&toserver=1&an=98f094b7ed7d0a3f80db7ef0b03c740f&pan=98f094b7ed7d0a3f80db7ef0b03c740f&denomination=250

These Ticket Request are the same as the Detection Request except that they include a "toserver" parameters. The toserver parameter describes the RAIDA number that is to be repaired (0 through 24). This facilitates advanced encryption between the fractured RAIDA and the trusted RAIDA if it becomes necessary.

Ticket Response:

The client will receive a "ticket" from each RAIDA that authenticates the Ticket Request. The ticket is exactly 44 characters in length and is a random and secret hexadecimal number. By default, the RAIDA servers will only honor a ticket that is less than 15 seconds old, but this amount can be changed by each RAIDA Administrator. Note that the "message" from the Ticket Response is not divided into subject and details when it returns a ticket.

Example Ticket: 23a399c5358fe88be678c45fa65747c81d31293cf44c

Ticket Response if successful:

{
"server":"RAIDA2",
"status":"ticket",
"sn":"1",
"nn":"1",
"message":"23a399c5358fe88be678c45fa65747c81d31293cf44c",
"time":"2016-40-21 10:40:PM"
}

The Ticket fails are identical to the Detection fails

Fixit.jpg

Fix Request:

The fix request combines the outcomes of three ticket requests to send to the fractured RAIDA. The tickets must come from three of the corner servers.

Fix Request Example attempting to fix RAIDA1:

https://raida1.cloudcoin.global/service/fix?
fromserver1=0&message1=4aa2b02d3d2279216009cfcdd8a04b46b24835f63632
&fromserver2=2&message2=5ce45a6141ac9cb00233b11a900ea5302e9745051659
&fromserver3=4&message3=23e45a6141ac9cb00233b11a900ea5302e9745051659
&pan=E9611BF6FCBB1CB58CB62A5FC24A4B39

Fix Response: The fix response tells the client if the fix attempt was successful or failed.

Fix Response Example If success in repairing the fractured RAIDA:

{
"server":"RAIDA1",
"status":"success",
"message":"Fixed: Unit's AN was changed to the PAN. Update your AN to the new PAN.",
"time":"2016-09-22 1:09:PM"
}

If failed because a server number is not between the range of zero to 24 (inclusive):

{"server":"RAIDA1","status":"error","message":"Server: Server 26 Out of Range.","time":"2016-39-22 11:39:AM"}
Note that the "26" number is a variable that will change.

If failed because the ticket (message) is not exactly 44 characters long:
 {"server":"RAIDA1","status":"error","message":"Ticket: Message 1 Out of Range.","time":"2016-39-22 11:39:AM"}
Note that the "Message 1" could be "Message 2".

If failed because a tickets (message) is not from a trusted server:
{"server":"RAIDA1","status":"error","message":"Trust: Server 2 Not Trusted.","time":"2016-39-22 11:39:AM"}
Note that the "2" number is a variable(0-24) that will change.

If failed because a GET parameters where not supplied ( message1, message2, fromeserver1, fromserver2 and pan ):
{"server":"RAIDA1","status":"error","message":"GET Parameters: You must provide a message1, message2, fromeserver1, fromserver2 and pan.","time":"2016-39-22 11:39:AM"}

If failed because one of the trusted servers could not be contacted by the fractured RAIDA server:
{"server":"RAIDA1","status":"error","message":"Connection: Could not connect to Server 0.","time":"2016-39-22 11:39:AM"}
Note: "The "0" number is a variable (0-24) that will change.

If failed because one of the trusted servers reported that the Ticket(message/RN) was invalid (not 44 hex symbols):
{"server":"RAIDA1","status":"error","message":"Remote Ticket: Server 4 said invalid ticket.","time":"2016-39-22 11:39:AM"}
Note: The "4" number is a variable (0-24) that will change.

If failed because one of the trusted servers reported that it did not authorize the Ticket ( Random Number ) and that the ticket was not found in its Fixit List:
{"server":"RAIDA1","status":"error","message":"Remote Ticket: No Ticket found on Server 2.","time":"2016-39-22 11:39:AM"}
Note: The "2" number is a variable (0-24) that will change.

If failed because one of the trusted servers' databases reported some kind of error:
{"server":"RAIDA1","status":"error","message":"Remote Ticket: Server 4 database said invalid ticket.","time":"2016-39-22 11:39:AM"}
Note: The "2" number is a variable (0-24) that will change.

If failed because one of the trusted servers reported a fixit-log time that was longer than the fractured RAIDA allows for:
{"server":"RAIDA1","status":"error","message":"Time: Only 15 seconds where allowed for the fix but server 2 took 29.","time":"2016-39-22 11:39:AM"} 
Note: The 15 seconds is a variable that can be changed by the RAIDA Administrator. The "2" number is a variable (0-24) that will change.

If failed because one of the trusted servers errored while trying to connect to it:
{"server":"RAIDA1","status":"error","message":"Connection Exception: Server 0 System.Net.WebException: The remote server returned an error: (500) Internal Server Error. at 
System.Net.HttpWebRequest.GetResponse() at ASP.service_fix_aspx.Page_Load(Object sender, EventArgs e)//raida0.cloudcoin.global/service/hints?rn=f67d8b84ed22b806ac81f00227ca5637476a9197ef6a.","time":"2016-09-22 1:09:PM"}
Note: The "0" number is a variable (0-24) that will change.

If failed because the two trusted servers returned different serial numbers (they should return the same serial number):
{"server":"RAIDA1","status":"error","message":"Mismatch: The Serial Numbers specified by the trusted remote servers did not match.","time":"2016-09-22 1:09:PM"}

If failed because one of the trusted servers returned a serial number that was invalid (Greater than 16,777,216 or less than 1:
{"server":"RAIDA1","status":"error","message":"Remote SN: The trusted server provided an invalid Serial Number.","time":"2016-09-22 1:09:PM"}
Note: The "0" number is a variable (0-24) that will change.

General Errors:

Purpose:

The purpose of custom errors provided in JSON form is that webapplications can more easily handle common errors. Note: RAIDA Administrators may turn off custom errors in order to troubleshoot problems. This assumes that Custom Errors are turned on in the RAIDA servers' webserver.

{"server":"RAIDA1","status":"error","message":"500: Internal Server Error","time":"2016-09-22 1:09:PM"}
{"server":"RAIDA1","status":"error","message":"404: Not Found","time":"2016-09-22 1:09:PM"}

The failure numbers will have values over 400.

  • 4xx Client Error.
  • 5xx Server Error.
  • 6.3 Cloudflare.