swissbit Secure Boot SDK for Raspberry Pi User Manual

: June 3, 2024
: swissbit

Table of Contents

Glossary and SDK Contents
Swissbit Secure Boot Solution for Protecting the System Integrity of a
Quickstart Guide
Swissbit micro SD Card Configuration
U-Boot Installation
Activation of Card Data Protection
Booting the Raspberry Pi with activated security
Appendix
Document History
References
- Read User Manual Online (PDF format)
- Download This Manual (PDF format)

swissbit Secure Boot SDK for Raspberry Pi

swissbit Secure Boot SDK for Raspberry Pi

Copyright 2021 by Swissbit AG
This document as well as the information or material contained is copyright protected. Any use not explicitly permitted by copyright law requires prior consent of Swissbit AG. This applies to any reproduction, revision, translation, storage on microfilm as well as its import and processing in electronic systems, in particular. The information or material contained in this document is property of Swissbit AG and any recipient of this document shall not disclose or divulge, directly or indirectly, this document or the information or material contained herein without the prior written consent of Swissbit AG.
All copyrights, trademarks, patents and other rights in connection herewith are expressly reserved to Swissbit AG and no license is created hereby.
Subject to technical changes.
All brand or product names mentioned are trademarks or registered trademarks of their respective holders.

Glossary and SDK Contents

Glossary

Abbreviation	Description
API	Application Programming Interface
DP	Data Protection
SDK	Software Development Kit
GUI	Graphical User Interface
CLI	Command Line Interface
SO	Security Officer
SHA	Secure Hash Algorithm
PIN	Personal Identification Number

Note: In this document, PIN is synonym for password as any binary value can be defined. In practice the password will most probably be a ASCII PIN
NVRAM| Non-Volatile Random Access Memory

ⓘ Information / hints are denoted with this icon: ⓘ

Contents of the SDK

The Swissbit Secure Boot for Raspberry Pi solution provides an SDK with U-Boot binaries and configuration files for Raspberry 2, 3 and 4 boards, and managing applications tools to configure a Swissbit DP products. Prebuilt UBoot binaries are available for Raspberry Pi 2, 3 and 4 boards, configuration tools for Microsoft Windows (Windows 7 and higher). This chapter describes where to find the particular components. The Swissbit Secure Boot SDK is packed in the file Swissbit_SecureBoot_SDK_RPi.zip. After unpacking in a directory, the SDK has the following directory structure:

U-Boot Binary Files

The U-Boot Binary can be found in the respective folders for the Raspberry Pi.

RPI 2
U-Boot binary: \Raspberry\ RPI2\u-bootRPI2.bin
Binary U-Boot boot script: \Raspberry\ RPI2\boot.scr.uimg
RPI 3 B Plus & CM3+ lite
U-Boot binary: \Raspberry\ RPI3Bplus_CM3plus\u-bootRPI3.bin
Binary U-Boot boot script: \Raspberry\ RPI3Bplus_CM3plus \boot.scr
RPI 4
U-Boot binary: \Raspberry\ RPI4\kernel7l
Binary U-Boot boot script: \Raspberry\ RPI4\boot.scr
Kernel image \Raspberry\ RPI4\uImage

Applications for Managing DP-Devices

Swissbit Security DP devices can be configured using the Device Manager applications for (micro)SD and USB, located AppsuSDcard and

AppsUSB, respectively.

Swissbit Secure Boot Solution for Protecting the System Integrity of a

Raspberry PI Boot Media

A Raspberry Pi board boots from an SD (RPI 1) or micro SD (RPI 2, 3, CM3+ lite & 4) card inserted into the board. A default Raspbian installation installs the kernel on the boot partition and the root files system on a separate second partition. If standard storage cards are used, typically all data and files in both partitions can be read, modified and deleted by anybody.
The Swissbit Data Protection (DP) micro SD card PS-45u DP Raspberry Edition allows restricting access to data on the card by various configurable policies. The boot image can be set read-only to prevent from unauthorized modification. Authorization is performed in the Swissbit customized pre-boot phase to unlock access for a user or further boot.

Following security policy methods are available:

PIN policy: PIN input by the user
USB policy: an authorization dongle is plugged into the Raspberry Pi (requiring a Swissbit USB PU-50n DP “Raspberry Edition”)
NET policy: authorization through a network server

In the herein described setup, all files and data in the boot partition are read only and cannot be modified. The root file system of the Operating System can be read and writen after authentication. Thus, an authentication failure during boot will prevent the kernel from reading the OS root file system resulting in a boot failure. Please check www.swissbit.com/secure-boot- rpi (→Downloads) for the latest version of the Secure Boot SDK and documentation.
Note: After a successfull authentication (unlocked access for a user) to raspberry-pi, raspberry-pi will remain in authenticated/unlocked state until a power supply occurs in the raspberry pi/swissbit DP card. That means on a soft reboot of raspberry-pi, it will remain in unlocked state with the only exception of RPi4, where a power cycle triggered to swissbit DP card during soft reboot.

Quickstart Guide

The Swissbit Secure Boot Solution for Raspberry Pi allows encryption and access protection of data stored on the card. The DP card safeguards a data policy that is enforced with minimum interaction of the host system with the Raspberry Pi. Swissbit provides a Secure Boot SDK to integrate a Swissbit Data Protection (DP) micro SD card into a U-Boot boot environment.

Step 1: Check Prerequisites
In order to use Swissbit Secure Boot Solution for Raspberry Pi you first need:
– A Raspberry PI 2, 3 B Plus, CM3+ lite or 4 and its peripherals
– A Windows-based computer for configuring the Swissbit DP products

Step 2: Get Swissbit Secure Boot Solution for Raspberry Pi

The Swissbit Secure Boot Solution for Raspberry Pi consists of:
– A Swissbit Secure microSD card PS-45u DP “Raspberry Edition”
– The Swissbit Secure Boot SDK for Raspberry Pi
In case you choose to pursue an USB policy (see chapter 4.5.2 ),
– An additional Swissbit Secure USB stick PU-50n DP „Raspberry Edition“ is needed
In case you pursue a NET policy (see chapter 4.5.3 ),
– A linux based system is needed with docker installation to act as a NET policy server.
You can get the Swissbit Secure Boot Solution for Raspberry Pi from our Distribution partners. Please visit https://www.swissbit.com/en/support /where-to-buy/

Note: Currently, USB policy is not supported by the RPI4 because CCID is not supported by the current U-Boot for RPI4.
Step 3: Configure the Swissbit micro SD Card by choosing your security policy (cf. Chapter 4)
Authorization is performed in the Swissbit customized pre-boot phase to unlock access for further boot.
Swissbit offers the following security policy methods:

PIN policy (cf. chapter 4.5.1 ): PIN input by the user
USB policy (cf. chapter 4.5.2 ): an authorization dongle is plugged into the Raspberry Pi (requiring a separate Swissbit DP device: PU-50n DP ,,Raspberry Edition” )
NET policy (cf. chapter 4.5.3 ): authorization through a network server (require a linux based system is needed with docker installation to act as a NET policy server)

Step 4: Install U-Boot (cf. Chapter 5)
Step 5: Activate DP Card Data Protection (cf. Chapter 6)
Step 6: Securely boot the Raspberry Pi (cf. Chapter 7)

Swissbit micro SD Card Configuration

Insert microSD card into your Windows-based system

You can use an adapter to insert the Swissbit microSD card into your Windows- based system, e.g. PC or Notebook.

Run Swissbit Device Manager

The Swissbit Device Manager can be found at

AppsuSDcardWindowsbincardManager.exe. It can be started from that location or optionally be installed permanently using the install script at AppsWindowsinstall.bat. **NOTE:** The Swissbit Device Manager tool only works with Swissbit DP memory cards. If such a card is inserted and the Device Manager still reports “No secure device found”, please make sure that the card is formatted (e.g. FAT32) and got assigned a drive letter (e.g. F:) by Windows. Furthermore, the card must be writeable the write protect switch of micro-SD/SD adapters must be inactive.

Set Security Flags

Set the security flags with following steps:

Start the Swissbit Device Manager
Go to menu “Manage > Security Settings” and choose these settings:
– Support Fast Wipe: not checked
– Reset Requires SO PIN: checked
– Multiple Partition Protection: checked
– Secure PIN Entry: checked
– Login Status Survives Soft Reset: checked
Multiple Partition Protection has to be checked for the OS integrity (Raspberry) use case.
Click “Set” to confirm your choices.
Close the Swissbit Device Manager
Remove the Swissbit micro SD card from your computer, insert it again and restart Swissbit Device manager.

Prepare a Security Policy

Swissbit Secure Boot for Raspberry Pi requires setting a security policy used by U-Boot. Policies are written to the first block of the random access NVRAM. Therefore, the policy must contain at least one block and have correct access rights.

Prepare a security policy with following steps:

Start the Swissbit Device Manager
Go to menu “NVRAM > Configure”
Select for booth “Size” fields the value “1” and check the column for Read and Write access rights as shown below in Fig. 2.
Click “Configure” to confirm your choices.

Set a Security Policy

There are three policies available:
– PIN policy: PIN input by the user
– USB policy: an authorization dongle is plugged into the Raspberry Pi (requiring a Swissbit USB PU-50n DP „Raspberry Edition“)
– NET policy: authorization through a network server (require a linux based system is needed with docker installation to act as a NET policy server)

Set a “PIN” policy

PIN policy means the user has to enter a PIN to unlock the card for further boot process. Set the PIN policy with the following steps:

Start the Swissbit Device Manager
Go to menu “NVRAM > Read/Write Random Access Memory”
Enter “0” as the value for the block and click on “Select”
Write “PIN” into the text field
Click “Commit”
Click “Quit” to leave dialog

Set a “USB” policy

USB policy means that there is an additional Swissbit Secure USB stick PU-50n DP ,,Raspberry Edition” with CCID capabilities inserted in a USB slot of the Raspberry Pi board that is booted. This CCID device holds the unlock PIN in an encrypted format and provides it at boot time to the U-Boot authentication function.

Note: Currently, USB policy is not supported by the RPI4 because CCID is not supported by the current U-Boot for RPI4.

Set a “USB” policy in Swissbit microSD

Set the USB policy in the Swissbit microSD card with the following steps:

Start the Swissbit Device Manager
Go to menu “NVRAM > Read/Write Random Access Memory”
Enter “0” as the value for the block and click on “Select”
Write “USB” into the text field
Click “Commit”
Click “Quit” to leave dialog

Set a “USB” policy in authentication dongle

Set the USB policy in the authentication dongle (= additional Swissbit USB stick PU-50n DP „Raspberry Edition“) with the following steps:

Unplug the microSD card
Insert the additional Swissbit USB stick PU-50n Raspberry Pi Edition
Start the Swissbit Device Manager for USB at \Apps\USB\Windows\bin\cardManager.exe
Go to menu “Manage > Set Authenticity Secret”
Enter a PIN as an Authenticity Secret, re-type the Authenticity Secret
Click on “Set Authenticity Secret”

Note: Please remember the entered PIN (= Authenticity Secret) as you need to set the same value as the Authenticity Secret later on in the microSD card DP Activation Dialog.
Fig. 5 Configuring the additional USB device as an authentication dongle
when using an USB policy

Set a NET policy

NET policy means that during the boot process, U-Boot will retrieve authentication information from an authentication server in the network. The corresponding document “Swissbit NetPolicyServer User Manual” describes how to set up an authentication server.

In General:
The NET policy has this format: NET##.

: the IPv4 address or the name of the authentication server (Net policy server). : the UDP port on which the Net policy server is listening. Default port is 12375. Thus a properly formatted NET policy string would look like this: Example: NET#192.168.178.75#12375 → indicating an authentication server with the IP address 192.168.178.75 listening on port 12375. In case server is hosted over internet and can be access using DNS name then NET policy has format: NET##. Example: NET#netpolicy.ishield.cloud#12375 → indicating an authentication server with the DNS name netpolicy.ishield.cloud listening on port 12375.

Set the NET policy in the Swissbit microSD card with following steps:

Start the Swissbit Device Manager
Go to menu “NVRAM > Read/Write Random Access Memory”
Enter “0” as the value for the block and click on “Select”
Write the “NET##” string into the text field (example shown below in Fig. 6)
Click “Commit”
Click “Quit” to leave dialog

Next, it is required to get the Unique ID of the Swissbit microSD card for for the later configuration of the NET policy server:

Start the Swissbit Device Manager
Go to menu “Information > Device Status” or press “CTRL-S”
Write down the UniqueID of the Swissbit microSD card (or copy it to clipboard and save it digitally)

Install the Raspberry Pi Operating System

Install the Raspberry Pi Operating System onto the Swissbit micro SD card with the following steps:

Download the latest Raspbian OS image from: https://www.raspberrypi.org/downloads/raspbian/
Follow the installation procedure using e.g. the balenaEtcher tool: https://www.raspberrypi.org/documentation/installation/installing-images/windows.md
After you installed the Operating System onto the microSD card verify you can boot your Raspberry PI from this card and apply all OS updates.

Set a Protection Profile

Set a Protection Profile on the Swissbit micro SD card with following steps:

Re-Insert the microSD card into your Windows-based PC or notebook
Click on “Cancel” if your system requests to format the second partition on the micoSD card

A Protection Profile has to be set only in case “Multiple Partition Protection” has been selected in step 4.3 Note: If Multiple Partition Support has not been activated, this step cannot be applied since the protection profile is applied implicitly.
The Protection Profile determines which kind of protection is in force after security has been activated on the card. Protection profiles are assigned to partitions. Each partition can have exactly one profile type assigned. It is strongly recommended to check “Protect MBR”. With this setting, the card’s MBR can be read but not be modified. Even in unlocked state, the MBR is immutable and the card cannot be repartitioned.

Note: Repartitioning of the MBR is possible by the Admin and requires deactivation of the card’s security first. See 8.1 .
The OS integrity use case (e.g. for the Raspberry Pi) assumes two partitions. A boot partition that shall be readable at any time and a root file system partition that shall be accessible only after authentication. Set a protection profile with following steps:

Start the Swissbit Device Manager
Go to menu “Manage > Manage Protection Profiles”
If a popup window titled “Profiles not matching partitions” appears, asking whether you “want to reset all protection profiles?”, click “Yes”.
For Partition 1 choose value “Public CD-ROM”
For Partition 2 choose value “Private RW”
Check “Protect MBR”
Click “OK”

ⓘ If you see more than 2 partitions (e.g. 4 partitions) under “manage protection profiles”, please make sure that this is what you want. More than 2 partitions also appear if the “installing Operating System” step has been skipped by mistake. If so, please go back to Chapter 4.6 .
ⓘ Please note that the “Public CD-ROM” partition becomes read-only after the DP Card protection has been activated (see Ch. 6). Even in read-only mode the partition appears to be writable, but all changes will be reverted after removing & re-inserting the memory card. When the protection is not activated like described in Chapter 6. (Card is in “transparent mode”), regular read/write operation is possible on the partition.

U-Boot Installation

The U-Boot files required for the Swissbit U-Boot implementation on Raspberry Pi consists of a U-Boot binary and a U-Boot configuration script.

Insert the microSD-Card into a Windows-based machine and depending on your Raspberry Pi model, please follow the according steps as stated below:
If your Raspberry Pi model is a Raspberry PI 2:
a. Copy the file \Raspberry\RPI2\u-bootRPI2.bin onto the first partition of your microSD card.
b. Copy the file \Raspberry\ RPI2\boot.scr.uimg to the first partition of your microSD card.
c. On the first partition of your microSD card open the file “config.txt” and add the following line at the end: kernel=u-bootRPI2.bin
If your Raspberry Pi model is a Raspberry PI 3 B Plus or CM3+ lite:
a. Copy the file \Raspberry\RPI3Bplus_CM3plus\u-bootRPI3.bin onto the first partition of your microSD card.
b. Copy the file \Raspberry\RPI3Bplus_CM3plus\boot onto the first partition of your microSD card.
c. On the first partition of your microSD card please open the file “config.txt” and add the following line at the end: kernel=u-bootRPI3.bin
If your Raspberry Pi model is a Raspberry PI 4:
a. Replace the file kernel7l onto the first partition of your microSD card with \Raspberry\RPI4\kernel7l.
b. Copy the file \Raspberry\RPI4\boot onto the first partition of your microSD card.
c. Copy the file \Raspberry\RPI4\uImage onto the first partition of your microSD card
d. On the first partition of your microSD card please open the file “config.txt” and add the following line at the end: enable_uart=1
e. On the first partition of your microSD card please open the file “config.txt” and comment the line “dtoverlay=vc4-fkms-v3d” (that means add # before “dtoverlay=vc4-fkms-v3d” e.g. “# dtoverlay=vc4-fkms-v3d”)

Activation of Card Data Protection

In case the PIN or USB policy has been set before, please proceed with the activation of the DP card data protection.
In case the NET policy has been set before, please verify that the authentication server is up and running, then please proceed with the activation of the DP card data protection.
Insert the microSD-Card into a Windows-based machine and follow these steps:

Start the Swissbit Device Manager 2. Go to menu “Manage > Activate Data Protection”
Set a Password (min. 4 characters), which will be your user PIN, and set the Security Officer Password (min. 8 characters) NOTE: If you have chosen “USB policy”, the password must match the authenticity secret of the authentication dongle (USB stick PU-50n “Raspberry Pi Edition”), which has been set in Chapter 4.5.2 .
Click on “Activate Data Protection”.
NOTE: The “Public CD-ROM” partition(s) (see Chapter 4.7 ) will become read-only after the micro SD card data protection has been activated. Even in read-only mode the partition(s) will appear to be writable, but all changes will be reverted after removing & re-inserting the memory card.

Booting the Raspberry Pi with activated security

Now you can insert the prepared microSD Card Raspberry Pi Edition into your Raspberry Pi and securely boot up your Raspberry Pi. When using …

PIN policy: you will be asked to enter the Password in order to boot up the Raspberry PI
USB policy: please make sure that the Authenticity dongle (= USB stick PU-50n) is inserted into your Raspberry PI before you power up your Raspberry PI
The boot up of your Raspberry PI will look similar to the screenshot shown below:
NET Policy: Please make sure, that your Raspberry PI is connected to the network and the net policy server is up and running.
The boot up of your Raspberry PI will look similar to shown below:

Appendix

Deactivating DP Card Data Protection

If you want to make changes to the boot partition of the Swissbit DP card (PS- 45u Raspberry Pi Edition), you can do this only when the card has data protection deactivated (transparent mode).
Deactivate DP card following steps:

Start the Swissbit Device Manager
Go to menu “Manage > Deactivate Data Protection”
Enter the Security Officer Password
Click on “Deactivate Data Protection”

DP-card Compatibility on Raspberry-Pi

Due to a violation of the SD specification by the host (Raspberry-Pi), power- on recognition problems can occur
in seldom cases when Swissbit DP Cards are used on the Raspberry Pi. If the issue is triggered, the Raspberry Pi’s LED does flash 4 times and it won’t boot. This problem does not exist once the device has booted successfully.

Below are the status of Raspberry-PIs where there is a possibility that this problem can be occur:

Pi Model

|

Safe for use

---|---

2 Mod B

| Very low probability for issue
3 Mod B+|

Very low probability for issue

CM3 B+ lite

| Yes
4 Mod B|

Yes

Note: For Secure boot use case Swissbit recommends to use CM3 B+ lite model as it safe for use against poweron recognition problem with Swissbit DP Cards on the Raspberry Pi.

Remedies:

This very seldom power-on recognition problem with Swissbit DP card on the Raspberry Pi can be solved by adding ~100k resistor between CLK and GND pin in SD card slot of Raspberry Pi as shown in the below picture.

Note: Apply remedy only if the problem occurs

Placement of 100k Pull-Down between CLK and GND pin in SD card slot of Raspberry Pi