ENGAGE - Credential Sort and Encryption

Table of Contents

1. Introduction 3

2. How do Alliance Partner’s need to sort? 3

3. Credentials with Secondary Credential Data 3

4. What does the 32 Byte Credential look like inside of the Door File 4

5. How do I turn PrimCred into 16 bytes? 4

6. “Degraded” or “Optimized” Search Modes 5

6.1 Difference between “Degraded” and “Optimized” search modes 5

1. What will a sorted user database look like? 5

2. What type of encryption will be used? 6

8.1 Encryption Type 6

8.2 Encryption Example 6

1. What should be sent to the lock in the door file? 6

Introduction

How Do Alliance Partner’s Need to Sort?

• Sort on the 16 bytes of Primary Credential Data (PrimCred)

• Sort on the unencrypted values of the PrimCred

• Sort the PrimCred from smallest to largest

• Encrypt both the PrimCred and the ScndCred with the Site Key

Credentials with Secondary Credential Data

Sort only on the PrimCred and ignore any ScndCred’s present in the user record. The lock will handle looking backwards and forwards if multiple PrimCreds exist with unique ScndCreds.

Keep in mind that secondary credentials usage is the equivalent to the second credential in a Credential + Credential sequence (example: card + pin). The secondary credential is only used once the primary credential has already been matched. In the case where there are no secondary credentials just use “null” as your secondary credential (scndCr) with a credential type (of “null”).

NOTE: You cannot have a mixture of a primary credential without a secondary credential specified and then the same primary credential again with secondary credentials in the same door file. When the lock matches a primary credential where there is no secondary credential, it will act upon that entry and will not search for any other entry that may contain a secondary credential.

NOTE: Including two identical credentials in the same door file will result in the lock treating the database as unsorted. Please avoid duplicate entries in the door file to ensure optimized operation.

What Does the 32 Byte Credential Look Like Inside the Door File?

How Do I Turn PrimCred Into 16 Bytes?

Pad the remaining bytes with 0xFF.

NOTE: ENGAGE edge devices do not support primary or secondary credentials unencrypted value of all 0xFF. 0xFF should be used for padding of the unencrypted credential data, not for the entirety of the unencrypted credential info.

Example:

• Starting with a 26-bit credential [0x23C5981].

• Left-shift the data until you get to the first byte boundary (32-bits, 40-bits, 48-bits, or 64-bits)

  • For a 26-bit credential, you need to left-shift (32-26=6); 6 times.

  • Left-shifting 6 times results in [0x8F16 6040].

• Finally, the remaining 12 bytes are padded with 0xFF which gives a 16 byte value of [0x8F16 6040 FFFF FFFF FFFF FFFF FFFF FFFF]. This value is now left justified and padded.

“Degraded” or “Optimized” Search Modes

The lock will record an audit stating the result of a user database presort verification upon downloading a new user database. The result will state if the presort verification succeeded (user database is confirmed to be sorted) or failed (user database was not sorted upon downloading from the OEM).

Difference Between “Degraded” and “Optimized” Search Modes

When the door file is sorted (according to the Section below, "What Will a Sorted User Database Look Like?, the lock performs a binary search on the primary credential. This enables a very rapid search of the entire 5,000 user door file – usually within a hundred milliseconds.

When the door file is not sorted, the lock will remain functional, but must check every credential starting from the first entry to the final entry in the file. As a result, a search of the “last” user in the file may take a few seconds to complete, during which the user has no indication that anything is going on at the lock. So the user will present his/ her card to the lock and the lock will beep, indicating that the card was read, but will give no other UI until a few seconds later when the credential is matched and the door unlocks.

Keep in mind that “degraded” mode is completely detectable and avoidable. The lock will tell the server when the door file is not sorted as an audit.

What Will a Sorted User Database Look Like?

Let’s look at an example of 5 users. We will only list the PrimCred values since this is the only field that needs to be sorted.

What Type of Encryption is Used?

Encryption Type

Each set of Credential Data (primeCred = 16 total bytes, scndCr = 16 total bytes) will be encrypted using AES-256 Cipher-Block Chaining (CBC) with an Initialization Vector (IV) of zero, where the key is your secure Site Key. Depending upon the tool used to encrypt the credential data, it may be easier to use “Electronic Codebook” (ECB) for each credential since the IV is zero for each credential and they are not chained together.

Encryption Example

For the table below, the site key was: [0x1234 5678 90AB CDEF 1234 5678 90AB CDEF 1234 5678 90AB CDEF 1234 5678 90AB CDEF]. The online tool at aes.online-domain-tools.com was used to generate the encrypted values – this tool can do both CBC and ECB. Other tools can only use ECB and will work just fine. An example of another tool can be found here: http://www.hanewin.net/encrypt/aes/aes-test.htm

What Should be Sent to the Lock in the Door File?

Taking the example in section 8, user 5’s primary credential should be 16 bytes. See the example below:

“primeCred”:”34110EA549AA549AA73FF06DC93B63B4”,

“prCrTyp”:”card”,

“scndCr”:”null”,

“scndCrTyp”:”null”