5.15.1 api mobilekey config

The api/mobilekey/config function is used for reading and writing of location IDs and encryption keys for Bluetooth Authentication.

Service and Privileges Groups

Service group is API Access Control.
Privileges group is Access Control.

Methods

GET – read location IDs and encryption keys
PUT – write location IDs or encryption keys

GET Request

There are no parameters used for GET request.

The response to a GET request is in the application/json format. The result object contains keys location and keys.

Table 1. Response to GET Request JSON Keys

Key	Typical Returned Values	Description
location	String	Location ID of a 2N device. The details are described in the Request section.
keys	Array of objects containing encryption keys	The array length is always 4 (empty objects are returned for the missing keys). The details and structure of objects in the array are described in the Request section.

{
   "success":true,
   "result":{
      "location":"54-1046-0745",
      "keys":[
         {
            "type":"rsa",
            "key":"MIICXAIBAAKBgQhBqr5YI= (...)",
            "ctime":1608047754
         },
         {
            "type":"rsa",
            "key":"MIICXQIBAAKBgQCfyMHsTjP (...)",
            "ctime":1608046389
         },
         {
            "type":"rsa",
            "key":"MIICXQIBAAKBUNQNqodNo (...)"
         },
         {
            
         }
      ]
   }
}

PUT Request

The PUT request contains parameters in the application/json format.

Table 2. PUT Request JSON Keys

Key Name	Mandatory	Expected Values	Default Value	Description
location	No	String of maximum length of 127 characters	–	location defines the specific device location for the purpose of Bluetooth authentication. Any string that defines the location uniquely is accepted. The location is broadcast by the 2N devices and serves for selecting relevant authentication parameters by the Bluetooth authentication device.
key	No		–	*key* helps upload data for the primary encryption key. The array contains encryption keys that are used for secure communication between a 2N device and a device used for authentication via Bluetooth. The objects in the array have the following keys: type – algorithm type "ecc" ("rsa" only if the Compatible mode is active) key – encryption key data (DER format encoded in Base64), use 1024 bit encryption keys, this key is mandatory, ctime – creation time represented as Unix time 32 bit unsigned integer, this key is optional.
keys	No	Array of objects containing encryption keys	–	keys contains encryption keys that are used for secure communication between a 2N device and a device used for authentication via Bluetooth. The objects in the array have the following keys: type – algorithm type, RSA is currently supported, this key is optional, key – encryption key data (DER format encoded in Base64), use 1024 bit encryption keys, this key is mandatory, ctime – creation time represented as Unix time 32 bit unsigned integer, this key is optional.

The 2N devices allow up to four encryption keys to be used at one time. The first encryption key in the array is considered to be the primary encryption key and the other encryption keys are secondary. If a Bluetooth device authenticates itself with any secondary encryption key the 2N device will prompt the Bluetooth device to replace its encryption key with the primary encryption key. Because of this the newest encryption key should always be added to the beginning of the array.

If an array keys of a length shorter than 4 is submitted, the missing encryption keys are deleted (replaced with an empty object).

The key location is by default the serial number of a 2N device. Change it accordingly to add several devices to one location.

The key type is not mandatory. If the algorithm is omitted, the 2N device automatically assumes that RSA (rsa) is used. If the Compatibility mode is inactive, then type of the first item in keys must be ECC, the other keys can be ECC or RSA.

The key ctime is not mandatory. If the creation time is omitted or invalid, the 2N device will display Jan 1st 1970 00:00:00 in the configuration web and will not return ctime for this encryption key.

Response

Example of PUT Request – upload of 2 encryption keys

URL: https://192.168.1.1/api/mobilekey/config 
{
   "location":"LocationUniqueID",
   "keys":[
      {
         "type":"rsa", 				// compatibility mode is active (rsa supported)
         "key":"MIICXAIBAqr5YI (...)",
         "ctime":1608047606
      },
      {
         "type":"rsa",
         "key":"MIICXQInJSGse (...)",
         "ctime":1608044538
      }
   ]
}

Example of PUT Request – upload of primary encryption key

URL: https://192.168.1.1/api/mobilekey/config  
{
  "location": "00-0001-0014",
  "key": {
    "key": "MIIQInJSdfsed...",
    "type": "ecc",
    "ctime": 1733159857
  }
}

The response to a PUT request does not contain any details. E.g., if there is an invalid encryption key value, the key will not be written without any notification.