Introduction
This page describes asset lists, user assets lists, and digests that an OKM and an OKM Service instance use to keep the information synchronized.
Overview
One way to enforce access to devices is to use a OneKEY Manager (OKM). An OKM is like a representative of the system. It controls who has access to what. To be able to operate devices, a person needs to get its configured access list from the OKM of the store. This happens when checking out a key.
Each store has a set of devices (often called “asset list” in documentation and code). Each person who has access to that store has access to all or a subset of those devices (often called “user assets” in documentation and code).
Access List, User Assets List, and Digests
The OKM Service and OKMs need to keep two lists synchronized:
- an asset list;
- a users assets list, a list containing the access list of each user that has access to the devices in the asset list.
To make it quicker to spot if their lists are different for the same store, the OKM Service and OKMs each calculate a digest of the list of assets and of the lists of access lists they own. They can then compare their digests to make sure they are synchornized.
There are two digests:
- asset list digest: digest of a SHA256 hash of all the assets of a store;
- user assets list digest: digest of a SHA256 hash of all the user access lists of the users of a store;
When an event occurs which modifies one or more ACLs, the OKM Service calculates the digest of the ACLs and stores it with the ACL.
A digest is never sent to an OKM, only the asset lists (asset list and users assets list).
Note: An Access Control List (ACL) defines which users have permission to access specific assets in the asset list. It maps users to the devices they are allowed to use.
Assets Digest
The assets digest, also called the asset list digest, is the digest (i.e. hash function output) obtained from hashing the set of devices to control, ordered by ascending order of serial numbers.
When the OKM Service receives a new ACL or an update request for an ACL, it will calculate the hash of the list of assets and the hash of the access lists.
Then, when the OKM Service receives a /config request from the OKM, it will compare the known hash of the list of assets for the ACL of that OKM, with the assetList query parameter of the request sent by the OKM.
If there is a difference, the OKM Service will send the new asset list to that OKM.
The pseudo code looks like this:
- Get the ACL of the OKM from the database.
- Compare the digest obtained from hashing the set devices, with the digest received in the
assetListquery parameter.
User Assets Digest
The user assets digest is the digest obtained from hashing the set of access lists of all the users in an ACL.
User assets are the Access Control Lists (ACLs) which the OKM and Key use to determine which person can checkout a key and subsequently which devices this person has access to.
If a person has an access list in the OKM, they will be able to check out a key. The checkout operation transfers the access list to the key. The contents of that access list determines if the person can operate a device (for ex: unlock a lock).
When the OKM Service receives a /config request from an OKM, it compare the digest of the lists of assets each user has access to for each user for that OKM, then compares it with the usersAssets query parameter received from the OKM.
If there’s a difference, then the OKM Service will send to the OKM a new set of access lists for all the users.
The pseudo code looks like this:
- Get the ACL of the OKM.
- Compare the digest obtained from hashing that array, with the digest received in the
usersAssetsquery parameter .
Components of Asset Lists
Asset List
List of devices/locks in a store, in ascending order of serial number.
⚠ The asset list must be sorted in ascending order of serial numbers.
It is sent to the OKM as a msgTkn_putAssetList_e command.
User Asset List/ User Access List
List of users who have access to the devices, sorted by invue id, where each user has a list of permission flags for the devices it has access to in that store, in ascending order of serial number.
⚠ The list of users must be sorted in ascending order of InVue ID (“iid”) for the digest calculation to match between the OKM and the OKM Service.
⚠ The length of the permission list and the order of the items in the list must match the order of the assets in the asset list sent to the OKM.
It is sent to the OKM as a msgTkn_putUser_e command.
Example 1 - Store Asset List and User Asset List for One User
Context
For a store that has 10 locks:
'0000058058000023', '000009147609a57c', '0000092a487487dd', '00000975d8061928', '000009a32ce6d655', '000009cfe8c16e6d', '000009f4e480ccdb', '00000f0500065a1d', '00000f0500065acb', '00000f0500065b97'
where user x has access to 4 locks:
'00000f0500065b97', '000009147609a57c', '0000092a487487dd’, '0000058058000023'
Store Asset List
The store asset list to send to the OKM will be:
| 0000058058000023 |
| 000009147609a57c |
| 0000092a487487dd |
| 00000975d8061928 |
| 000009a32ce6d655 |
| 000009cfe8c16e6d |
| 000009f4e480ccdb |
| 00000f0500065a1d |
| 00000f0500065acb |
| 00000f0500065b97 |
User Assets List
The user access list to send to the OKM will be:
| 1 |
| 1 |
| 1 |
| 0 |
| 0 |
| 0 |
| 0 |
| 0 |
| 0 |
| 1 |
Side-by-side:
| Serial Number | Status |
|---|---|
| 0000058058000023 | 1 |
| 000009147609a57c | 1 |
| 0000092a487487dd | 1 |
| 00000975d8061928 | 0 |
| 000009a32ce6d655 | 0 |
| 000009cfe8c16e6d | 0 |
| 000009f4e480ccdb | 0 |
| 00000f0500065a1d | 0 |
| 00000f0500065acb | 0 |
| 00000f0500065b97 | 1 |
All locks are sent, not just the locks the user has access to.
Example 2 - Store Asset List and User Asset List for n Users
Context
For a store that has 10 locks:
'0000058058000023', '000009147609a57c', '0000092a487487dd', '00000975d8061928', '000009a32ce6d655', '000009cfe8c16e6d', '000009f4e480ccdb', '00000f0500065a1d', '00000f0500065acb', '00000f0500065b97';
where user X has access to 4 locks:
'00000f0500065b97', '000009147609a57c', '0000092a487487dd’, '0000058058000023'.
Store Asset List
The store asset list to send to the OKM will be:
| 0000058058000023 |
| 000009147609a57c |
| 0000092a487487dd |
| 00000975d8061928 |
| 000009a32ce6d655 |
| 000009cfe8c16e6d |
| 000009f4e480ccdb |
| 00000f0500065a1d |
| 00000f0500065acb |
| 00000f0500065b97 |
User Assets List
The user access list to send to the OKM for user X will be:
| 1 |
| 1 |
| 1 |
| 0 |
| 0 |
| 0 |
| 0 |
| 0 |
| 0 |
| 1 |
For user Y who has access to these 6 locks in the same store as user X:
‘00000f0500065b97', ‘000009147609a57c', '0000092a487487dd’, '0000058058000023', '000009f4e480ccdb’, '000009a32ce6d655’
The user access list to send to the OKM for user Y will be:
| 1 |
| 1 |
| 1 |
| 0 |
| 1 |
| 0 |
| 1 |
| 0 |
| 0 |
| 1 |
All locks are sent for each user.
The user access list for user X and for user Y will be concatenated, then hashed, to generate the digest value.
The user access list for user X and for user Y will be concatenated, and sent to the OKM if the digests are different between LIVE Access and the OKM.