Introduction

Bosch IoT Rollouts System Software Updates supports to check the authenticity of received system- and update-reports using certificates. This may be required, if the reports are transmitted via an untrusted Software update app. This guide demonstrates how to leverage this feature in three steps:

Create a certificate chain for signing the reports. Note: If you already have a public key infrastructure, or signing certificate in place, you can skip this step.
Configure the fingerprint of a CA as trust anchor in Bosch IoT Rollouts System Software Updates
Create a signed report and upload it to the backend

Prerequisites

A booked Bosch IoT Rollouts including System Software Update extension service instance on EU-1.
You have OpenSSL and a curl with OpenSSL support installed on your client machine.

On MAC OS X this can be achieved with:

$ brew install curl-openssl
$ export PATH=/usr/local/opt/curl/bin:$PATH
# Tested with
$ openssl --version
  OpenSSL 3.3.1 4 Jun 2024 (Library: OpenSSL 3.3.1 4 Jun 2024)

Set up certificate chain for report signing

Generate root CA key and certificate

# Generate ECC key for root CA
$ openssl ecparam -name prime256v1 -genkey -noout -out ca_root.key

Note: The Common Name (CN) shouldn’t be empty.

# Generate root CA
$ openssl req -x509 -new -key ca_root.key -sha256 -days 1024 -out ca_root.crt

Generate intermediate CA key, signing request, and certificate

# Generate ECC key for intermediate CA
$ openssl ecparam -name prime256v1 -genkey -noout -out ca_intermediate.key

Note: The Common Name (CN) shouldn’t be empty.

# Generate certificate signing request
$ openssl req -key ca_intermediate.key -new -sha256 -out ca_intermediate.csr

Create the following configuration file:

# File: domainCA.ext
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:TRUE
keyUsage=keyCertSign,cRLSign,digitalSignature

Then, sign the intermediate CA with the root key:

# Sign intermediate CA certificate signing request with root key to create intermediate CA
$ openssl x509 -req -in ca_intermediate.csr -CA ca_root.crt -CAkey ca_root.key -CAcreateserial -out ca_intermediate.crt -days 356 -sha256 -extfile domainCA.ext

Generated gateway key, signing request, and certificate

# Generate ECC key for gateway certificate
$ openssl ecparam -name prime256v1 -genkey -noout -out gateway.key

Note: The Common Name (CN) shouldn’t be empty.

# Generate certificate signing request
$ openssl req -key gateway.key -new -out gateway.csr

Then, sign the gateway client certificate:

# Generate certificate signing request
$ openssl x509 -req -CA ca_intermediate.crt -days 365 -CAkey ca_intermediate.key -in gateway.csr -out gateway.crt

Create certificate chain

For checking the authenticity, the gateway needs to send the entire certificate chain along with the request. Bosch IoT Rollouts System Software Update extension will then validate the certificate chain and extract the fingerprints from all certificates.

To assemble the certificate chain, you can concatenate the single .crt files:

$ cat ca_intermediate.crt ca_root.crt > cert-chain.crt

Configure fingerprint of root CA as trust anchor

The fingerprint is required on the backend side as a trust anchor. The trust anchor can be any CA in the certificate chain depending on your public key infrastructure (PKI) setup. In this example we use the root CA, therefore, the backend trusts all reports signed with any of the certificates in that PKI.

$ openssl x509 -noout -fingerprint -sha256 -inform pem -in ca_root.crt
sha256 Fingerprint=BB:EA:2A:13:C7:21:DB:E0:01:37:07:58:5B:ED:85:09:47:D7:FF:8F:BF:9E:E4:65:9C:C3:BA:14:E3:7C:DD:D6

Then, configure as trust anchor by setting the fingerprint in the tenant configuration.

Note: If you already have fingerprints configured, you need to add them to the value array otherwise they will be overwritten.

$ curl -X 'POST' \
  'https://system-management.eu1.bosch-iot-rollouts.com/api/mgmt/v1/tenant-config/soup.report.validation.trusted.cert.fingerprints' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 'eyJhbGciOiJSUzI1NiIsImtpZCI6InB1Y....'' \
  -d '{"value": ["BB:EA:2A:13:C7:21:DB:E0:01:37:07:58:5B:ED:85:09:47:D7:FF:8F:BF:9E:E4:65:9C:C3:BA:14:E3:7C:DD:D6"]}'

Sign report and upload to Install API

Create signed system reports

After certificates are generated and the fingerprint is configured as trust anchor in Bosch IoT Rollouts System Software Update, the gateway certificate can be used to create signed reports. As input you can use any valid system report.

Note: The same command can be used to create a signed update-report, by adapting the -in <report.json> parameter.

$ openssl cms -sign -in systemreport.json -out systemreport.msg.signed -signer gateway.crt -inkey gateway.key -certfile cert-chain.crt -text

The signed report will look similar to:

$ cat systemreport.msg.signed
MIME-Version: 1.0
Content-Type: multipart/signed; protocol="application/pkcs7-signature"; micalg="sha-256"; boundary="----AF8849423398E29336BDF4A4F7FE84A1"
 
This is an S/MIME signed message
 
------AF8849423398E29336BDF4A4F7FE84A1
Content-Type: text/plain
 
{
  "timeStamp": "1684201667",
  "gatewayId": "gateway-123",
  "values": [
    {
      "type": "myModule",
      "id": "module-456"
    },
    {
      "type": "gateway",
      "id": "gateway-123",
    }
  ]
}
------AF8849423398E29336BDF4A4F7FE84A1
Content-Type: application/pkcs7-signature; name="smime.p7s"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smime.p7s"
 
MIIGMQYJKoZIhvcNAQcCoIIGIjCCBh4CAQExDTALBglghkgBZQMEAgEwCwYJKoZI
hvcNAQcBoIIEdTCCAW4wggEToAMCAQICFFJAGgLUplhzzO8yJDve7nkC1ADPMAoG
CCqGSM49BAMCMBcxFTATBgNVBAMMDElOVEVSTUVESUFURTAeFw0yNDA1MTAwNzQw
MzVaFw0yNTA1MTAwNzQwMzVaMBIxEDAOBgNVBAMMB0dBVEVXQVkwWTATBgcqhkjO
PQIBBggqhkjOPQMBBwNCAASga7WCJ62c+yTty9sbzBVKaxCVqMT+/vvZ3jVDSxmr
/5uUYeeCK22RqY0z8v10HwmxZCxzLRQdO4npJZBarosXo0IwQDAdBgNVHQ4EFgQU
WFL1MzYIYMl5GqNOosodAPig+kYwHwYDVR0jBBgwFoAUuFULx7oc1UVSAsiNjN7U
rBFc688wCgYIKoZIzj0EAwIDSQAwRgIhALsoPMnx/OLBMmy9TRuGhHWA4tNmgnSu
qEuGrBz/DnAMAiEA+b6WgFUKIliqeBvm7hpJCm3NCT+Fjf7iB0QFu2Sq7XUwggF4
MIIBH6ADAgECAgIQATAKBggqhkjOPQQDAjAPMQ0wCwYDVQQDDARST09UMB4XDTI0
MDUxMDA3NDAzNVoXDTM0MDUxMTA3NDAzNVowFzEVMBMGA1UEAwwMSU5URVJNRURJ
QVRFMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAElOMiZDh0VZ3K2Gx/BBWeVi1s
QOvuoJt3wnU38DCtiP9aOjoixfFKMQb5Ej04VIyy+hdHJrqsIjyzWj5n8owmSaNj
MGEwHQYDVR0OBBYEFLhVC8e6HNVFUgLIjYze1KwRXOvPMA8GA1UdEwEB/wQFMAMB
Af8wDgYDVR0PAQH/BAQDAgGGMB8GA1UdIwQYMBaAFA5JruvxrfkKqW7KyE4urrvX
8UsBMAoGCCqGSM49BAMCA0cAMEQCIFZym7ZMzlK1JLHUu3RrspDedph5kdakCabU
Uddl5MKFAiApUIFBQV01Z3elU3eYGPy+ZtNhI2AOgQ2UrV33vYnDrjCCAYMwggEp
oAMCAQICFAgQO0d9Tl5V3IyYKhT3KJn/3NO1MAoGCCqGSM49BAMCMA8xDTALBgNV
BAMMBFJPT1QwHhcNMjQwNTEwMDc0MDM1WhcNNDQwNTEwMDc0MDM1WjAPMQ0wCwYD
VQQDDARST09UMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE1FBDt1K1jI6XNarG
E66Hdee0GiN/2YRNamWMNF0BoxEqXI3L65qGF6ZEOeBPnVcz9RctegZLsgAyVVis
HcpKKaNjMGEwHQYDVR0OBBYEFA5JruvxrfkKqW7KyE4urrvX8UsBMB8GA1UdIwQY
MBaAFA5JruvxrfkKqW7KyE4urrvX8UsBMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0P
AQH/BAQDAgGGMAoGCCqGSM49BAMCA0gAMEUCIAJMr2klm4nI2KM2bX5jNeU798Ot
TXx3MhNyef3Lh7qzAiEAk9M6x20d2psIIGcTGx3klF5eWDF7jrkk/paEs/+g9yAx
ggGCMIIBfgIBATAvMBcxFTATBgNVBAMMDElOVEVSTUVESUFURQIUUkAaAtSmWHPM
7zIkO97ueQLUAM8wCwYJYIZIAWUDBAIBoIHkMBgGCSqGSIb3DQEJAzELBgkqhkiG
9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTI0MDUxMDA3NDAzNVowLwYJKoZIhvcNAQkE
MSIEIM2TuEBVYUBFlvp8gJatT/WUzmh9R0Z3AX6jVt5b/vg3MHkGCSqGSIb3DQEJ
DzFsMGowCwYJYIZIAWUDBAEqMAsGCWCGSAFlAwQBFjALBglghkgBZQMEAQIwCgYI
KoZIhvcNAwcwDgYIKoZIhvcNAwICAgCAMA0GCCqGSIb3DQMCAgFAMAcGBSsOAwIH
MA0GCCqGSIb3DQMCAgEoMAoGCCqGSM49BAMCBEgwRgIhALzQXG+Vy2bVckAz4G0v
CU5tBPlpBhHBY8tmNqVd+vwqAiEAj/9eR3kRfalw62sHY6wJKg1cy+7LhExisLFA
SjH/pZU=
 
------AF8849423398E29336BDF4A4F7FE84A1--

Upload signed system report

Finally, the signed report can be uploaded using the Install API:

$ curl -X 'POST' \
    'https://system.eu1.bosch-iot-rollouts.com/api/install/v1/system-reports' \
    --form 'signedReport=@"./systemreport.msg.signed"' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6InB1Y....'