Initialization of Locks

System Requirements

BlueID SDK for C initializer distribution
Java Runtime Environment 8
Internet connection

Overview

The BlueID SDK for C initializer distribution contains the following tools for initializing one or several secured objects:

Keyword	File	Description
Initializer Library	sdkforc-initializer-lib.jar	For writing your own initializer
	sdkforc-initializer-lib-javadoc.jar	API documentation
Tool for initializing secured objects	sdkforc-initializer.jar	For initializing secured objects
Further information	README.txt	Link to documentation
	version.txt	Additional version information
	BlueID Open Source License Agreement Supplement.pdf	Information on open source licenses which apply

Internet Access Configuration

The tools require an internet connection, please configure your firewall to allow the following connection type:

Name	Value
Protocol	HTTPS
Port	443
Allowed hosts	Your respective Device API URL

You can find all of our Device API URLs here: BlueID Environments

Initializing

Each secured object requires a unique device identification within the BlueID system. This device identification can be created using the standard initializer that comes along with the BlueID SDK for C initializer distribution. The initializer generates a new set of cryptographic keys for each secured object and sends it to the BlueID Trust Center in order to add it to its database. In response, the initializer receives the unique secured object ID for a new secured object. After the initializer received the unique secured object ID the initializer generates the desired output file(s). The usage of the output files is described below.

Using the initialization tool

To print usage information execute the following command on the command line:

java -jar sdkforc-initializer.jar [-h]

Synopsis:

java -jar sdkforc-initializer.jar --api-key KEY --environment ENV [--endianness ENDIAN] [--out-type [TYPE]+] <CHANNELS>

KEY

One of the provided API-Keys

ENV

The main BlueID Trust Centers can be set using INT or PROD

If you need to initialize for your own Trust Center, use --trust-center HOSTNAME instead of --environment ENV

ENDIANESS

LITTLE, BIG

TYPE

There are two possible output types that can be used to run a secured object:

BCF: A binary configuration image that can be flashed into the SO's non-volatile memory.
JSON: A JSON file (text-based file format) that can be used for further processing of the information produced by the initializer.

Furthermore you can define an additional output type, which doesn't contain sensitive information like private keys and client secrets:

META: A JSON file with identification information on the secured object without sensitive data.

CHANNELS

Available channels are Bluetooth Low Energy, socket, UART and NFC. They get defined in the following way:

--channel-btlespp [localname [service uuid]] (e.g. --channel-btlespp myBox4711 00005301-0000-002a-426c-756549442a00)
--channel-socket hostname [port] (e.g. --channel-socket 155.676.976.100 8080)
--channel-uart device (e.g. --channel-uart /dev/xxx)
--channel-nfcpki Activate support for NFC PKI cards

For more details use the help output. If you don't define any channel, Bluetooth Low Energy is used with a random local name.

Example Output: JSON

{
  "localPrivate": "0000000000000000000000000000000000000000000000000000000000000000",
  "operatorPublic": "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "trustCenterUrl": "https://deviceapi-int.blueid.net/deviceapi",
  "localKeyType": "ASYMMETRIC_KEY_TYPE_EC_SECP256R1",
  "operatorKeyType": "ASYMMETRIC_KEY_TYPE_EC_SECP256R1",
  "connectionParameters": {
    "btleLocalName": "ZZZZZZZZ",
    "btleUuid": "000053010000002a426c756549442a00"
  },
  "apiKey": "ZZZZZZZZZZZZZZZZZZZZ",
  "operatorPublicLength": 64,
  "id": "ZZZZZZZZZZ",
  "version": "3.3",
  "endian": "C_LITTLE_ENDIAN",
  "localPrivateLength": 32
}

Example invocation via command line

A simple call of the initializer using default Bluetooth Low Energy settings is shown below. For your first tests add the --dry-run option to avoid creating real objects.

java -jar sdkforc-initializer.jar --api-key R3YNEUMV38DI29F76NLX --environment INT --dry-run
java -jar sdkforc-initializer.jar -a R3YNEUMV38DI29F76NLX -e INT --dry-run

This will initialize the secured object to the Integration environment for the user with the given API key.

A usual call for a device that supports BLE and NFC looks like this:

java -jar sdkforc-initializer.jar -a YOUR_API_KEY_HERE -e INT_OR_PROD --channel-btlespp --channel-nfcpki

Using an HTTPS proxy

It is also possible to use the initializer tool with your own proxy server. For this to work, the https.proxyHost and https.proxyPort Java properties must be set. An example invocation would look like this:

java -Dhttps.proxyHost=<ProxyIP> -Dhttps.proxyPort=<ProxyPort> -jar sdkforc-initializer.jar [...]

Writing your own initialization tool

For writing your own initializer, we provide a small library (incl. apiDoc) that is also used by our initializer tool described above. Please have a look at the following files:

sdkforc-initializer-lib-javadoc.jar
to unpack the documentation: jar -xfv sdkforc-initializer-lib-javadoc.jar
sdkforc-initializer-lib.jar