Live Objects - complete developer guide

Bootstrap Sequence

General case

Before being able to bootstrap a device, it is necessary to provision a Bootstrap Entry for the device and link it to a Bootstrap Config.
The Bootstrap sequence starts with the device sending a Bootstrap-Request (preceded by a DTLS Handshake). If the instance IDs to use for the Security Objects are not defined in the Bootstrap Config, a Bootstrap-Discover is sent by LiveObjects to be able to know which Security Object instance holds the Bootstrap server information and avoid it. The Security, Server and OSCORE Objects are deleted. The Security and Server Objects are then written using the parameters defined in the Bootstrap Config and the credentials defined in the Bootstrap Entry.
The Bootstrap sequence ends with LiveObjects sending a Bootstrap-Finish. The device can then register to the LwM2M Run servers.

Bootstrap sequence diagram

@startuml Bootstrap Sequence

Scale 0.8
skinparam style strictuml

participant "Device" as DEV
participant "LiveObjects" as LO
participant CUSTOMER #LightGreen

activate LO

== Provisioning ==
note over CUSTOMER
    Creates a new Bootstrap Config
end note
CUSTOMER -> LO : POST /api/v1/bootstrap/lwm2m/configs
LO -> CUSTOMER : 

note over CUSTOMER
    Creates a new Bootstrap Entry and
    associates it to the Bootstrap Config

    The Entry can be created before the Config
    and the association can be done afterwards
end note
CUSTOMER -> LO : POST /api/v1/bootstrap/lwm2m/entries
LO -> CUSTOMER : 

== Bootstrap sequence ==

activate DEV
DEV -> LO : DTLS Handshake (PSK)
LO -> DEV

note over DEV
    Bootstrap-Request
end note
DEV -> LO : POST /bs?ep={Endpoint Client Name}&pct={Preferred Content Format}

alt Accepted
    LO -> DEV : 2.04 Changed
else problem with credentials
    LO -> DEV : 4.00 Bad Request
else no Config or Invalid Config
    LO -> DEV : 4.00 Bad Request
end

alt The instance IDs to use for the Security Objects are not defined in the Bootstrap Config
    note over LO
        Bootstrap-Discover on all Objects

        The discover makes it possible to know
        the Security Object instance that holds
        the Bootstrap server information in order
        to avoid it
    end note
    LO -> DEV : GET /
    note over DEV
        ;lwm2m=1.1,,;uri="{bootstrapURI}",,,
    end note
    DEV -> LO : 2.05 Content
end

note over LO
    Bootstrap-Delete on Objects Security, Server and OSCORE
end note
LO -> DEV : DELETE /0, /1 and /21
DEV -> LO : 2.02 Deleted

note over LO
    Bootstrap-Write

    Instances of the Objects Security (id=0) et Server (id=1) are written

    If a Bootstrap-Discover was performed, the instance of the Security Object
    related to the Bootstrap server is avoided
end note
LO -> DEV : PUT /0/{i} and /1/{i}
DEV -> LO : 2.04 Changed

note over LO
    Bootstrap-Finish
end note
LO -> DEV : POST /bs
DEV -> LO : 2.04 Changed

note over DEV
    The device then Registers to the LwM2M server
end note

@enduml

The Bootstrap status is visible in the Bootstrap Entry. The status evolves as follows during the Bootstrap sequence:

Bootstrap state machine

@startuml BootstrapStatus scale 0.8 title Bootstrap Status state NEVER_REQUESTED : No Bootstrap-Request has ever been received for the entry state REQUESTED : A Bootstrap session is ongoing state FINISHED #PaleGreen : All the Bootstrap Information have been provided state FAILED #Pink : - Unauthorized\n- No config or invalid config\n- Unable to automatically provision credentials (if required)\n- Incorrect manual provisioning (in useLiveObjects mode)\n- Device-side exception (e.g. inconsistent configuration)\n- Any other unexpected exception [*] --> NEVER_REQUESTED : user creation of the Bootstrap Entry (north API) NEVER_REQUESTED -[#green,bold]-> REQUESTED : the device sends a Bootstrap-Request REQUESTED -[#green,bold]-> FINISHED : the server sends a Bootstrap-Finish REQUESTED -[#red,bold]-> FAILED : an error occurs during the Bootstrap session @enduml

Using LiveObjects as Run Server

To use LiveObjects as Run Server, the Bootstrap Config must be created with the parameter useLiveObjects set to true. Refer to this Bootstrap Config creation example.

A device must be created in your account (with the same endpoint name as the Bootstrap Entry) before the bootstrap takes place.

However, if you use the autoProvisionDeviceOnBootstrap.enabled=true setting in the config.RunServer definition, you can skip this device pre-provisioning: the device will be automatically created in the device inventory of the Bootstrap Entry’s customer account.

The device can be declared as being managed by the LiveObjects Bootstrap Server (bootstrap.managed = true and w/o security info) or not (bootstrap.managed = false and w/ security info). Refer to: LwM2M Device or LwM2M Device managed by Bootstrap creation examples.

If the device is created with bootstrap.managed = true (and in the same tenant as the Entry), the security info will be automatically provisioned in the LiveObjects device representation upon bootstrapping. Otherwise, they must be provisioned manually during the device creation, and they will be checked during bootstrap (i.e., do they match the security info that was provisioned in the Bootstrap Entry, and that will be set on the physical device).

If an error occurs during the automatic provisioning of the security info or if there is a security info mismatch, the Bootstrap sequence will fail. After a successful Bootstrap sequence, the device will register with the LiveObjects LwM2M Run server.

Bootstrap sequence using LiveObjects as Run Server

@startuml Bootstrap sequence using LiveObjects as Run Server scale 0.8 skinparam style strictuml participant "Device" as DEV participant "LiveObjects" as LO participant CUSTOMER #LightGreen activate LO == Provisioning == note over CUSTOMER Creates a new Bootstrap Config **with useLiveObjects = true** end note CUSTOMER -> LO : POST /api/v1/bootstrap/lwm2m/configs LO -> CUSTOMER : note over CUSTOMER Creates a new Bootstrap Entry and associate it to the Bootstrap Config end note CUSTOMER -> LO : POST /api/v1/bootstrap/lwm2m/entries LO -> CUSTOMER : note over CUSTOMER Creates a new Device * with the same endpoint name as the Bootstrap Entry * managed by LiveObjects Bootstrap Server or not (bootstrap.managed = true/false) end note CUSTOMER -> LO : POST /api/v1/deviceMgt/devices LO -> CUSTOMER : == Bootstrap sequence == activate DEV DEV -> LO : DTLS Handshake (PSK) LO -> DEV note over DEV Bootstrap-Request end note DEV -> LO : POST /bs?ep={Endpoint Client Name}&pct={Preferred Content Format} alt bootstrap.managed = false LO -> LO : Check that the security info that were \n manually provisioned in the LO device \n representation match the one that will be \n set by the Bootstrap Server else bootstrap.managed = true && the device and entry belong to the same tenant LO -> LO : Provision run credentials in the\nLiveObjects device representation end alt Accepted LO -> DEV : 2.04 Changed else Unable to provision security info or security info mismatch LO -> DEV : 5.00 Internal Server Error end note over DEV, LO The bootstrap sequence proceeds as usual end note note over LO Bootstrap-Finish end note LO -> DEV : POST /bs DEV -> LO : 2.04 Changed note over DEV The device registers with the LiveObjects Run server end note @enduml

With credentials generated at Bootstrap time

The following diagram describes the sequence when the run credentials are generated at Bootstrap time.
The Bootstrap Config has to be created with the renewSecurityOnBootstrap parameter set to true. Refer to this Bootstrap Config creation example. The Bootstrap Entry should be created without Run credentials (otherwise they will just be ignored).
If the Bootstrap Config does not set autoProvisionDeviceOnBootstrap.enabled=true, a device must be created on LiveObjects with the bootstrap.managed parameter set to true (and with the same endpoint name and on the same account as the Bootstrap Entry). Refer to this Device creation example.
At each Bootstrap new credential will be generated and automatically provisioned in the LiveObjects device representation. If an error occurs during the credentials provisioning, the Bootstrap sequence will fail. After a successful Bootstrap sequence, the device will register with the LiveObjects LwM2M Run server using the generated credentials.

Bootstrap sequence with credentials generated at bootstrap time

@startuml Bootstrap sequence with credentials generated at bootstrap time scale 0.8 skinparam style strictuml participant "Device" as DEV participant "LiveObjects" as LO participant CUSTOMER #LightGreen activate LO == Provisioning == note over CUSTOMER Creates a new Bootstrap Config * with useLiveObjects = true * and **renewSecurityOnBootstrap = true** end note CUSTOMER -> LO : POST /api/v1/bootstrap/lwm2m/configs LO -> CUSTOMER : note over CUSTOMER Creates a new Bootstrap Entry * **without run credentials** * and associate it to the Bootstrap Config end note CUSTOMER -> LO : POST /api/v1/bootstrap/lwm2m/entries LO -> CUSTOMER : note over CUSTOMER Creates a new Device * with the same endpoint name as the Bootstrap Entry * with **bootstrap.managed = true** * without run credentials * on the same tenant end note CUSTOMER -> LO : POST /api/v1/deviceMgt/devices LO -> CUSTOMER : == Bootstrap sequence == activate DEV DEV -> LO : DTLS Handshake (PSK) LO -> DEV note over DEV Bootstrap-Request end note DEV -> LO : POST /bs?ep={Endpoint Client Name}&pct={Preferred Content Format} LO -> LO : Generate new credentials and provision \nthem in the LiveObjects device representation alt Accepted LO -> DEV : 2.04 Changed else Unable to provision credentials LO -> DEV : 5.00 Internal Server Error end note over DEV, LO The bootstrap sequence proceeds as usual end note note over LO Bootstrap-Finish end note LO -> DEV : POST /bs DEV -> LO : 2.04 Changed note over DEV The device registers with the LiveObjects Run server using the generated credentials end note @enduml

Using a Bootstrap Master Entry

The following diagram describes the sequence when using a Bootstrap Master Entry.

A Bootstrap Master Entry must be created to get a Bootstrap Master Entry ID and a master PSK secret, from which the PSK identity and secret for each endpoint are derived (the key derivation is of course not done by the device, which must not know the master secret).

The Bootstrap Config must be created with the following parameters set to true: useLiveObjects, renewSecurityOnBootstrap, and autoProvisionDeviceOnBootstrap.enabled.

A Bootstrap Entry and a LwM2M device will be automatically created or updated for each endpoint using the Bootstrap Master Entry, (i.e., for each endpoint whose credentials are derived from it) during the Bootstrap sequence. For more details about how credentials are derived for each endpoint, refer to Endpoint Credentials.

Bootstrap sequence using a Bootstrap Master Entry

@startuml Bootstrap sequence with using a Bootstrap Master Entry scale 0.8 skinparam style strictuml participant "Device" as DEV participant "LiveObjects" as LO participant CUSTOMER #LightGreen activate LO == Provisioning == note over CUSTOMER Creates a new Bootstrap Config * with useLiveObjects = true * and renewSecurityOnBootstrap = true * and autoProvisionDeviceOnBootstrap.enabled = true end note CUSTOMER -> LO : POST /api/v1/bootstrap/lwm2m/configs LO -> CUSTOMER : note over CUSTOMER Creates a new Bootstrap Master Entry (with a link to a Bootstrap Config) end note CUSTOMER -> LO : POST /api/v1/bootstrap/lwm2m/masterEntries LO -> CUSTOMER : note over CUSTOMER Saves the Bootstrap Master Entry ID and PSK secret. Provisions endpoints using this information to determine the PSK identity and secret (derived from the master secret) to use for each endpoint. end note == Bootstrap sequence == note over DEV **PSK identity**: {Endpoint Client Name}@{Bootstrap Master Entry ID} **PSK secret**: derived from the master secret and endpoint name (The key derivation is not done by the device, which must not know the master secret.) end note activate DEV DEV -> LO : DTLS Handshake (PSK) LO -> DEV note over DEV Bootstrap-Request end note DEV -> LO : POST /bs?ep={Endpoint Client Name}&pct={Preferred Content Format} LO -> LO : Creates a Bootstrap Entry for the endpoint LO -> LO : Provision the device with some generated credentials\n (or update the credentials if the device was already created) note over DEV, LO The bootstrap sequence proceeds as usual end note note over LO Bootstrap-Finish end note LO -> DEV : POST /bs DEV -> LO : 2.04 Changed note over DEV The device registers with the LiveObjects Run server using the generated credentials end note @enduml