Allegion Developer Portal

ENGAGE_Remote_Network_Security_Access_Point_Configuration

ENGAGE - Remote Network Security Access Point Configuration

REVISION CONTROL RECORD   
VERDATEDESCRIPTION OF CHANGEAUTHOR
0.103/4/2018Initial draftA. Paul
0.203/28/2018Final draftA. Paul
0.304/30/2018Updated for additional invalid audit for switch timeA. Paul
0.405/7/2018ReformattingM. Nichols
1.003/4/2018Final updates prior to the document's releaseM. Nichols
  Section 1.3.1 - corrected wording 
  Section 2 - corrected note to include version later than 6.1 
  Section 2.2 - correct "apCfgNewStrtTm" in Table 1 
  Section 2.3 - Add text "Only alphanumeric standard English language characters are accepted." 
  Section 2.3 - Add text "IP host should check that lockAP new configurations match expected values.” 
  Section 2.4.1 - items 2 and 3 edited 
  Section 2.4.2 - item 3 edited 
1.107/9/2018External Release for 6.1T. Holt

Table of Contents

  1. Introduction 4

1.1 Abbreviations 4

1.2 Purpose 4

1.3 Background 4

  1. Updating a Lock’s Access Point Login Credential 5

2.1 Feature Prerequisite 5

2.2 Feature Overview 5

2.3 Feature Implementation Considerations 6

2.4 ENGAGE Alliance Partner Host Implementation 7

2.4.1 Set New Access Point Configuration 7

2.4.2 Verify New Access Point Configuration was Set 7

2.4.3 Delete a New Access Point Configuration 7

2.4.4 To Confirm New Access Point Configuration Switch 8

  1. Appendix A: Use Case Example 9

3.1 Set a New Access Point Configuration 9

3.2 Verify New Access Point Configuration 12

3.3 Delete New Access Point Configuration 14

3.4 Verify New Access Point Configuration Switch 19

Introduction

Abbreviations

Abbreviations Used In This Document 
APAccess Point
ENGAGEConnectivity Platform Technology
JSONJava Script Object Notation
ConfigDevice Configuration
DBDatabase

Purpose

The purpose of this document is to provide the rationale behind the implementation of the Access Point Login Update feature, provide a base level understanding of how the feature works, why our ENGAGE Alliance Partners may want to use it, and to outline the specifics of the communication protocol.

This would enable our ENGAGE Alliance Partners to update the Access Point login of an ENGAGE device from a host without the need to visit each device installed at the customer site.

Background

Operational Issues

Currently, the only method to update the access point login credential of a networked offline lock, is to visit the door on which the lock/device is installed and change the access point login credential using the ENGAGE mobile app or a mobile application provided by the ENGAGE Alliance Partners.

This method takes about 10 to 15 minutes for a single lock/device. A site containing 1000 locks/devices would require an estimated 20 man-days to complete the single round of updates. In addition, travel and access time is incurred.

Planned, quarterly updates can burden an organization for 80 man-days annually to ensure an accepted security practice, the compulsory upgrade of the login credentials, is maintained for networked ENGAGE devices (NDE/LE/CTE/RURM).

Viable Solution

A method, to manage and refresh login credentials remotely, allows a host to update all the locks/devices simultaneously while eliminating the resource hours normally involved. The elimination of site visits and the elimination of nearly 80 man-days annually, can be realized in immediate savings of time and effort for the organization’s IT team.

Updating a Device’s Access Point (AP) Login Credential

This feature is applicable to all ENGAGE devices which operate in Networked Offline Mode.

Updates to the Alliance Partner host is required as outlined herein.

NOTE: This new feature is supported beginning with the ENGAGE Release 6.1.

Feature Prerequisite

New Access Point (AP) Config JSON is only supported if TLS and HMAC are enabled.

Feature Overview

ENGAGE enabled networked offline locks phone home once in 24 hours (configurable) to push current device configuration, download database, and upload audits.

The host can send the new Access Point configuration for changing the login credential during this time.

Table 1 illustrates the new Access Point configuration JSON.

Table 1: New Access Point Configuration JSON

TagShort TagType/Length (ASCII bytes)ValueDevice Exclusions
New Access Point ConfigapCfgNewString/6N/ASC
New AP Config EnableapCfgNewEnString/1“T” = enables new Access Point Config “F” = disables new Access Point Config (default option)SC
New SSIDssidNewString/32Max 32 charactersSC
New AP PasswordpsswdNewString/64Max 64 charactersSC
New User NameusrNmNewString/16Max 16 charactersSC
New Wi-Fi SecuritywifiSecNewString/7“prsnl”, “entrprs”, “open”,”wep”SC
Config Start TimeapCfgNewStrtTmString /14“YYYYMMDDHHMMSS”SC

A WIFI_NEW_AP_UPDATE audit (Audit Event = 0x0B0E, Audit Data: 0000) is logged by the device, if New Access Point Configuration is successfully accepted. The device will push the updated configuration during the next phone home.

In case the new Access Point Configuration JSON is invalid, WIFI_NEW_AP_UPDATE audit (Audit Event = 0x0B0E, Audit Data: 0003, Audit Event = 0x0B0E, Audit Data: 0004) is logged.

To disable a new AP configuration before it takes effect, the host needs to send a JSON with tag “apCfgNewEn” = “F”. WIFI_NEW_AP_UPDATE audit (Audit Event = 0x0B0E, Audit Data: 0001) is logged by the device.

At time = “apCfgNewStrtTm” set by the host, the device will switch over from current AP Configuration to New AP Configuration. The device will set new AP configuration as current AP Configuration and set tag “apCfgNewEn” = “F” (i.e. clear/disable New Access Point Config). During the switch the device shall log WIFI_NEW_AP_UPDATE audit (Audit Event = 0x0B0E Audit Data: 0002). The device will use the new configuration, the next time it phones home.

Feature Implementation Considerations

  • Any time after the new AP configs are set, if the HMAC and or TLS are turned off, the device clears the new AP configs and logs a WIFI_NEW_AP_UPDATE audit (Audit Event = 0x0B0E Audit Data: 0001).

  • New Access Point Config is invalid, if invalid JSON tag/size/data or out of boundary values for “apCfgNewStrtTm” is sent.

    • Accepted boundary values for “apCfgNewStrtTm”:
    • Minimum value: 1 minute from current time.
    • Maximum value: 6 months from current time.

  • If the switch time (change from current AP settings to new AP settings) is missed due to a device being powered off or reset or power cycle, the device switches to the new AP config on the next power up. This is true only if the device retains time on power up. If the device loses time on power up, device clears the new AP configs and logs a WIFI_NEW_AP_UPDATE audit (Audit Event = 0x0B0E Audit Data: 0001).

  • If using WEP as a WiFi security type, kyIndx (WEP Key Index) is deprecated and always considered to be of value 1.

  • Only alphanumeric Standard English language characters are accepted.

  • IP host should check that lockAP new configurations match expected values.

ENGAGE Alliance Partner Host Implementation

Set New Access Point Configuration

To set a new AP configuration, perform the following steps:

  1. During the next phone home, get the current configuration from the lock.

  2. Confirm if the dvcProfile block, in the Lock Configuration, contains extension key “NewAPCfg” with value = 1 which confirms the feature is supported.

  3. Send the new AP configuration with relevant values as per Table 1 as part of Config during Database download.

  4. While sending the updated database (if any), include an updated value for the “dbDwnLdTm” tag to request the next phone home happens within 10 minutes.

Verify New Access Point Configuration was Set

To verify the new AP configuration, perform the following steps:

  1. After Step 4 in the above section Set New Access Point Configuration, get audits from the lock.

  2. Verify WIFI_NEW_AP_UPDATE audit (Audit Event = 0x0B0E, Audit Data: 0000) was logged. This audit indicates that the new AP configuration was accepted successfully by the lock.

  3. During the next phone home (after 10 minutes), get the configuration from the lock. Verify if the new AP configuration was received along with other lock configuration parameters. Verify values match expected.

Delete a New Access Point Configuration

To delete a new AP configuration that was set previously, perform the following steps:

  1. During the next phone home, get the current configuration from the lock.

  2. Send new AP configuration with tag “apCfgNewEn” = “F” as part of Config during Database download.

  3. While sending the updated database (if any), include an updated value for the “dbDwnLdTm” tag so the next phone home happens within 10 minutes (Optional step).

  4. Get audits from the Lock.

  5. Verify WIFI_NEW_AP_UPDATE audit (Audit Event = 0x0B0E, Audit Data: 0001) was logged. This audit indicates that the new AP configuration was successfully deleted by the lock.

  6. During the next phone home after 10 minutes, get the configuration from the lock. Verify that no new AP configuration was received along with other lock configuration parameters.

NOTE: Deleting a New AP configuration is only applicable before new AP configuration switch time.

Confirm New Access Point Configuration Switch

To confirm the new AP configuration switch, perform the following steps:

  1. During the previous phone home, while sending the updated database (if any), include an updated value for the “dbDwnLdTm” tag which is after “apCfgNewStrtTm” time (i.e. “dbDwnLdTm” > “apCfgNewStrtTm”).

  2. During the “dbDwnLdTm” confirm that the lock is able to connect to the host using the new AP configuration parameters.

  3. Get configuration from the lock.

  4. Verify that no new AP configuration was received along with other lock configuration parameters.

  5. Verify that current AP configuration is same as previously set new AP configuration.

  6. Get audits from the lock.

  7. Verify WIFI_NEW_AP_UPDATE audit (Audit Event = 0x0B0E, Audit Data: 0002) was logged. This audit indicates that the new AP configuration was successfully switched by the lock.

Appendix A: Use Case Example

For API’s used by the ENGAGE Device during phone home refer Software Alliance Member API Integration Application Note.

NOTE: In the following sections, items highlighted in RED are items to be noted.

Set a New Access Point Configuration

STEP 1: Configuration reported from the lock during phone home. Verify "key":"NewAPCfg" and "value":"1".

 {
  "dvcProfile":
    {
            "baseType":"nde",
            "key":"NewAPCfg",
            "value":"1"
    },
    "battV":
    {
            "main":"5.87",
            "li":"2.99"
    },
    "fwVer":
    {
            "main":"01.03.11",
            "credRdr":"01.02.10",
            "ble":"01.02.10",
            "wifi":"01.05.10",
            "mainBl":"00.01.03",
            "credRdrBl":"00.01.01"
    },
    "wifiStngs":
    {
            "ssid":"01.03.11",
            "psswd":"\@113G10N",
            "usrNm":"Br549",
            "wifiSec":"entrprs",
            "encrypt":"wep",
            "kyIndx":4,
            "dscvryTyp":"ipAddr",
            "scrCnn": "http",
            "ip":"196.23.43.113",
            "dns":"firstChoice",
            "altDNS":"secondChoice"
    },
    "lckPrmtrs":
    {
            "nm":"corner office",
            "mdl": "sf",
            "lckSn":"1122334455",
            "mnSn":"2233445566",
            "mfgDt":"20140607113022",
            "daysInUse":145,
            "hwVer":"c1",
            "type":"strm",
            "relock":1,
            "doorProp":20,
            "ada":30,
            "firstManIn":0,
            "dstEnable":0,
            "dstStart": "3022",
            "dstEnd": "B012",
            "battFail": "sec",
            "rtcTime": "20140527140629",
            "dbDwnLdTm":"20140528020000"
    },
    "rdrPrmtrs":
    {
            "bprEn": "T",
            "crSn":"4455667788",
            "mfgDt":"20140607113522",
            "daysInUse":145,
            "hwVer":"c1"
    }
  }

STEP 2: Send new AP configuration with relevant values as part of Config during Database download.

Set next phone home to happen after 10 minutes.

{
"config":{
  "battFail":"sec",
  "proxConfGE4001":"T",
  "rtcTime":"20140424152753",
  "iClsUID40b":"T",
  "bprEn":"T",
  "proxConfHID":"T",
  "uid15693":"T",
  "name":"sw555",
  "mi14443":"T",
  "uid14443":"F",
  "proxConfGECASI":"T",
  "dstStart":"12b0",
  "ada":"30",
  "proxConfAWID":"T",
  "proxConfGE4002":"F",
  "doorProp":"20",
  "relock":"3",
  "noc14443":"T",
  "mdl":"unknown",
  "dstEnd":"2230",
  "firstManIn":"false",
  "dstEnable":"false",
  "fwUrl":""
 },
"apCfgNew":{
    "apCfgNewEn":"T",
    "ssidNew":"02.04.12",
    "psswdNew":" G10N\@113",
    "usrNmNew":"Cr649",
    "wifiSecNew":"entrprs",
    "apCfgNewStrtTm":"20140527160629"
 },
 "dbDwnLdTm": "20140527141629",
 "nxtDbVerTS": "0x8d16386bfaec212"
}

Verify New Access Point Configuration

STEP 1: Get audits after DB download. Verify WIFI_NEW_AP_UPDATE audit logged.

{
 “audits”:
 {
    "event":"B0E0000",
    "time":"20140527140640"
 },
 “nxtDbVerTS”:" 0x8d16386bfaec212"
}

STEP 2: (OPTIONAL) Verify Configuration reported from the lock during next phone home after 10 minutes.

{
 "dvcProfile":
   {
           "baseType":"nde",
           "key":"NewAPCfg",
           "value":"1"
   },
   "battV":
   {
           "main":"5.87",
           "li":"2.99"
   },
   "fwVer":
   {
           "main":"01.03.11",
           "credRdr":"01.02.10",
           "ble":"01.02.10",
           "wifi":"01.05.10",
           "mainBl":"00.01.03",
           "credRdrBl":"00.01.01"
   },
   "wifiStngs":
   {
           "ssid":"01.03.11",
           "psswd":"\@113G10N",
           "usrNm":"Br549",
           "wifiSec":"entrprs",
           "encrypt":"wep",
           "kyIndx":4,
           "dscvryTyp":"ipAddr",
           "scrCnn": "http",
           "ip":"196.23.43.113",
           "dns":"firstChoice",
           "altDNS":"secondChoice"
   },
   "apCfgNew":{
   "apCfgNewEn":"T",
   "ssidNew":"02.04.12",
   "psswdNew":" G10N\@113",
   "usrNmNew":"Cr649",
   "wifiSecNew":"entrprs",
   "apCfgNewStrtTm":"20140527160629"
 },
  "lckPrmtrs":
  {
           "nm":"corner office",
           "mdl": "sf",
           "lckSn":"1122334455",
           "mnSn":"2233445566",
           "mfgDt":"20140607113022",
           "daysInUse":145,
           "hwVer":"c1",
           "type":"strm",
           "relock":1,
           "doorProp":20,
           "ada":30,
           "firstManIn":0,
           "dstEnable":0,
           "dstStart": "3022",
           "dstEnd": "B012",
           "battFail": "sec",
           "rtcTime": "20140527140629",
           "dbDwnLdTm":"20140528020000"
   },
   "rdrPrmtrs":
   {
           "bprEn": "T",
           "crSn":"4455667788",
           "mfgDt":"20140607113522",
           "daysInUse":145,
           "hwVer":"c1"
   }
}

Delete New Access Point Configuration

STEP 1: Verify Configuration reported from the lock during next phone home.

{
 "dvcProfile":
   {
           "baseType":"nde",
           "key":"NewAPCfg",
           "value":"1"
   },
   "battV":
   {
           "main":"5.87",
           "li":"2.99"
   },
   "fwVer":
   {
           "main":"01.03.11",
           "credRdr":"01.02.10",
           "ble":"01.02.10",
           "wifi":"01.05.10",
           "mainBl":"00.01.03",
           "credRdrBl":"00.01.01"
   },
   "wifiStngs":
   {
           "ssid":"01.03.11",
           "psswd":"\@113G10N",
           "usrNm":"Br549",
           "wifiSec":"entrprs",
           "encrypt":"wep",
           "kyIndx":4,
           "dscvryTyp":"ipAddr",
           "scrCnn": "http",
           "ip":"196.23.43.113",
           "dns":"firstChoice",
           "altDNS":"secondChoice"
   },
   "apCfgNew":{
   "apCfgNewEn":"T",
   "ssidNew":"02.04.12",
   "psswdNew":" G10N\@113",
   "usrNmNew":"Cr649",
   "wifiSecNew":"entrprs",
   "apCfgNewStrtTm":"20140527160629"
},
  "lckPrmtrs":
  {
           "nm":"corner office",
           "mdl": "sf",
           "lckSn":"1122334455",
           "mnSn":"2233445566",
           "mfgDt":"20140607113022",
           "daysInUse":145,
           "hwVer":"c1",
           "type":"strm",
           "relock":1,
           "doorProp":20,
           "ada":30,
           "firstManIn":0,
           "dstEnable":0,
           "dstStart": "3022",
           "dstEnd": "B012",
           "battFail": "sec",
           "rtcTime": "20140527140629",
           "dbDwnLdTm":"20140528020000"
   },
   "rdrPrmtrs":
   {
           "bprEn": "T",
           "crSn":"4455667788",
           "mfgDt":"20140607113522",
           "daysInUse":145,
           "hwVer":"c1"
   }
}

STEP 2: Send new AP configuration with tag “apCfgNewEn” = “F” as part of Config during Database download.

(OPTIONAL) Set next phone home to happen after 10 minutes.

{
"config":
  {
   "battFail":"sec",
   "proxConfGE4001":"T",
   "rtcTime":"20140424152753",
   "iClsUID40b":"T",
   "bprEn":"T",
   "proxConfHID":"T",
   "uid15693":"T",
   "name":"sw555",
   "mi14443":"T",
   "uid14443":"F",
   "proxConfGECASI":"T",
   "dstStart":"12b0",
   "ada":"30",
   "proxConfAWID":"T",
   "proxConfGE4002":"F",
   "doorProp":"20",
   "relock":"3",
   "noc14443":"T",
   "mdl":"unknown",
   "dstEnd":"2230",
   "firstManIn":"false",
   "dstEnable":"false",
   "fwUrl":""
  },
 "apCfgNew":{
     "apCfgNewEn":"F"
  },
  "dbDwnLdTm": "20140527142629",
  "nxtDbVerTS": "0x8d16386bfaec212"
 }

STEP 3: Get audits after DB download. Verify WIFI_NEW_AP_UPDATE audit logged.

 {
  “audits”:
   {
     "event":"B0E0001",
     "time":"20140527140640"
   },
   “nxtDbVerTS”:" 0x8d16386bfaec212"
  }

STEP 4: Verify Configuration reported from the lock during next phone home after 10 minutes. No New AP Configuration should be reported.

{
 "dvcProfile":
   {
           "baseType":"nde",
           "key":"NewAPCfg",
           "value":"1"
   },
   "battV":
   {
           "main":"5.87",
           "li":"2.99"
   },
   "fwVer":
   {
           "main":"01.03.11",
           "credRdr":"01.02.10",
           "ble":"01.02.10",
           "wifi":"01.05.10",
           "mainBl":"00.01.03",
           "credRdrBl":"00.01.01"
   },
   "wifiStngs":
   {
           "ssid":"01.03.11",
           "psswd":"\@113G10N",
           "usrNm":"Br549",
           "wifiSec":"entrprs",
           "encrypt":"wep",
           "kyIndx":4,
           "dscvryTyp":"ipAddr",
           "scrCnn": "http",
           "ip":"196.23.43.113",
           "dns":"firstChoice",
           "altDNS":"secondChoice"
   },
   "lckPrmtrs":
   {
           "nm":"corner office",
           "mdl": "sf",
           "lckSn":"1122334455",
           "mnSn":"2233445566",
           "mfgDt":"20140607113022",
           "daysInUse":145,
           "hwVer":"c1",
           "type":"strm",
           "relock":1,
           "doorProp":20,
           "ada":30,
           "firstManIn":0,
           "dstEnable":0,
           "dstStart": "3022",
           "dstEnd": "B012",
           "battFail": "sec",
           "rtcTime": "20140527140629",
           "dbDwnLdTm":"20140528020000"
   },
   "rdrPrmtrs":
   {
           "bprEn": "T",
           "crSn":"4455667788",
           "mfgDt":"20140607113522",
           "daysInUse":145,
           "hwVer":"c1"
   }
}

Verify New Access Point Configuration Switch

STEP 1: During phone home set next phone home to happen after configuration switch time.

{
 "dbDwnLdTm": "20140527171629",
 "nxtDbVerTS": "0x8d16386bfaec212"
}

**STEP 2: Verify Configuration reported from the lock during next phone home after configuration switch time. No New AP Configuration should be reported. Verify current AP configuration is the same as the New AP configuration set previously.

{
 "dvcProfile":
   {
           "baseType":"nde",
           "key":"NewAPCfg",
           "value":"1"
   },
   "battV":
   {
           "main":"5.87",
           "li":"2.99"
   },
   "fwVer":
   {
           "main":"01.03.11",
           "credRdr":"01.02.10",
           "ble":"01.02.10",
           "wifi":"01.05.10",
           "mainBl":"00.01.03",
           "credRdrBl":"00.01.01"
   },
   "wifiStngs":
   {
           "ssid":"02.04.12",
           "psswd":" G10N\@113",
           "usrNm":"Cr649",
           "wifiSec":"entrprs",
           "encrypt":"wep",
           "kyIndx":4,
           "dscvryTyp":"ipAddr",
           "scrCnn": "http",
           "ip":"196.23.43.113",
           "dns":"firstChoice",
           "altDNS":"secondChoice"
   },
   "lckPrmtrs":
   {
           "nm":"corner office",
           "mdl": "sf",
           "lckSn":"1122334455",
           "mnSn":"2233445566",
           "mfgDt":"20140607113022",
           "daysInUse":145,
           "hwVer":"c1",
           "type":"strm",
           "relock":1,
           "doorProp":20,
           "ada":30,
           "firstManIn":0,
           "dstEnable":0,
           "dstStart": "3022",
           "dstEnd": "B012",
           "battFail": "sec",
           "rtcTime": "20140527140629",
           "dbDwnLdTm":"20140528020000"
   },
   "rdrPrmtrs":
   {
           "bprEn": "T",
           "crSn":"4455667788",
           "mfgDt":"20140607113522",
           "daysInUse":145,
           "hwVer":"c1"
   }
}

STEP 3: Get audits after DB download. Verify WIFI_NEW_AP_UPDATE audit logged.

{
 “audits”:
  {
    "event":"B0E0002",
    "time":"20140527171630"
  },
 “nxtDbVerTS”:" 0x8d16386bfaec212"
}