Authentication Services (Command Group 1)

Key Terms

Command Codes

Code Meanings

DETECT

DETECT does not require a PANs (Proposed Authenticity Number) and requires less bandwidth and processing power than P'OWN. This is used as a fast way of checking to see if tokens are authentic as in a "Check Health" function on a client. Use UDP if sending less than 65 notes and TCP if sending more. It is recommended that this service only be used if you have already used the DETECT SUM service and it responded with an All Fail status.

Response Body if All Pass or All Fail:

Response body only present if there is mixed content:

DETECT SUM

Like DETECT, but does not require ANs. Instead, the ANs are added up and put in one number. This service can be much faster than DETECT, 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.

REQUEST: Example Request Body with four tokens:

Response Body if All Pass or sum does not add up (All Fail):

P'OWN

P'Own means "Password Own". The client sends the Serial Number, Authenticity Number and the Proposed Authenticity Number. The AN and PAN must be different or an error will be returned with a status that the ANs and PANs matched. The server checks to see if the AN that the client sent matches the AN in the table. If it matches, the AN in the table is replaced with the PAN provided by the client and the "pass" status is returned. If multiple tokens are sent then the server may return "all pass" or "all fail" status. If some of the tokens are found authentic and some are found counterfeit, then the "mixed" status is returned along with a bitfield. The bitfield has one bit per token. A bit set to '1' is a pass and each bit set to '0' is a fail. Zeros are padded to the byte. Since the server only returns whole bytes, the client must know when to stop reading the bitfield based on how many tokens were sent.

Like all services, the p'own allows the client to send a 16 byte challenge. The server returns the first four bytes of an MD5 hash of this challenge in the response header. This allows the client to be certain that the response came from the RAIDA since only the RAIDA would be able to decrypt the challenge.

REQUEST: DN (Denomination) is one byte. SN(Serial Number) is 4 bytes

MS means Mixed Status. Each bit returned represents the status of one token. If the bit is a zero then that token has failed. If the bit is a 1 then that token is authentic.

P'OWN SUM

The client must add up all of the AN numbers to get a sum. Then it includes all the SNs of the tokens that are part of the equation.

Steps for calculating the XOR-ed sum are the same as for the DetectSum service.

You will need to calculate the new Authenticity Number by adding it to the AD. This is done by summing the AN with the AD and truncating the number. so D4785BED + 48BD4125 = 11D359D12 but we drop the leading 1 so the new AN becomes 1D359D12.

MS means Mixed Status. Each bit returned represents the status of one token. If the bit is a zero then that token has failed. If the bit is a 1 then that token is authentic.

HASH PANG

Not Implemented Yet

The HASH PANG service allows for the inclusion of Serial number ranges. Suppose that a user is changing the passwords for coins SN 3000 - 4000. Instead of needing to list every Serial number, the call just includes the range. This makes the service good for handling large requests. The client must evaluate an authenticity number for a group of coins. Then the client sends the number to the RAIDA servers. The RAIDA servers in turn do the same evaluation for the serial numbers. If the resulting AN matches the AN sent by the Client the result is considered authentic. The client can send ranges of serial numbers along with individual numbers.

The algorithm used to evaluate the Group Hash is md5. It doesn't have to be strong because the RAIDA server is supposed to already know all the ANs of the original coins. The client iteratively adds each AN to the Group MD5 hash. In the end the Client gets the final MD5 hash that becomes the Group hash.

On each calculation the Serial Number is prepended to the AN

sn 10, an 3031900e6c47411da57192574faa61c3
sn 20, an 5ab8661c15c44bc995f5bda379efdaf4
sn 30, an ed797feb38b0416ba2bd1d7db29f68d7

// binary representation 
input0 {0x0a, 0x30, 0x31, 0x90, 0x0e, 0x6c, 0x47, 0x41, 0x1d, 0xa5, 0x71, 0x92, 0x57, 0x4f, 0xaa, 0x61, 0xc3}
input1 {0x14, 0x5a, 0xb8, 0x66, 0x1c, 0x15, 0xc4, 0x4b, 0xc9, 0x95, 0xf5, 0xbd, 0xa3, 0x79, 0xef, 0xda, 0xf4}
input2 {0x1e, 0xed, 0x79, 0x7f, 0xeb, 0x38, 0xb0, 0x41, 0x6b, 0xa2, 0xbd, 0x1d, 0x7d, 0xb2, 0x9f, 0x68, 0xd7}

    md5Init(&ctx);
    md5Update(&ctx, (uint8_t *)input0, strlen(input0));
    md5Update(&ctx, (uint8_t *)input1, strlen(input1));
    md5Update(&ctx, (uint8_t *)input2, strlen(input2));
    md5Finalize(&ctx);

The resulting Group hash is 21e46bbb18d8ce646a840ccda4602f56
                

The call supports sending a range of serial numbers.

Example with three ranges and three single coins: