Security

Introduction

The following chapter describes the authentication and authorization mechanisms that Bosch IoT Rollouts offers both for IoT devices as well as for services/users. However, for secure software updates in IoT context additional mechanisms have to be in place.

As the Bosch Holistic IoT security whitepaper describes, it is as well necessary that the update process ensures that the artifacts themselves are protected in an end-to-end manner using digital signatures that can safeguard their authenticity and integrity.

This functionality by design is not offered by Rollouts e.g. by means of automatic artifact signature generation. In fact, signatures have to be generated and signed by a trusted source, i.e. is an outcome of the artifact release process. Rollouts responsibility, as part of a secure update infrastructure, is to distribute artifacts in a secure manner but the end-to-end trust relationship has to be between the device and the authority that published the artifacts.

It is recommended to rely on an asymmetric key encryption scheme if supported by the device. As an additional defense-in-depth measure, it is as well recommended but not necessarily mandatory that software artifacts are encrypted end-to-end to render reverse engineering more difficult.

We strongly advise not to distribute the encryption key with Rollouts, as such a behaviour would undermine the benefits of the encryption mechanism and is, as a result by design again, out of scope for Rollouts. Solutions for managing encryption keys on devices exist, e.g. by the Bosch group.

As mentioned in the whitepaper it is as well recommended that IoT devices implement a secure boot mechanism that prevents persistent compromise of IoT devices and helps to protect from potential misuse of secret key material.

Authentication

The Rollouts server can be accessed in several ways:

DDI API authentication modes

IoT Rollouts supports multiple ways to authenticate a target against the server. The different authentication modes can be individual enabled and disabled within Rollouts.

Certificate authentication with TLS termination at Bosch IoT Cloud’s load balancer

IoT Rollouts allows the authentication based on a defined HTTP-header set by a trusted load balancer. The load balancer terminates the TLS connection and adds common name of the certificate which is equal to the ID of the target. This is preferred and if done right by far most secure way to handle target authentication. However, in order to do so the load balancer also checks the certificate chain which has to be provided by the client as well. The root or intermediate CA’s certificate MD5 hash is then checked by Rollouts to establish trust with the client certificate provided by the device.

The MD5 hash in lower case can be configured in the configuration view.

Header Authentication

X-SSL-ISSUER-HASH-1: 2e:24:d0:ce:31:9c:9c:fd:5b:88:0f:b4:67:6c:2e:2a
X-SSL-ISSUER-HASH-2: 0e:da:70:c8:e1:e1:fb:79:80:cd:dd:69:e4:0c:ca:79

Note: The reverse proxy might inject multiple of those header values (i.e. all members of the chain). The Rollouts service browses through them and check if one fits the configured hash of the tenant.

This needs to be enabled for your account:

Enable Certificate Authentication

Note: It is possible to provide multiple certificate fingerprints by using a semicolon as separator. Rollouts verifies that at least one of the provided hashes matches. This might be useful for certificate migration.

Check out the How to setup client certificate based authentication for devices on Bosch IoT Cloud guide for a step by step walkthrough based on openssl and curl.

Target security token authentication

There is a 32 alphanumeric character security-token for each created target within IoT Rollouts. This token can be used to authenticate the target at the IoT Rollouts through the HTTP-Authorization header with the custom scheme TargetToken.

GET /SPDEMO/controller/v1/0e945f95-9117-4500-9b0a-9c6d72fa6c07 HTTP/1.1
Host: sp.apps.bosch-iot-cloud.com
Authorization: TargetToken bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY

The target security token is provided in DMF API as part of the update message in order to allow DMF clients to leverage the feature or it can be manually retrieved per target by Management API or in the Management UI in the target details.

Needs to be enabled for your account:

Enable Target Token

Gateway security token authentication

Often the targets are connected through a gateway which manages the targets directly and as a result are indirectly connected to the Rollouts update server.

To authenticate this gateway and allow it to manage all target instances under its tenant there is a GatewayToken, to authenticate this gateway through the HTTP-Authorization header with a custom scheme GatewayToken. This is of course also handy during development or for testing purposes. However, we generally recommend to use this token with great care as it allows to act “in the name of” any device.

GET /SPDEMO/controller/v1/0e945f95-9117-4500-9b0a-9c6d72fa6c07 HTTP/1.1
Host: sp.apps.bosch-iot-cloud.com
Authorization: GatewayToken 3nkswAZhX81oDtktq0FF9Pn0Tc0UGXPW

Needs to be enabled for your account:

Enable Gateway Token

Anonymous download

For download only it is also possible to enable anonymous access. That includes even un-encrypted data transport (e.g. HTTP without TLS). This option has to be used with care! It might be useful for scenarios where the artifact itself is already encrypted. However, a tenant that has this configuration enabled cannot protect itself from random downloads by anyone. That traffic will be charged by Rollouts on its account.

Needs to be enabled for your account:

Enable Anonymous Download

DMF API

Authentication is provided by the Rollouts service broker interface with a separate RabbitMQ vhost and user credentials per service binding.

Management API

Option 1: Bosch IoT Permissions integration

  • Basic Auth
  • IM API key header field
  • IM Context ID header field
  • IM Javascript Support API Cookie

Note: check out Bosch IoT Permissions developer guide for further information.

Option 2: Bosch IoT Rollouts technical cloud user

  • Rollouts Basic Auth as provided through environment variables
  • User: “TENANT\USERNAME”
  • Password: “PASSWORD”

Management UI

  • Login Dialog

Authorization

Authorization is handled separately for Direct Device Integration (DDI) API and Device Management Federation (DMF) API (where successful authentication includes full authorization) and Management API and UI which is based on permissions.

DDI API

An authenticated target is permitted to:

  • retrieve commands from the server.
  • provide feedback to the server.
  • download artifacts that are assigned to it.

Anonymous download

A target might be permitted to download artifacts without authentication (if enabled, see above).

Management API and UI

The Bosch IoT Rollouts permissions grant access to different repository functionalities and data. The permissions are identical between the two service options running either combined with a separately purchased Bosch IoT Permissions service that allows the tenant to grant different permissions to different users (“multi user”) or the Rollouts technical cloud user that is granted with all permissions of the tenant (“single user”).

Delivered permissions

  • READ/UPDATE/CREATE_/DELETE_TARGETS for:
    • Target entities including metadata (that includes also the installed and assigned distribution sets)
    • Target tags
    • Target actions
    • Target registration rules
    • Bulk operations
    • Target filters
  • READ/UPDATE/CREATE_/DELETE_REPOSITORY for:
    • Distribution sets
    • Software Modules
    • Artifacts
    • DS tags
  • READ_TARGET_SECURITY_TOKEN
    • Permission to read the target security token. The security token is security concerned and should be protected.
  • DOWNLOAD_REPOSITORY_ARTIFACT
    • Permission to download artifacts of a software module (Note: READ_REPOSITORY allows only to read the metadata).
  • TENANT_CONFIGURATION
    • Permission to administrate the tenant settings.
  • ROLLOUT_MANAGEMENT
    • Permission to provision targets through rollouts (not included in starter plan).

Permission matrix for example uses cases that need more than one permission

Use Case Needed permissions
Search targets by installed or assigned distribution set READ_TARGET, READ_REPOSITORY
Assign DS to a target READ_REPOSITORY, UPDATE_TARGET
Assign DS to target through a Rollout, i.e. Rollout creation and start READ_REPOSITORY, UPDATE_TARGET, ROLLOUT_MANAGEMENT
Read Rollout status including its deployment groups ROLLOUT_MANAGEMENT
Checks targets inside Rollout deployment group READ_TARGET, ROLLOUT_MANAGEMENT

Delivered Bosch IoT Permissions default roles

Deployment admin

The deployment administrators job is to manage the targets itself and trigger actions on them.

Contains the permissions:

  • READ_TARGET, READ_TARGET_SECURITY_TOKEN, UPDATE_TARGET, CREATE_TARGET and DELETE_TARGET to manage the targets
  • READ_REPOSITORY to find out what is deployed on the targets
Repository admin

The repository administrator manages the software repository itself including information concerning the deployment status of the repository artifacts.

Contains the permissions:

  • READ/UPDATE/CREATE_/DELETE_REPOSITORY to manage the repository
  • READ_TARGETS in order to find out where the repository content is applied
  • DOWNLOAD_REPOSITORY_ARTIFACT to download artifacts
Rollout Admin

The rollout administrator manages the rollouts or campaigns for large scale update operations.

Contains the permissions:

  • READ_/UPDATE_TARGET and ROLLOUT_MANAGEMENT to manage and execute the rollouts
  • READ_REPOSITORY to define the software that is applied through the rollout
Support agent

The support agent can look into targets and repository in order to investigate support cases.

Contains the permissions:

  • READ_REPOSITORY, READ_TARGET for situation overview.
Tenant administrator

The tenant administrator can configure tenant specific settings.

  • TENANT_CONFIGURATION
Beta Features

Special role for closed beta customers of upcoming feature previews. Beta features are marked as those in the Rollouts documentation. Please contact Rollouts customer support in case you interested in becoming part of the closed beta program.

Device Management Federation API

The RabbitMQ vhost and user is provided with the necessary permissions to send messages to Rollouts through the exchange and receive messages from it through the specified queue. In addition, the permission exists for an application to create their own queues and exchanges and in combination with the reply to header tell Rollouts to send all messages into that setup.