RAIDA Healing Services (Command Group 2)
These services allow the RAIDA to heal when a token becomes counterfeit on one RAIDA and authentic on others.
Command Codes
| Command Code | Service |
|---|---|
| 40 | Get Ticket |
| 41 | Get Ticket By Sum |
| 50 | Validate Ticket |
| 60 | Find |
| 80 | Fix |
Get Ticket
The GET TICKET service is nearly identical to DETECT except a Ticket is returned. A ticket is a 4-byte random number that the RAIDA gives to the caller as proof that the tokens are authentic. This ticket can be used by the client to prove its authenticity to other RAIDA. The Ticket can be claimed one time by each RAIDA server. After the ticket grows old it times out.
The client gets a one ticket from a RAIDA and can send that ticket to 24 other RAIDA.
Example Request Body with four tokens:
| Response Status | Code |
|---|---|
| All Pass | 241 |
| All Fail | 242 |
| Mixed | 243 |
Example Response if all pass:
Example Response if mixed:
Get Ticket By Sum
Like DETECT SUM, except it returns a ticket. The ANs are added up and put in one number. This service can be much faster than GET TICKET, especially if there are lots of tokens being detected. Use UDP if sending between 65 and 275 notes. Use TCP if sending more than 275 notes, you should use TCP and it is probably better to use regular detect in case one of the tokens is bad.
The sum is calculated as per these steps:
- Each AN of every coin is converted to four 32 integers from a byte array
i0 = an[0] | an[1]<<8 | an[2]<<16 | an[3]<<24 i1 = an[4] | an[5]<<8 | an[6]<<16 | an[7]<<24 i2 = an[8] | an[9]<<8 | an[10]<<16 | an[11]<<24 i3 = an[12] | an[13]<<8 | an[14]<<16 | an[15]<<24
- The integers are XOR-ed to the accumulator (XOR-ed sum). The initial value of the XOR-ed sum is zeroes
sum[0] ^= i0 sum[1] ^= i1 sum[2] ^= i2 sum[3] ^= i3
- Steps #1 and #2 are repeated for every coin
- The resulting sum is converted to a byte array (SU SU SU SU SU SU SU SU SU SU SU SU SU SU SU SU)
SU = sum[0] SU = sum[0] >> 8 SU = sum[0] >> 16 SU = sum[0] >> 24 SU = sum[1] SU = sum[1] >> 8 SU = sum[1] >> 16 SU = sum[1] >> 24 SU = sum[2] SU = sum[2] >> 8 SU = sum[2] >> 16 SU = sum[2] >> 24 SU = sum[3] SU = sum[3] >> 8 SU = sum[3] >> 16 SU = sum[3] >> 24
REQUEST: Example Request Body with four tokens:
| Response Status | Code | Note |
|---|---|---|
| All Pass | 241 | All the tokens were authentic. |
| All Fail | 242 | Really means sum does not add up. So, the tokens may all be good but just one is bad so the DETECT service should be run to know exactly which tokens are bad. |
Example Response if pass:
Example Response if fail:
Validate Ticket
The Validate Ticket protocol allows the client to see if a ticket belongs to a serial number. It is used to prove that a person owns a token without them having to show the token. This is useful if you are using RAIDA Tokens to authenticate a person or thing in your own application.
Validate ticket is not encrypted.
EXAMPLE BODY OF REQUEST:
EXAMPLE REPLY: Shows seven serial numbers returned. The number is divisible by 5 bytes.
Find
A token is in Limbo when the client makes a request to POWN but there is no response from the RAIDA. The client is uncertain if the RAIDA got the message and turned the AN to the PAN or if the RAIDA did not get the message and the AN is unchanged.
To get the token out of Limbo the client sends a Find request and sends the AN and the PAN to the RAIDA and asks which one is it's AN. The RAIDA will tell the Client if the AN is authentic, the PAN is authentic or if neither is authentic.
The Fix Lost service allows the caller to send both AN and PAN to see if they are authentic. The service then responds with the correct answer. If neither are correct, it will respond with a status of "Neither". '0x00'= Neither. "0x01" = AN and "0x02"=PAN.
Example with four tokens:
Response Statuses:
| Code | Status | Description |
|---|---|---|
| 208 | Find All Neither | Neither the ANs or the PANs on any of the tokens were authentic |
| 209 | Find All AN | The ANs of all of the tokens were authentic |
| 210 | Find All PAN | The PANs of all of the tokens were authentic |
| 211 | Find mixed | The tokens had a mix of ANs good, PANs good and Neither good. |
Mixed Results Codes:
| Hex Code | Meaning |
|---|---|
| 0x00 | Neither the AN or the PAN presented by the Client was authentic. |
| 0x01 | The AN is authentic and the RAIDA has it in its database. |
| 0x02 | The PAN is authentic and the RAIDA has the PAN as in its database. |
Response Body if Results are Mixed for four tokens: One byte per token
Fix
All 25 RAIDA should agree that a token is authentic. When all RAIDA are not in agreement about the authenticity of a token, we call the token "Fractured" or "Fract" for short. The Fix protocol allows for Fract tokens to become whole.
The fix protocol must look at two config files to determine which other RAIDA to trust and how many of the RAIDA need to be in agreement to switch the AN to the client's request. All of the file's data are located in the file's name and the file is located in the Config folder.
Example config files:
- Example config file that tells this RAIDA can accept tickets from all 25 RAIDA and it needs 13 good tickets to turn the AN:
trusted.1.1.1.1.1.1.1.1.1.1.1.1.1.1.1.1.1.1.1.1.1.1.1.1.1.13.config
- This example file name shows that the RAIDA is to trust no other RAIDA except for RAIDA 0 and that it must have one good ticket:
trusted.1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.1.config
- This example show that it can get tickets from any RAIDA except 10 and that it needs 13 good tickets:
trusted.1.1.1.1.1.1.1.1.1.1.0.1.1.1.1.1.1.1.1.1.1.1.1.1.1.13.config
Each RAIDA Trusts the majority of other RAIDA. The client can get 'Tickets' from RAIDA that think the token is authentic and give them to the fract raida. The RAIDA requires 13 of the 25 RAIDA to change its AN to the AN that the client specifies.
The fract RAIDA will always receive 25 tickets although they will all be zeros unless they actually contain a ticket. So the majority of the tickets are just place holders.
The Fix protocol may receive empty tickets with all "00000". In this case there is no ticket.
Client Steps
- Client receives a "fail" from one or more of the RAIDA (up to 12).
- Client requests tickets from 13 or more RAIDA that are good.
- Client sends all the tickets to all the RAIDA that are fracked (received a fail).
- RAIDA checks the tickets. If the tickets are good then the fracked RAIDA set the AN that the clients specifies.
RAIDA Steps
- The fracted RAIDA receives Tickets with the Serial Numbers of the tokens that are fract and the Proposed Authenticity Numbers (or Proposed Authenticity Number Generator) that client wants to give them.
- The fracted RAIDA sends the Tickets to all the trusted RAIDA in parallel using the VALIDATE TICKET protocol.
- Trusted RAIDA respond with the serial numbers associated with they ticket.
- Fract RAIDA compares the Serial Numbers returned by the Good RAIDA with the Serial Numbers specified by the Client.
- If there are 13 Good RAIDAs that agree with what the Serial numbers that the client sent, the Authenticity Numbers on the Fract RAIDA are changed.
- All Pass is returned if all the token were fixed. All fail if none of the tokens were fixed. Mixed if some of the tokens were fixed.
Fix Algorithm
Fix allows you to fix multiple tokens using tickets that it got from the Get_Ticket service. Each ticket can only be used one time per RAIDA. Each RAIDA can use the same ticket to fix. This allows the client to use all the tickets returned from a Get_Ticket request to fix all the fracked tokens on all the RAIDA without needing to go and get more tickets. The Fix then calls the "Validate Ticket" service and sees what SNs are returned. If 13 out of 25 RAIDA return the same SN, that SN's ANs are changed to the PAN supplied by the Client.
Version 0 Example Request Body with four tokens:
The PAN is determined by concatenating the RAIDA ID, Serial Number and the PG. Like this:
WARNING: Client should send a different PG to each RAIDA otherwise the token will be stolen by any other RAIDA admin.
- The Client will generate a 16 byte random seed.
- The Client will send this seed to the RAIDA. This seed is called a "PAN Generator".
- The Client and the RAIDA will use an algorithm to figure out what the Authenticity numbers will be for each serial number that fixes.
- The Authenticity numbers for each serial number will be calculated by putting together the RAIDA Number (one byte), the token's denomination (one byte) and serial Number (four bytes) and the PG (16 bytes).
Example PAN calculation:
1 + 0xFE + 1632435 + 9195C7A60CF0471BBE9B66144F5681C5 and then running an MD5 hash against that.
Then the concatenated string is:
PAN = MD5("01FE18E8B39195C7A60CF0471BBE9B66144F5681C5");
So the AN will be:
fd1495be732ab2f6959559f3041c72c0
Example Request Body With Actual Bytes for an attempt to fix RAIDA 12 for four tokens:
Example Response:
There will only be a response body if there is mixed results.