ENGAGE - SAM No Tour Integration

Table of Contents

1. Introduction 4

2. Integration 4

2.1 No Tour JSON 5

2.2 Door File 5

2.3 No Tour card data 6

2.3.1 Jaguar sector 6

2.3.2 No Tour Commands: 7

2.3.2.1 Add Credential: 7

2.3.2.2 Add Credential Example: 8

2.3.2.3 Delete Credential: 9

2.3.2.4 Repurpose credential: 11

2.3.2.5 Replace credential: 12

2.3.2.6 Unblock Credential for Reuse: 14

2.3.2.7 Remove Blocked Credential from Door File 14

2.3.2.8 Using Group ID: 15

1. Data Encryption 16

3.1 No Tour End-to-End Encryption 16

3.2 No Tour Data Encryption Example 17

1. MT20W 17

2. Credential ID Inputs 17

3. No tour databases (when touring) 18

4. Appendix A: Credential Attribute 19

5. Appendix B: Device Schedules 20

6. Appendix C: Additional Information 21

Introduction

Abbreviations Used In This Document

No Tour provides the ability to use a cardholder’s smartcard to change an ENGAGE lock’s cardholder database and certain configurations. The lock does not have to be physically visited by the property manager in order to perform administrative actions such as:

• Adding a credential

• Deleting a credential

• Replacing a lost credential

• Changing certain configurations

The cardholder’s smartcard will be programmed by the property manager and it is the cardholder who carries the programmed card with the commands to the lock. No Tour should be used when the architecture is described as “offline” or not actively communicating with a host. It is the responsibility of the Software Alliance Member (SAM) to develop a mobile application to connect via Bluetooth Low Energy to the ENGAGE device and deliver the payload necessary to set up the device for No Tour operation.

This document describes the steps necessary for No Tour SAM integration.

Integration

To integrate No Tour, a SAM will need to create their own mobile application. This is necessary for the edge device to be provided with the lock ID, schedule, and Group IDs over BLE (Details of these tags below).

For Engage Devices commissioned before the release of ENGAGE 5.2 (Q3 2017):

• For SAM managed sites with either an MT20W or Schlage Control device commissioned to the site, locks that are commissioned with the ENGAGE mobile application will pre-populate the lock ID during the commissioning process therefore enabling No Tour for all No Tour capable devices. Lock ID’s will be assigned sequentially starting with number 1. It is recommended that all of the No Tour configuration data be overwritten by the SAM provided mobile application (including the lock ID) in order to prevent multiple edge devices with the same lock ID being assigned.

• For Engage Devices commissioned after the release of ENGAGE 5.2 (Q3 2017)

• The ENGAGE mobile application will no longer pre-populate the lock ID during commissioning. Therefore, the SAM mobile application is required to send the requisite configurations to the lock in order to allow No Tour to work properly. This prevents the possibility of multiple edge devices with the same lock ID being assigned.

NDE Units manufactured before March 2016 currently do not have support for NDE No Tour. NDE and LE Units manufactured before March 14 2017 currently do not have support for MiFare Plus cards Please contact the Allegion Technical Services team for No Tour support of NDE units manufactured before this date and MiFare Plus support of NDE and LE units.

No Tour JSON

The JSON configurations that need to be provided to the ENGAGE device for No Tour are:

• Lock ID (lockId)

  • The Lock ID is the unique device ID identifying the lock/device within the Site.

• Jaguar Sectors (jagSectors)

  • Jaguar Sectors refer to the location of the directory sector on the No Tour credential (default sector 2 in jagSectors bitmask form 00000100 = “jagSectors”: 4). Currently, this is the only supported sector, therefore “jagSectors” must always be set to 4.

• Group IDs (groupIds)

  • Group IDs are used to assign multiple devices to one group. Up to 16 groups can be created within the site.

The definition of the JSON configurations can be found in the Schlage Engage JSON Data Structures document.

These JSON commands are in addition to the commands required to setup the device.

NOTE: For NDE and LE locks, a Lock ID of 0xFFFF (65535) will disable No Tour.

Door File

Before a No Tour enabled edge device can allow passage to any No Tour credential the device must first be provided with at least one credential schedule through the JSON tag “schedules”. Please see Appendix B: Device Schedules, for information on how the No Tour credential information on the card corresponds to the “crSch” and “schedules” JSON tags. The edge device must also be provided with the JSON “db” tag and “deleteAll” must be set to true (1) at least for the first door file that is provided to the edge device. This door file JSON is in addition to the No Tour JSON from above which comes as part of the “config” JSON tag. For more information please see the Schlage ENGAGE – JSON Data Structures document. An example door file with the “db”, “deleteAll”, and “schedules” tags is included below for ease of reference.

{"db":{"usrRcrd":{"deleteAll":1,"delete":[],"update":[],"add":[]},"schedules":
[{"days":["Mo","Tu","We","Th","Fr","Sa","Su"],"lngth":1439,"strtHr":0,"strtMn":0}],
"autoUnlock":[],"holidays":[]}}

No Tour card data

No Tour card data is designed to go into sectors 2-14 of the Smart card. The following section describes how the No Tour card data needs to be formatted.

Jaguar sector

A ‘Jaguar’ sector works as a directory that contains a list of doors and pertinent information for each door.

Within this directory sector, the first four bytes are allocated for the credential type and reserved bytes. The following bytes are in 4 byte increments containing the door ID which could be a group ID or lock ID followed by the sector location of the card data and the pending bit. The lock ID is unique for each device in the site, the same group ID can be assigned to multiple devices in the site.

The table below show’s an example of the Jaguar sector in Sector 2 (default) of a SMART credential. Note this is 0 based, thus default sector 2 in jagSectors bitmask form 00000100 = “jagSectors”: 4

Currently this is the only supported sector therefore “jagSectors” must always be set to 4.

The status byte has the following format:

• Bit 0 – Pending command (1-Command pending, 0-No pending commands).

• Bit 1 – Door or Group ID (0-Door ID, 1-Group ID)

• Bit 2-7 – Reserved (set to 0s)

When using a lock ID, the device will reset the pending command bit. When using a group ID, the pending command bit will not reset due to its ability to be assigned to multiple devices in the site.

Table 1 displays how the data is on the SMART credential for a Jaguar (directory) Sector. Due to the size of the sector, eleven DOOR IDs is the max that a No Tour credential can support.

Table 1: SMART Credential Data

No Tour Commands:

The data in the command sectors and jaguar sector will be encrypted with the site key. This is in addition to the encryption provided by MIFARE protocol. The examples provided below are illustrated with the additional encryption with the site key disabled in order to help understand the actual content and structure of the data.

Add Credential:

When an add credential is presented to the device, even the first time when the credential is added to the device’s database, the device will grant access.

The flow diagram in Figure 1 represents how the device will process the No Tour data for an add or update of a credential.

Figure 1: Add Credential Flow Diagram

Figure 2: Add Credential Payload

Structure Definitions:

Add Credential Example:

Table 2: Add Credential Example

Delete Credential:

This command will actually block a user in the database. If a user is just deleted from the database, a card with a pending bit can come by and add itself even if it was deleted previously. Therefore, the user record needs to stay in the database so that when the card comes by and tries to add itself, it won’t allow access.

The flow diagram represents how the device database will process the No Tour data for a delete credential.

Figure 3: Delete Credential Flow Diagram

Figure 4: Delete Credential Payload

Structure Definition:

Delete Credential Example:

In this example the card is blocking itself in the database.

Table 3: Delete Credential Example

Re-purpose credential:

To repurpose a credential, the method uses a combination of add and delete commands. The add command for the new door that is needing access and a delete (block) command of the previous access.

Re-purpose credential example:

Table 4: Re-purpose Credential Example

Replace credential:

In the case that a credential is lost, a replacement credential can be created the deletes (blocks) the lost credential and add the new credential.

Replace credential Example:

Table 5: Replace Credential Example

Unblock Credential for Reuse:

When a credential is deleted via No Tour, the credential information still resides in the door file database with a credential type of blocked. Creating a No Tour Add command to re-enable the credential via No Tour will be rejected by the device. In order to unblock a credential, the device must receive a new door file either via touring with a mobile app, or a WiFi call in for WiFi enabled devices.

For NDE and LE Devices there are two methods to unblock the credential.

• If deleteAll = 1, the credential needs to be part of the “add” array.
• If deleteAll = 0, the credential needs to be part of the “update” array.

For Control, the credential needs to be part of the “add” array, regardless of the Boolean status of deleteAll.

Remove Blocked Credential from Door File

When a credential is deleted via No Tour, the credential information still resides in the door file database with a credential type of blocked. In order to remove an unblocked credential, the device must receive a new door file either via touring with a mobile app, or a WiFi call in for WiFi enabled devices.

• For NDE and LE Devices, a deleteAll = 1 will remove No Tour credential from door file database.
• For Control, a deleteAll = 0 with an “update” array including the “fnctn” tag set to “norm” must be sent to the device which will change the credential function value from “blocked” to “norm”. Then a deleteAll = 1 will remove the No Tour Credential from door file database.

Using Group ID:

When using a group ID instead of a lock ID, the status byte needs to be 0x03. The No Tour device will not write back the pending status bit 0 to 0 when group IDs are used because the same group ID can be assigned to multiple doors in a Site.

Group ID Example

Table 6: Group ID Example

Data Encryption

No Tour End-to-End Encryption

The No Tour data is in the secure sectors of the credential secured by a different key from the credential’s key. All No Tour data is encrypted by the site key.

Figure 5: No Tour End to End Encryption

The steps on how to encrypt the data are found in the Schlage Engage AptiQ MT20W API document.

No Tour Data Encryption Example

The example created is of a No Tour add credential before encryption and after encrypted with the Site Key.

The un-encrypted data for sectors 2 and 3 is as follows:

Table 7: Un-encrypted Data for Sectors 2 and 3

The sectors need to be encrypted individually. For the example 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 was set to do CBC with an initialization vector (IV) of 0 per Schlage Engage AptiQ MT20W API documentation.

The encrypted data for sectors 2 and 3 is as follows:

Table 8: Encrypted Data for Sectors 2 and 3

MT20W

The reader/writer used to write No Tour data onto smart cards is the MT20W.

The steps on how to integrate the MT20W can be found in the Schlage Engage AptiQ MT20W API-X.XX document.

Credential ID Inputs

All references to credential ID for the No Tour module need to be ‘left aligned, no sentinel’ structure in order to operate properly. Credential information is usually in right shift with sentinel. This section covers how to convert to the left aligned, no sentinel structure required, for No Tour to work.

The credential information for 26A format is as follows:

• FFFF FFFF BBBB BBBB BBBB BBBB

• Where:

  • F = Facility Code

  • B = Badge ID

There is an even parity bit before the data structure (for the first 12 bits) and an odd parity bit after the structure (for the last 12 bits). 24 + 2 parity = 26 bits.

There is also a ‘sentinel’ bit that starts the data. The data that gets stored in sector 1, block 1 of the card is right aligned, with sentinel byte.

For example, Facility Code = 0x12, Badge ID = 0xABCD

• 0000 0100 0010 0101 0101 0111 1001 1011 = 0x0425579B

• Sentinel

• Even Parity

• Facility Code

• Badge ID

• Odd Parity

However, the data that would get loaded into the database is left aligned, without the sentinel bit.

• 0000 1001 0101 0101 1110 0110 1100 0000 = 0x0955E6C0

• Even Parity

• Facility Code

• Badge ID

• Odd Parity

• No Sentinel

As another example, Facility Code = A5, Badge ID = 0x0001.

Right Aligned w/ Sentinel:

0x054A0002 0000010 1010 0101 0000 0000 0000 0001 0

Left Aligned w/o Sentinel:

0x52800080 0 1010 0101 0000 0000 0000 0001 0000000

No tour databases (when touring)

It is recommended to always provide a “full” database every time when updating No Tour devices. This keeps the database from getting out of sync and ensures the door has the correct access.

Appendix A: Credential Attribute

Table 9 defines the values for credential attribute. ADA attributes are not supported on Schlage Control locks.

NOTE: Table 9 varies from the credential tag table and credential tag name definitions that are part of the Schlage ENGAGE – JSON Data Structures document. The structure of JSON allows the ADA designation as a different JSON tag in addition to the credential type, whereas this designation is applied with a different attribute tag for No Tour.

Table 9: Credential Attribute Values

Appendix B: Device Schedules

This section defines the device schedule bitmask and how it connects to the JSON device schedules created in the user database.

No Tour can support up to 16 credential schedules simply by or-ing bits with each bit correlating to the “crSch” that is assigned to each credential in the User Record section of “Engage JSON Data Structures” document. Each “crSch” is on a per user basis and should correspond to the JSON tag array “schedules” which is on a per edge device basis.

At a minimum, the No Tour device has one credential schedule which is schedule 1 and correlates to the first bit of the bit mask. The No Tour data written to the card for schedule 1 would be 0x0001.

Figure 6 shows a mapping of the No Tour schedule bitmask to the JSON value provided with the “crSch” tag.

Figure 6: Mapping Bitmask to Credential Schedule

NOTE: Credential Schedules cannot be programmed into the device via No Tour. In order for a credential to have access to a device, at least one credential schedule must be programmed into the device. Creating a new credential schedule via No Tour without updating the device before will result in an out of time zone denied access.

Appendix C: Additional Information

• When a smart card is presented to an Engage device with No Tour enabled, the reader will read the directory sector (Sector 2) and send this information to the main lock controller along with card data (PACS). Based on the information from the pending command bit in the directory sector, the device may request the reader to read data from other sectors.

• No Tour card data is added to an area of the database of the device that is unsorted. The device will send an audit if this unsorted area begins to get full. Performing a card search of the database may take longer, as the unsorted area is not optimized for searching but should not take longer than one second.

• A smart card with No Tour commands will need approximately 1 second to process the card after the beep is heard.

• The battery life may be minimally affected by No Tour cards as the device needs to read more data from the smart card.

• Group IDs are used to assign multiple devices to a group. Removing the device from the group ID will not remove credentials that were added via the group ID. To remove the group ID from a device, the MAPP will need to send a JSON config with the group ID set to an empty array.

• As described above, all SAM mobile apps should provide a door file with deleteAll set to 1 to complete the lock configuration process even though this might not be required with all versions of Schlage Control.