Documentation

Edge Device Security - Password Manager Rollout – Phase 2.1

Suggest Edits

❗️

INTERNAL ONLY

This is a test/staging page for Phase 2.1 of the Device Password Manager Rollout - Do Not Distribute outside of CalAmp.

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 edgedevice 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.

ModelPart Number*Description
LMU-3040LMU3040LAB-KZC0-xxxxxLMU-3040, LTE CAT 1, ATT, (3G FALLBACK), 180 MAH BATT, BT, BUZZER, PLUG-IN OBDII
LMU-3040LMU3040LVB-KZC0-xxxxxLMU-3040, LTE CAT 1, VZW, 180MAH BATT, BT, BUZZER, PLUG-IN OBDII
LMU-3240LMU3240LAW-KZC0-xxxxxLMU-3240, LTE CAT 4, ATT (3G FALLBACK), WI-FI AP, 180MAH BATT, BT, BUZZER, PLUG-IN OBDII
LMU-5541LMU5541LW-H000-xxxxxLMU-5541, LTE CAT 4 (GLOBAL), 3G/2G FALLBACK, EXT ANT, WIFI HOTSPOT, 1000 MAH BATT
  • 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.

FeatureLMU32Router-LinuxEdgeCore
Product line examplesLMU364XLMU5541LMU3X40
Password Storage: P2177,0 & S171b4up to v8.5bv4.1e & earlierv3.2.0,1 & later
AT#PW, Secure storagev8.5c & laterv4.1f & laterTBD
SMS: !R0PYYY
SMS: !#,<command ...>Yv4.1f & laterTBD
Alternate Passwords via Keyfilev8.5c & laterv4.1f & laterTBD
Null Password supportv8.5c & laterv4.1f & laterTBD
Inhibit entry of some special charactersv8.6a & laterNTBD

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.

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

❗️

INTERNAL ONLY

This is a test/staging page for Phase 2.1 of the PWD Manager Rollout - Do Not Distribute outside of CalAmp. The Test Account feature has been implemented in the PULS and CTC Production environment.

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.

Please use the below CTC Production test account credentials:
https://connect.calamp.com/

  • Username: pwdmgrtester
  • Password: !Qwerty123
  • App-Key: 820b5258-1f73-4d7b-bd72-c75c4e5072d1

Please use the below PULS Production test account credentials:
https://puls.calamp.com/

  • Username: pwdmgrtester
  • Password: Pass123!

PULS GUI

Use the PULS credentials to create a Basic Authentication token, add PULS x-app-key and make the request using the CTC API (GET or POST methods, no Login/Logout needed).

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

Enter single ESN:

1907

Single ESN – Password:

1918

Enter Multiple ESNs:

1918

📘

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:

1920

Enter ESN

1920

Single ESN Response

920

Multiple ESN Response

1076

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

1920

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://qa.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://qa.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://qa.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://qa.connect.calamp.com/api/logout" \
--header "Authorization: $AUTH" \
--header "x-app-key: $APKY"

Updated over 3 years ago