Manually configuring device credentials
Cirrent provides a script to configure the WCM on each device. Before you start, make sure the WCM is properly installed on the device. You'll need to have a few pieces of information available before you start:
- Account ID. This is your Cirrent account ID, an integer like 1312, which you can find here. It lets Cirrent associate the device with a company account.
- Device ID. This is the unique ID for the device.
- Device secret. This is the secret that you allocated to the device, or Cirrent issued for the device. If you don't have a secret yet, make sure to register the device in the Management Center. Make sure to double check capital I and l and 0 and O to get the secret right. You can find more information about the Device ID and secret here.
- Demo device. A demo device resets itself and clears any private networks each time it reboots. For testing purposes this is useful, because you can rediscover a device each time it boots up. Decide whether you want the device to be a demo device.
Now you can configure the device by running the personalization script:
# sudo /etc/wcm/personalize.sh
Now enter the information as the script asks you to.
The script will generate a credential file for the WCM to use. The script will also validate the entered device credentials by attempting a call to the Cirrent cloud. If you have an internet connection on the device, this should return a success. If you do not have an internet connection, the script will get an error. You can either setup an internet connection manually on the device and run the script again, or you can move on. Your device credentials will be validated later when running the WCM in range of a ZipKey network. You can find information on setting up a test ZipKey network here. (Note: this script is only run when you are manually installing the WCM on your Linux device. For production devices, the device credentials will be pre-provisioned during manufacturing.)
Configuring credentials for production devices
Every ZipKey-enabled device needs its own set of credentials. On Linux devices, the WCM reads the credentials from a specially formatted credentials file, or uses a library you provide to read the credentials. For production devices, each device should be pre-provisioned with a unique credentials file as part of the manufacturing process. The credentials must also be uploaded to the Cirrent cloud. You can find more information about Device IDs here.
The best approach to providing the credentials to the WCM is to implement a small library, libwcmcredentials.so, that the WCM will call to get the device credentials. This gives you complete control over how and where you store the credentials (e.g. you can store them in encrypted form and decrypt them when the WCM needs them). The API for libwcmcredentials.so is defined in wcm_credentials.h, and an example implementation (that reads the credentials from a credential file) is in wcm_credentials.c.
If you do not wish to provide a library that the WCM can call to retrieve the credentials, you can generate the credential file in the format that the WCM supports, and the WCM will read the credentials directly from the credentials file. The credentials file includes the Device ID, Device secret, and Account ID. You should save the credentials to a text file with the following formatting:
Configuration Version: 0.0.1
A sample credentials file for a device with Device ID ZipKeyProduct123, Device Secret MyDeviceSecret, and belonging to Account ID 1312 looks like this:
Configuration Version: 0.0.1
You can download a sample credentials file here.
Once you have saved the file as "credentials.key", you should place the file into the configured directory for the WCM to use.
Saving the credentials file to the device
You will have to save the credentials file to a directory called "keys" located in the same directory where you installed the WCM files. For example, the WCM installer package for the Raspberry Pi described here installs the WCM to the directory "/etc/wcm" (the location of the "wcm" directory is specified in the WCM configuration file described here). For a Raspberry Pi, the keys are stored in a directory "keys" with a full path of "/etc/wcm/keys" (this path will change depending on where you have installed the WCM). After you copy over the credentials.key file, make sure it has the appropriate permissions. The file must be available for reading by a user running as root.