Edge Device Security - Password Manager Rollout – Phase 2.1

To enhance security measures, adhere to global compliance regulations, and protect data and device security, CalAmp is rolling out Phase 2.1 of the Device Password Manager Service. In this phase, unique random passwords for affected devices will be set at time of manufacture. Customers will be able to access these passwords through the Device Password Manager (PWD Manager).

This page describes the release of the edge device password manager interface API. This API allows customers to download unique strong passwords that will be enabled by default on devices. The APIs are considered preliminary, and it has not been released on production servers. Changes to the APIs may occur prior to release.

The device password interface is a GET endpoint to retrieve the password for a device specified by its ESN (Electronic Serial Number), IMEI or MAC. The API can be authenticated using CTC or PULS credentials, but the authentication method varies between the two.

The first bulletin, detailing CalAmp’s Phase 2 plan, can be found here

Throughout Phase 2, CalAmp will subsequently introduce Device Password Manager support for additional product lines, as they are validated in iterative bulletins (Phase 2.2, 2.3, 2.4 etc)

📘

As part of release 2.1, CalAmp will be rolling out PWD manager on LMU-3040, LMU-3240, LMU-5541

Click Here to View the Full Bulletin

Affected Products

The table below details the product and part number specificities of the Device Password Manager Phase 2.1 deployment.

• includes all customer-specific SKU / configurations and derivatives

AT Command Authentication

The command AT$PW "" is used to authenticate the user accessing the AT Command interface. The use of the double quotes is Q strongly recommended on all password-related commands to isolate embedded spaces and because the AT Command processor converts all character outside of quotes to uppercase before parsing.)

SMS Authentication

The password can be provided two ways:

1. As a suffix to the !R0 command: !R0P. Whether the password is correct or not, the normal !R0 response will be returned.

2. On platforms that support it, as a prefix to a command: !#,<command ...>. If the command normally returns a response, the command will only execute and return a response if the password is correct.

Once a correct password has been provided, the sender remains authenticated for commands from the same phone number until the device reboots (wakeup, power-on, app restart, OTA FW update, etc.) or another phone number is used to access the device.
If the sender is not authenticated, commands are quietly ignored (no response).

AT Command and SMS Password Compatibility

Refer to the table below for the feature-set and firmware compatibility by embedded platform for the affected product lines of Phase 2.1.

Root Password (Restricted access)

On the Linux platform, the root password cannot be retrieved by the PULS and/or CTC customer via API or GUI. Access is restricted to internal CalAmp entities.

If a customer has a need for a device’s root password, a request should be made to the CalAmp support team via a CTCS - JIRA support request ticket.

Alternate Passwords

The random per-device AT Command & SMS password described above is called the Primary password. Devices can be given a fleet-wide Alternate password via the L1-Security Key File feature. A Key File can be used to specify separate passwords for AT Commands and SMS. Customers who want to have a key file generated should make a CTCS - JIRA support request and append the Key File form filled out per their requirement. The Key File form can be downloaded from the dev portal

📘

Key File Form

The Key File form can be accessed here.

📘

L1 Security

please click here to view additional details on L1 security

Password Retrieval

When passwords are generated by during the manufacturing process, the Device Password Manager database stores the passwords by ESN, IMEI and Ethernet MAC address on applicable devices. Any of these keys can be used to lookup the password or passwords assigned to a device.

Customer - Test Account

To support customers transitioning their processes and code to work with Device Password Manager, CalAmp provides a test account – login, password & x-app-key that can be used by all developers.

The test account is populated with 501 (fictitious) ESNs 1110110001 through 1110110501 that each return a full set of passwords.

❗️

Test Account Access

Please write an email to CalAmp Customer Support at [email protected] to get credentials and app-key to access this test account for test and integration needs.

PULS GUI

Passwords for up to 500 ESNs can be looked up at Mfg > Advanced > DEVICE PWD.

Enter single ESN:

Single ESN – Password:

Enter Multiple ESNs:

📘

Note on the screens above there is a “save as excel” , “save as CSV” buttons to extract the content displayed on the screen into an excel or CSV files respectively

CTC GUI

Test account is created under the connect telematics and account details are:
Under ACTIONS tab, select Device Password:

Enter ESN

Single ESN Response

Multiple ESN Response

In case of invalid ESN, user would see an error prompt on the screen:

There is also a provision to upload to excel the multiple ESNs and extract the passwords in bulk.

APIs

Both PULS and CTC users can retrieve the passwords by passing their respective PULS or CTC credentials respectively for the APIs below.

There is an API to login, retrieve passwords & logout. The API will reject requests arriving at more than 1 per 100ms.

Login

The Login request returns a Bearer token (snipped in the following example) that must be isolated and provided on subsequent requests.

AUTH="Bearer eyJhbGciOiJIUzI1 <snip> KE_0EhfYvpNttBpI"
Request
curl --location --request POST "https://connect.calamp.com/api/login" \
--header "Content-Type: application/json" \
--header "x-app-key: $APKY" \
--data-raw "{ \"username\": \"$USER\", \"password\": \"$PSWD\" }"
Response
{
  "response" : {
  "errors" : [ ]
  "results" : [
    {
    "authToken" : "Bearer eyJhbGciOiJIUzI1 <snip> KE_0EhfYvpNttBpI"
<snip>

Retrieve (GET Method)

Request
KEY can be one of "esn", "imei", or "mac".
VAL is a list of 1 up to 500 keys, comma separated. An error is returned if none of the keys are available or more than 500 keys are requested. If some keys are available, only those are returned.

The KEY type and list of keys are specified in the URL.

KEY="esn"
VAL="1110110001,1110110002"
curl --location --request GET "https://connect.calamp.com/api/devices/passwords/$KEY?values=$VAL" \
--header "Content-Type: application/json" \
--header "x-app-key: $APKY" \
--header "Authorization: $AUTH"

Response

{
  "response" : {
    "results" : [
      {
        "devicePassword" : {
          "esn" : "1110110001"
          "imei" : null
          "mac" : null
          "user" : "Ehqmug44*"
          "atCmdSms" : "Nyfuwk83{"
          "guiEngr" : "Sgnlen50^"
          "gui1" : "Qjastg25^"
          "wifi0" : "Esn-1110110001"
          "createdOn" : "2021-05-13T19:19:16.414+00:00"
          "modifiedOn" : "2021-05-13T19:19:16.414+00:00"
          "ukey" : "Rnwkup89="
        }
      }
      {
        "devicePassword" : {
          "esn" : "1110110002"
          "imei" : null
          "mac" : null
          "user" : "Whikmx05{"
          "atCmdSms" : "Iqvzhv38?"
          "guiEngr" : "Ncmwng57="
          "gui1" : "Upojjt01%"
          "wifi0" : "Esn-1110110002"
          "createdOn" : "2021-05-13T19:44:39.129+00:00"
          "modifiedOn" : "2021-05-13T19:44:39.129+00:00"
          "ukey" : "Vmmdsf33>"
        }
      }
    ]
  "errors" : [ ]
  }
}

Retrieve (POST Method)

Request
KEY can be one of "esn", "imei", or "mac".
VAL is a list of 1 up to 500 keys, comma separated. An error is returned if none of the keys are available or more than 500 keys are requested. If some keys are available, only those are returned.

The KEY type and list of keys are specified in the request body.

KEY="esn"
VAL="1110110001,1110110002"
curl --location --request POST "https://connect.calamp.com/api/devices/passwords/all" \
--header "Content-Type: application/json" \
--header "x-app-key: $APKY" \
--header "Authorization: $AUTH" \
--data-raw "{\"$KEY\":\"$VAL\"}"

Response
Same as Retrieve (GET Method). device password entries may be out of order compared to the VAL list.)

Logout

Request

curl --location --request GET "https://connect.calamp.com/api/logout" \
--header "Authorization: $AUTH" \
--header "x-app-key: $APKY"