1# eStoraged Design - Encrypted Secondary Storage Management Daemon 2 3Author: John Wedig <johnwedig@google.com> 4 5Other contributors: 6 7- John Broadbent <jebr@google.com> 8- Benjamin Fair <benjaminfair@google.com> 9- Nancy Yuenn <yuenn@google.com> 10 11Created: September 2, 2021 12 13## Problem Description 14 15This daemon will serve as an abstraction for an encrypted storage device, 16encapsulating the security functionality and providing a D-Bus interface to 17manage the encrypted filesystem on the device. Using the D-Bus interface, other 18software components can interact with eStoraged to do things like create a new 19encrypted filesystem, wipe its contents, lock/unlock the device, or change the 20password. 21 22## Background and References 23 24This design is intended to manage secondary storage devices and cannot be used 25for the root filesystem, i.e. the BMC needs to be able to boot while the device 26is still locked. 27 28This design makes use of the 29[cryptsetup](https://gitlab.com/cryptsetup/cryptsetup) utility, which in turn 30uses the [dm-crypt](https://en.wikipedia.org/wiki/Dm-crypt) kernel subsystem. 31Dm-crypt provides the encryption and device mapping capability, and Cryptsetup 32provides the [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup) 33capability, which facilitates password management so that we can do things like 34change the password without re-encrypting the entire device. 35 36This design is specifically targeted for use with eMMC devices, and we plan to 37make use of the lock/unlock feature (CMD42) at the eMMC hardware level as an 38additional security measure. This feature prohibits all read or write accesses 39to the device while locked. Some documentation on this feature can be found in 40the 41[JEDEC standard JESD84-B51A](https://www.jedec.org/document_search?search_api_views_fulltext=jesd84-b51), 42or in this document: 43[Enabling SD/uSD Card Lock/Unlock Feature in Linux](https://media-www.micron.com/-/media/client/global/documents/products/technical-note/sd-cards/tnsd01_enable_sd_lock_unlock_in_linux.pdf?rev=03f03a6bc0f8435fafa93a8fc8e88988). 44 45There are several types of keys referenced in this doc: 46 47- Volume key: The main encryption key used to encrypt the data on the block 48 device. 49- Encryption Password: The password needed to load the volume key into RAM and 50 decrypt the filesystem. 51- Device Password: The password to lock or unlock the device hardware. 52 53## Requirements 54 55This design should provide an interface for the following capabilities: 56 57- Create a new LUKS encrypted filesystem on the device 58- Securely wipe the device and verify that the data was wiped 59- Lock the device 60- Unlock the device 61- Change the password 62 63In addition, eStoraged should: 64 65- Generate a volume key using a random number generator with enough entropy, 66 making it sufficiently random and secure. 67- Utilize any security features provided by the hardware (as a defense-in-depth 68 measure). 69- Use interfaces that are generic enough, so that they can be extended to 70 support additional types of storage devices, as desired. For example, 71 different devices will have different command sets for device locking, e.g. 72 MMC, SATA, NVMe. Initially, we plan to only use eStoraged with eMMC devices, 73 but we may wish to use this with other types of storage devices in the future. 74 75The users of this design can be any other software component in the BMC. Some 76client daemon on the BMC will interact with eStoraged to set up a new encrypted 77filesystem on the eMMC. In addition, the client daemon could be configured to 78unlock the eMMC device when the BMC boots. It is the responsibility of the 79client daemon to provide a password. For example, this password could come from 80user input, fetched from a secure location, or the client daemon could generate 81the passwords itself. 82 83## Proposed Design 84 85eStoraged will represent each eMMC device as an object on D-Bus that implements 86an interface providing these methods and properties: 87 88- (method) Format 89- (method) Erase 90- (method) Lock 91- (method) Unlock 92- (method) Change Password 93- (property) Locked 94- (property) Status 95 96Upon startup, eStoraged will create a D-Bus object for each eMMC device in the 97system. Specifically, we will use udev to launch an eStoraged instance for each 98eMMC. The bus name and object name will be as follows: 99 100Bus Name: xyz.openbmc_project.eStorage.\<device name\> Object Path: 101/xyz/openbmc_project/storage/\<device name\> 102 103The object path is intended to be generic enough, so that we could ultimately 104have multiple daemons managing the same storage device, while using the same 105object path. For example, this daemon would handle the encryption, whereas 106another daemon could provide stats for the same device. 107 108To manage the encrypted filesystem, we will make use of the 109[cryptsetup API](https://mbroz.fedorapeople.org/libcryptsetup_API/). This 110library provides functions to create a new LUKS header, set the password, etc. 111 112For eMMC devices, we plan to enable the password locking feature (CMD42), to 113prevent all read or write accesses to the device while locked. So, the "Locked" 114property will mean both locked at the hardware level and locked at the 115encryption level. We will likely use the ioctl interface to send the relevant 116commands to the eMMC, similar to what 117[mmc utils](https://git.kernel.org/pub/scm/utils/mmc/mmc-utils.git/) does. 118 119Support for hardware locking on other types of devices can be added as needed, 120but at the very least, encryption-only locking will be available, even if 121hardware locking isn't supported for a particular device. 122 123As mentioned earlier, the client will provide a password. This password will be 124used by eStoraged to generate two different passwords: the encryption password 125and the device password (if hardware locking is available). The passwords will 126be different, so that in the event that one password is compromised, we still 127have some protection from the other password. 128 129The Erase method should provide a way to specify the type of erase, e.g. write 130all zeros, or do something else. Different organizations may have different 131opinions of what a secure erase entails. 132 133Since some of the D-Bus methods may take a while (e.g. installing a new 134encrypted filesystem), the D-Bus interface will be asynchronous, with the 135"Status" property that can be queried to indicate one of the following: success, 136error, or in-progress. 137 138## Alternatives Considered 139 140An alternative would be to use systemd targets to manage the eMMC. For example, 141the 142[systemd-cryptsetup@.service](https://www.freedesktop.org/software/systemd/man/systemd-cryptsetup@.service.html) 143is often used to unlock an encrypted block device, where it takes the password 144from a key file or from user input. However, the OpenBMC architecture calls for 145using D-Bus as the primary form of inter-process communication. In addition, 146using a daemon with a well-defined D-Bus interface keeps the security 147functionality more isolated, maintainable, and testable. 148 149Another related piece of software is UDisks2, which also exports a D-Bus object 150for each storage device in a system. It is capable of setting up an encrypted 151block device with the Format method: 152[org.freedesktop.UDisks2.Format](http://storaged.org/doc/udisks2-api/latest/gdbus-org.freedesktop.UDisks2.Block.html#gdbus-method-org-freedesktop-UDisks2-Block.Format). 153And it provides several additional methods related to encryption: Lock, Unlock, 154and ChangePassphrase. See the D-Bus interface 155[org.freedesktop.UDisks2.Encrypted](http://storaged.org/doc/udisks2-api/2.7.5/gdbus-org.freedesktop.UDisks2.Encrypted.html). 156The main problem preventing us from leveraging this tool is that it increases 157our image size too much. We found that the compressed image size increased by 22 158MB due to the transitive dependencies being pulled in, e.g. mozjs and python. 159 160## Impacts 161 162To make use of eStoraged, it may be necessary to provide another client daemon 163that manages the password and invokes the D-Bus API for eStoraged. Since the 164password management scheme can be unique for different platforms and 165organizations, it is outside the scope of this design. 166 167## Testing 168 169- Unit tests to validate the various code paths in eStoraged. 170- Regression tests will exercise the various D-Bus methods: encrypt, erase, 171 lock, unlock, and change password. 172