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