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, keys and pairingKey.

Table 1. Response to GET Request JSON Keys

Key

Typical Returned Values

Description

location

String

location is the location ID of a 2N device. The details are described in the Request section.

keys

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 array length is always 4 (empty objects are returned for missing keys). The objects in the array have the following keys:

- type – algorithm type can be: ecc, rsa, unknown. This key is optional
- publicKey – Base64 encoded DER encoded public key. This key is mandatory
- ctime – creation time represented as Unix time 32 bit unsigned integer. This key is optional and is present only when the key has a known creation time.

pairingKey

Object containing encryption key or absent

pairingKey is exported if pairing key data are present at the 2NOS device. It is exported at the same format as the other keys in the keys section. This key is optional.

{
   "success":true,
   "result":{
      "location":"54-1046-0745",
      "keys":[
         {
            "type":"rsa",
            "publicKey":"MIICXAIBAAKBgQhBqr5YI= (...)",
            "ctime":1608047754
         },
         {
            "type":"rsa",
            "publicKey":"MIICXQIBAAKBgQCfyMHsTjP (...)",
            "ctime":1608046389
         },
         {
            "type":"rsa",
            "publicKey":"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.