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:

  • Direct Device Integration (DDI) API by IoT devices
  • Artifact downloads by targets
  • Management API by 3rd party applications
  • Device Management Federation (DMF) API by 3rd party applications through AMQP.
  • Management UI by users

Note: access URLS are listed here

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: device.eu1.bosch-iot-rollouts.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: device.eu1.bosch-iot-rollouts.com
Authorization: GatewayToken 3nkswAZhX81oDtktq0FF9Pn0Tc0UGXPW

Needs to be enabled for your account:

Enable Gateway Token

Anonymous download (EU2 only)

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

Artifact download authentication

The artifact download authentication differs between Bosch IoT Suite (EU1) and Bosch IoT Cloud (EU2).

Download artifacts in Bosch IoT Suite instance (EU1)

Within Bosch IoT Rollouts the artifact download is done by signed URLs. This means that there is no device authentication necessary (DDI credentials) when downloading an artifact. However, to get the download URL by deployment base the device has to be authenticated. Furthermore, the received download URL has a validity expiration of 1 month. This means that devices might have to re-call deployment base if access is denied. Artifacts are delivered through a worldwide Content Delivery Network (CDN) to provide high availability and performance for downloads.

Download artifacts in Bosch IoT Cloud instance (EU2)

The Bosch IoT Cloud (EU2) offers two ways of downloading artifacts for Bosch IoT Rollouts. Either by using one of the provided authentication mechanisms (Target security token, Gateway security token or certificate authentication) or by allowing 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 (default): Bosch IoT Rollouts Cloud User

  • Rollouts Basic Auth as provided after booking
  • User: “TENANT\USERNAME”
  • Password: “PASSWORD”

Option 2: Bring your own Bosch IoT Permissions instance (supported on EU-2 only)

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

Management UI

Option 1 (default): Bosch IoT Rollouts Cloud User

  • Generated Rollouts root user credentials (tenant, username, password) as provided after booking
Root User Login
  • Or as alternative sign in with Bosch account (can be added to your instance in user management view in the Management UI).
Bosch User Login

Option 2: Bring your own Bosch IoT Permissions instance (supported on EU-2 only)

  • Bosch IoT Permissions tenant, username, password into 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 authentication options described above, i.e. either combined with a separately purchased Bosch IoT Permissions instance or the Rollouts Cloud User.

By default in the Cloud User user scenario a root user will be generated including username and password. This root user is granted with all permissions. Additional Bosch account registered users can be added by user management view in the Management UI. Keep in mind that Bosch account works as of now only for Management UI. For the Management API the root user has to be used for the time being (see above).

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.
  • READ_/UPDATE_/CREATE_/DELETE_/HANDLE_ROLLOUT
    • 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, CREATE_ROLLOUT, HANDLE_ROLLOUT
Read Rollout status including its deployment groups READ_ROLLOUT
Checks targets inside Rollout deployment group READ_TARGET, READ_ROLLOUT

Optional Bosch IoT Permissions (included 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_/CREATE_/DELETE_ROLLOUT to manage the rollouts
  • HANDLE_ROLLOUT to start or pause a rollout
  • READ_REPOSITORY to define the software that is applied through the rollout
  • READ_TARGET to see target filters for rollout definition and targets in the rollout groups
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.