Primary Credential Encryption Changes

There were some enhancement changes made to security by introducing changes to the encryption of the Primary credential which is part of the API request body.

Existing Encryption Methodology for Primary Credential

NOTE: This is still applicable for WiFi mode of operation.

1. Primary credential is 8 bytes (16 hex digits) in length.

2. The credential value is filled with b0s until the byte boundary and 0xFF for the rest of the bytes (to form an 8 byte credential ID).

3. MT20W fills 0xFF as the most significant 8 bytes to form a 16 byte (128 bits) block of data for encryption.

4. MT20W encrypts (AES 256) the 16 bytes (from step 2) using the Site Key as the encryption key and zeros for Init Vector.

5. This encrypted value (16 bytes OR 32 hex digits) is encoded in Base 64 format (24 bytes) and sent as the Primary credential data to ORCA.

6. ORCA decodes the Base 64 encoded data and then decrypts the Primary value from step 4, using the site key as the decryption key and zeros for Init Vector.

7. The decryption results in a 16 byte (32 hex digits) data and ORCA pulls the least significant 8 byte to get the Primary Credential value.

Bit Format for UNencrypted Data: 16 bytes

Encryption Example

Raw card data as printed on the card: 0x9400016009A4

Encryption Changes for Primary Credential

The Primary credential is 8-bytes (16 hex digits) in length. The following steps are used to encrypt the Primary credential:

1. The credential value is filled with binary bit 0s up to the byte boundary and 0xFF for the rest of the bytes (to form an 8-byte credential ID).

2. The MT20W fills 0xFF as the most significant 8-bytes to form a 16-byte (128 bits) block of data.

3. A random number of 12 bytes is generated and used as the first part of data to be encrypted. This is followed by the Primary credential of 16-bytes mentioned in the previous step.

4. Two additional bytes of 0x00s are added to the data to make it 30-bytes long.

5. CRC is calculated on this entire data and placed in the last two bytes of the 32-byte unencrypted data array.

6. The MT20W encrypts (AES 256) the 32-bytes (from above step) using the Site Key as the encryption key and zeros for Init Vector.

7. This encrypted value (32-bytes OR 64 hex digits) is encoded in Base64 format (44-bytes) and sent as the Primary credential data to ORCA.

Bit Format for UNencrypted Data: 16 bytes

Encryption Example

Raw card data as printed on the card: 0x9400016009A4.

Decryption of Primary

API must decode Base 64 and decrypt the Primary value using the site key as the decryption key. The decryption results in a 32-byte (32 hex digits) data and API pulls the masked 8-bytes to get the Primary Credential value.

The following steps are used to decrypt the Primary credential:

1. Decode the base64 formatted Primary credential.

2. Decrypt the decoded data using the Site key. This results in 32-byte un-encrypted Primary credential (Byte array of Hex values).

3. The last two bytes of this array contains CRC. This CRC follows [LSB, MSB] format, hence reverse the CRC byte array.

4. Compute the CRC16 for the first 30 bytes excluding the CRC.

5. Compare the CRC obtained with the CRC of incoming request. If the CRC check fails, then API returns Bad Request with a message Credential data is corrupt.

6. Once the CRC check is passed, Primary data (Total of from Byte[12] to Byte[27] – includes raw card data (8bytes) and padded 0xFF(8bytes)), is extracted from UNencrypted data. (See the Section: Encryption Changes for Primary Credential).

Computing CRC16

This is the method used to compute CRC. 0x10FFFF is used for masking in CRC 16 calculation and 0x1021 is the polynomial used.

public uint ComputeCrc16(byte [] bytes)
     {  
       uint crc = 0;
       foreach (byte b in bytes)
       {  
         crc ^= (uint) (b << 8);
         for (int i = 0; i < 8; i++)
         {
           if ((crc & 0x8000)! = 0)
           {
             crc = (((crc << 1) & 0x10FFFF) ^ 0x1021);
           }
           else
           {
             crc <<= 1;
           }
         }
       }
       return crc;}

Last Modified: October 15, 2019