ENGAGE JSON Server Commands

Table of Contents

1. Introduction 4

2. Encryption and Authentication 4

2.1 Cipher Block Chaining 4

2.2 Sequence Number 5

1. JSON Structure 5

2. Command Structure 5

3. Server Commands 6

4. Server Command Example 6

5. Sequence Recovery/Command Acknowledgment 7

6. Additional Example Server Commands 11

8.1 Unlock command with Sequence number = 1 and Relock Delay of 3 seconds 11

8.2 Reset sequence command with Sequence number = FFFF 11

8.3 Unlock command with Sequence number = 0 and Relock Delay of 3 seconds 11

8.4 Reset sequence command with Sequence number = 1A2B 11

8.5 Unlock command with Sequence number = 1A2C and Relock Delay of 10 seconds 11

Introduction

The purpose of this document is to describe how lock control commands can be sent to operate an ENGAGE enabled lock. These commands will use the existing JSON framework which will originate from a cloud based server and passed through a mobile app to the lock via BLE.

Encryption and Authentication

In order to prevent “replay” attacks as well as other “hacking” attempts several security measures will be employed for the lock control commands.

Each command will be encrypted using the AES-256 CBC method of encryption employing a 32 byte Site Key and 16 byte Initialization Vector (IV).

Cipher Block Chaining

Every 16 byte block encrypted command is chained to the next.

At the beginning of every new server command sequence a default Initialization value is used. Every subsequent command is then chained from the last (this is only applicable if multiple commands are sent in a single srvCmds array JSON object).

This default IV is 0.

Sequence Number

To guard against replay attacks a sequence number is used. It is dictated by following rules

• The server shall automatically monotonically increase the sequence number for every command sent.

• The lock shall disregard any command that is not greater than the last sequence number + 1.

  • A skip forward in sequence number of more than 1 is invalid.

The sequence number has a range of 0 to 65535 and will automatically roll over.

JSON Structure

The server command will be embedded in the existing JSON structure as a primary tag with the name “svrCmds”. This object type will be an array of strings that are the 16 byte encrypted commands where each byte is represented in hexadecimal format. The structure is illustrated in the code block below:

Commands may be up to 16 bytes including the length and padding bytes.

{
    "svrCmds": [
        "4D857D2408B00C3DD17F0C4FFCF15B97"
    ]
}

Command Structure

Table 1: Command Structure

Server Commands

Table 2: Server Commands

Server Command Example

Length = 0x08, Seq # = 0x05, Serial # = 0x72697331, Command = 0x11, Value = 0x03

Table 3: Server Command Structure

Using a Site Key of (hexadecimal):

546869732069732074686520416C6C6567696F6E2067617465776179206B6579

And IV of:

00000000000000000000000000000000

The encrypted command would be (using http://aes.online-domain-tools.com/ or http://extranet.cryptomathic.com/aescalc/index):

22ADF577775CA4D3890021F3ECFFF420

And the JSON would look like (in compacted form with no whitespace or newlines:

{“svrCmds”:[“22ADF577775CA4D3890021F3ECFFF420”]}

Sequence Recovery/Command Acknowledgment

In the event a command is not received by the lock or the sequence number becomes out of sync, a mechanism to recover must be implemented. To implement such a mechanism, the lock will send an application level acknowledgment (ACK) with a value of 0xACED for momentary unlock and 0xACEF for reset sequence number back to the MAPP. Once the command has been processed, it is passed back to the server.

The ACK is sent to the MAPP using the TxData gatt characteristic, which is part of the DataTransfer service, and the MAPP translates this and passes it on to the server.

<service uuid="52052C11-E701-4782-99F5-8CE88DBB1500" type="primary" advertise="true">
    <description>DataTransfer</description>
    <characteristic uuid="52052C11-E701-4782-99F5-8CE88DBB1506" id="TxData">
        <description>TxData</description>
        <properties notify="true" />
    <value variable_length="true" length="20" type="user" />
</characteristic>
</service>

If the server doesn’t receive the ACK within a defined timeout period it will:

1. Send the command with a sequence number of 1 to see if the lock has been powered cycled. If the server doesn’t receive the ACK:

2. Send the reset sequence number command. If the server doesn’t receive the ACK:

3. Send another reset sequence number command with a value that is not the same as the previous sequence number.

If the above retry attempts are not successful, manual intervention will be necessary at the lock. After successful sequence number synchronization, signified by an ACK to the reset sequence number command, the user will need to request the previous command again from the MAPP.

To reset the sequence number a random number between 1 and 65536 (not zero) will be generated at the server which will be sent in the sequence number bytes to the lock (there will not be a payload for this command). The lock will save this new sequence number which it will then begin incrementing for subsequent commands.

Figure 1

Figure 2

Additional Example Server Commands

Site Key:

F1991F50676E4CAEC6E81BCDD28196839B63CDE54991684A0F455CE9F4D05359

IV:

00000000000000000000000000000000

Last four bytes of Lock Serial Number:

72697331

Unlock command with Sequence number = 1 and Relock Delay of 3 seconds

08000172697331110301000000000000

Encrypted command:

E0091670913535C28B5E63C45D83544E

Reset sequence command with Sequence number = FFFF

07FFFF72697331F40100000000000000

Encrypted command:

F323C855E1F04E099BAB3BF846F44EC4

Unlock command with Sequence number = 0 and Relock Delay of 3 seconds

08000072697331110301000000000000

Encrypted command:

765A20813C94C0E0E9E4F03E9AFED0D5

Reset sequence command with Sequence number = 1A2B

071A2B72697331F40100000000000000

Encrypted Command:

2FA0A9E859667AD945D807F51DB80196

Unlock command with Sequence number = 1A2C and Relock Delay of 10 seconds

081A2C72697331110A01000000000000

Encrypted command:

102E93E60D4B5105B7EEEAE321201535