Skip to content

Commit 0164bb0

Browse files
albrecht-jalbrecht-j
authored
Merge pull request #198 from boschrexroth/release/3.6.1
Release/3.6.1
2 parents 698bda7 + 2337bf8 commit 0164bb0

17 files changed

+403
-10
lines changed

‎README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,26 @@ If your ctrlX App Build Environment is running, you can log in and install the c
3131

3232
__These installation steps are required on both an App Build Environment and an Ubuntu Server or Desktop System.__
3333

34+
### Prerequisite for the following Scripts
35+
36+
The following packages must be installed so that the following scripts can be executed. When using the __App Build Environment__, packages are installed when setting up an instance.
37+
38+
```bash
39+
sudo apt-get update
40+
sudo apt-get install -y \
41+
zip \
42+
unzip \
43+
p7zip-full \
44+
git \
45+
apt-transport-https \
46+
whois \
47+
net-tools \
48+
pkg-config \
49+
jq \
50+
sshpass \
51+
dpkg-dev
52+
```
53+
3454
### Clone and Install the ctrlX AUTOMATION SDK
3555

3656
Start a console session, change to your destination directory and enter:

‎doc/images/uefi-concept-fwupdate.png‎

7.86 KB
Loading

‎doc/images/uefi-permissions.png‎

91.5 KB
Loading

‎doc/images/uefi-trusted-certs-upload.png‎

157 KB
Loading

‎doc/images/uefi-trusted-certs.png‎

103 KB
Loading

‎doc/images/uefi-update-firmware.png‎

106 KB
Loading

‎doc/images/uefi-upload-fwupdate.png‎

102 KB
Loading

‎doc/package-assets.md‎

Lines changed: 89 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,25 @@ Scopes provided by the package
152152
"name": "View hello world",
153153
"description": "View (but not modify) hello world",
154154
"i18n": "scopes.view"
155+
},
156+
{
157+
"identifier": "ctrlx-helloworld.web.all.x",
158+
"name": "Operate hello world",
159+
"description": "Execute hello world",
160+
"i18n": "scopes.operate",
161+
"requiredScopes": [
162+
{
163+
"identifier": "ctrlx-tools.all.rwx",
164+
"purpose": "This scope is essential for executing hello world, as it provides access to the necessary tools."
165+
}
166+
]
167+
},
168+
{
169+
"identifier": "ctrlx-helloworld.web.rwx",
170+
"name": "Legacy Hello World Permissions",
171+
"description": "Full access to hello world.",
172+
"i18n": "scopes.rwx",
173+
"deprecated": true
155174
}
156175
]
157176
}
@@ -173,12 +192,21 @@ The Definiton of the scopes-declaration object:
173192

174193
Defition of the scope object:
175194

176-
| Field | Descriptions |
177-
| ------- | ------------------------------------|
178-
|**identifier** | string, the identifier of the scope |
179-
|**name** | string, the name of the scope |
180-
|**description**| string, description of the scope |
181-
|**i18n** | string, i18n tag, see [language files](#language files) and [translation](#translation)|
195+
| Field | Descriptions |
196+
| ------- | ------------------------------------|
197+
|**identifier** | string, the identifier of the scope |
198+
|**name** | string, the name of the scope |
199+
|**description** | string, description of the scope |
200+
|**i18n** | string, i18n tag, see [language files](#language files) and [translation](#translation)|
201+
|**requiredScopes**| array, array of requiredScope objects referencing other scopes that are required for this scope to function |
202+
|**deprecated** | boolean, indicates if the scope is deprecated. |
203+
204+
Defition of the requiredScope object:
205+
206+
| Field | Descriptions |
207+
| ------- | ------------------------------------|
208+
|**identifier** | string, the identifier of the referenced required scope |
209+
|**purpose** | string, a detailed explanation of why this scope is required. |
182210

183211
If access is restricted to specific resources, define scopes. When using the Identity Management, an administrator can configure the users and groups allowed to access specific resources. The following example shows two simple scopes (read/write, all settings, read-only settings). In every routine, the web server has to check whether the provided token includes the scope.
184212

@@ -264,6 +292,60 @@ The following snippet shows the definition of the admin scope. You can see (and
264292
]
265293
}
266294
```
295+
#### Required Scopes
296+
297+
Multiple scopes may be required to perform a particular action. To streamline the scope assignment process for the administrator, it is important to provide clear details of the required scopes. This information specifies the additional permissions required for certain functionalities and ensures that users and groups have the appropriate access rights to perform actions effectively.
298+
299+
!!! Example
300+
301+
```json
302+
{
303+
"identifier": "ctrlx-helloworld.web",
304+
"name": "Helloworld Scopes",
305+
"description": "Scopes for the Hello World App",
306+
"scopes": [
307+
{
308+
"identifier": "ctrlx-helloworld.web.all.x",
309+
"name": "Operate hello world",
310+
"description": "Execute hello world",
311+
"i18n": "scopes.operate",
312+
"requiredScopes": [
313+
{
314+
"identifier": "ctrlx-tools.all.rwx",
315+
"purpose": "This scope is essential for executing hello world, as it provides access to the necessary tools."
316+
}
317+
]
318+
}
319+
]
320+
}
321+
```
322+
#### Deprecated Scope
323+
324+
A deprecated scope is a permission that was once available for an application but is no longer utilized in its current and future versions.
325+
326+
!!! Remark
327+
- **When a scope is labelled as "deprecated", this permission may not be assigned to any users or groups.**
328+
- **The existing assignments of deprecated scopes can be removed from users and groups by administrator.**
329+
330+
!!! Example
331+
332+
```json
333+
{
334+
"identifier": "ctrlx-helloworld.web",
335+
"name": "Helloworld Scopes",
336+
"description": "Scopes for the Hello World App",
337+
"scopes": [
338+
{
339+
"identifier": "ctrlx-helloworld.web.rwx",
340+
"name": "Legacy Hello World Permissions",
341+
"description": "Full access to hello world.",
342+
"i18n": "scopes.rwx",
343+
"deprecated": true
344+
}
345+
]
346+
}
347+
```
348+
267349
### Services
268350

269351
<!-- md:version 1.0 -->
@@ -676,7 +758,7 @@ The definition of certificatestores object
676758

677759
|Field |Description |
678760
|---------------|--------------------------------------------------------------------------------------------------------|
679-
|**id** |string,Use a unique ID, as it is used to identify the store via the REST interface. Example: <br> - opcua <br> - vpnmanager|
761+
|**id** |string (max. 128 characters), Use a unique ID, as it is used to identify the store via the REST interface. Example: <br> - opcua <br> - vpnmanager|
680762
|**title** |string, name used in the front end. Example: <br> - OPCUA <br> - VPN Manager|
681763
|**description**|string, displayed in the front end. To describe the application and provide further information|
682764
|**scopesR** |array of strings, a list of scopes that allow the user to have read access to this certificate store, Example: <br> - rexroth-solutions.web.all.r <br> - example.permission.r|

‎doc/storage-extension.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ and the denylist has to be empty.
3535
sudo -s
3636
mkdir -p /etc/writable/integrity
3737
echo [] >/etc/writable/integrity/denylist.json
38-
snap restart rexroth-deviceadminw.web
38+
snap restart rexroth-deviceadmin.web
3939
```
4040

4141
After clearing the denylist it's possible to test storage extension without signed apps.

‎doc/uefi-firmware-updates.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# UEFI firmware updates for ctrlX OS Standard
2+
3+
UEFI firmware needs to be updatable in the field in order to apply security patches, e.g. in case of another [Spectre](https://en.wikipedia.org/wiki/Spectre_(security_vulnerability)) / [Meltdown](https://en.wikipedia.org/wiki/Meltdown_(security_vulnerability)) vulnerability.
4+
5+
On ctrlX CORE devices UEFI firmware updates are contained in the `Hardware Support` app (gadget snap). When you install a new version of the `Hardware Support` app that contains a UEFI firmware update, you will find the option to install the UEFI firmware update under `Settings > Apps > Update UEFI firmware`.
6+
7+
On ctrlX OS Standard devices it is not possible to ship UEFI firmware updates via the `Hardware Support` app as the same app is running on devices of multiple ctrlX OS partners with different UEFI firmware implementations.
8+
9+
Nevertheless, ctrlX OS Standard offers a secure and convenient way to deploy UEFI firmware updates.
10+
11+
## Prerequisites
12+
13+
UEFI firmware updates must be UEFI update capsules and must comply to the [UEFI specification](https://uefi.org/specs/UEFI/2.11/08_Services_Runtime_Services.html#update-capsule).
14+
15+
!!! Hint
16+
We strongly recommend to use update capsules with the [Firmware Management Protocol (FMP)](https://uefi.org/specs/UEFI/2.11/23_Firmware_Update_and_Reporting.html) and with required authentication (`IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED`).
17+
This provides an additional layer of security where the UEFI firmware itself will verify the integrity of the update capsule before executing it.
18+
You will need to inquire with your UEFI firmware vendor if FMP with required authentication is supported.
19+
20+
## Preparing a UEFI firmware update for ctrlX OS Standard
21+
22+
When uploading a UEFI firmware update to a ctrlX OS Standard device it will be checked if the update is from a trusted origin.
23+
24+
The certificates for trusted origins should be deployed onto the ctrlX OS Standard device during manufacturing, but can also be updated with the appropriate user permissions during runtime.
25+
26+
The UEFI firmware update must be provided as a `.fwupdate` archive.
27+
28+
### Provisioning UEFI firmware signature validation certificates
29+
30+
Your user on the ctrlX OS Standard device requires the `Certificates & Keys > Manage` permission to upload new trusted certificates for UEFI firmware updates.
31+
Make sure this permission is only available for authorized users to prevent misuse.
32+
33+
![`Certificates & Keys > Manage` permission required.](./images/uefi-permissions.png)
34+
35+
The private and public key with which UEFI firmware updates are signed should be owned and maintained by the ctrlX OS Standard device manufacturer.
36+
37+
An example how to generate P-384 ECDSA public and private keys with SHA-384 and the corresponding certificate can be found in [this example shell script using `openssl`](/public/scripts/firmware-generate-keys.sh).
38+
39+
!!! Hint
40+
Only P-384 ECDSA keys and SHA-384 are currently supported.
41+
42+
!!! Danger
43+
Take care of your private ctrlX OS UEFI firmware key and establish measures to protect against misuse and key leakage, like using an HSM.
44+
45+
To add a new trusted certificate for UEFI firmware updates go to `Settings > Certificate & Keys > UEFI firmware signature validation certificates`.
46+
47+
![Settings > Certificate & Keys > UEFI firmware signature validation certificates](./images/uefi-trusted-certs.png)
48+
49+
Upload your certificate in category `Trusted`.
50+
51+
![Upload as category `Trusted`](./images/uefi-trusted-certs-upload.png)
52+
53+
!!! Hint
54+
You can also manage your certificates with REST via the [ctrlX OS - Apps Management API](https://boschrexroth.github.io/rest-api-description/ctrlx-automation/ctrlx-core/).
55+
56+
### Packaging a UEFI firmware update as a `.fwupdate` archive
57+
58+
The UEFI firmware update must be provided in a proprietary `.fwupdate` archive to ctrlX OS Standard.
59+
60+
The `.fwupdate` is a `tar` archive that contains:
61+
62+
- `*.bin` file: The UEFI firmware update itself.
63+
- `*.signature` file: A detached signature for the digest of the UEFI firmware update
64+
65+
![Contents of a `.fwupdate` archive](./images/uefi-concept-fwupdate.png)
66+
67+
UEFI firmware updates are usually provided as [Cabinet](https://en.wikipedia.org/wiki/Cabinet_(file_format)) archives by UEFI firmware vendors.
68+
In addition to the update itself they often contain metadata information for [Windows (as a `firmware.inf` file)](https://learn.microsoft.com/en-us/windows-hardware/drivers/bringup/authoring-an-update-driver-package) and for [LVFS (as a `*.metainfo.xml` file)](https://lvfs.readthedocs.io/en/latest/metainfo.html#metadata).
69+
70+
Using the [`firmware-signing-tool.sh` script](/public/scripts/firmware-signing-tool.sh) you can repackage a UEFI firmware update from a `Cabinet` into a `.fwupdate`archive and create the detached signature.
71+
72+
!!! Hint
73+
Make sure all the required dependencies are installed by running [`install-ctrlx-os-dev-tools.sh`](/public/scripts/install-ctrlx-os-dev-tools.sh).
74+
75+
!!! Danger
76+
ctrlX OS Standard does not prevent potential UEFI firmware downgrades. As a ctrlX OS Standard device manufacturer it is your responsibility to inform your device operators about your process to install UEFI firmware updates in a forward-only manor.
77+
Update capsules with FMP support can express [Version dependencies](https://uefi.org/specs/UEFI/2.11/23_Firmware_Update_and_Reporting.html#dependency-expression-instruction-set) so that the UEFI firmware itself can prevent potential downgrades. Contact your UEFI firmware vendor for more details.
78+
79+
### Installing a `.fwupdate` archive on ctrlX OS
80+
81+
!!! Hint
82+
On ctrlX OS variants that deliver UEFI firmware updates via the `Hardware Support` app the following workflow is not supported.
83+
84+
Upload your `.fwupdate` archive under `Settings > Apps` with `Upload UEFI firmware`.
85+
86+
![`Settings > Apps > Upload UEFI firmware`](./images/uefi-upload-fwupdate.png)
87+
88+
On successful upload a new button `Update UEFI firmware` will appear.
89+
Click it and carefully read and confirm the pop-ups to start the UEFI firmware update process.
90+
91+
![`Settings > Apps > Update UEFI firmware`](./images/uefi-update-firmware.png)
92+
93+
!!! Hint
94+
An uploaded `.fwupdate` is not persisted on the device. If you restart the device before starting the UEFI firmware update as described above you will have to reupload the `.fwupdate` archive.

0 commit comments

Comments
 (0)