diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/usr/secureboot/README.md | 64 | ||||
| -rw-r--r-- | src/usr/secureboot/base/README.md | 60 | ||||
| -rw-r--r-- | src/usr/secureboot/common/README.md | 33 | ||||
| -rw-r--r-- | src/usr/secureboot/ext/README.md | 24 | ||||
| -rw-r--r-- | src/usr/secureboot/node_comm/README.md | 97 | ||||
| -rw-r--r-- | src/usr/secureboot/runtime/README.md | 21 | ||||
| -rw-r--r-- | src/usr/secureboot/trusted/README.md | 74 |
7 files changed, 373 insertions, 0 deletions
diff --git a/src/usr/secureboot/README.md b/src/usr/secureboot/README.md new file mode 100644 index 000000000..979cada54 --- /dev/null +++ b/src/usr/secureboot/README.md @@ -0,0 +1,64 @@ +# Secureboot Services in Hostboot +Hostboot provides multiple services to help secure the system and + ensure that only 'trusted' code is running on it. The multiple sub-directories + implement the various interfaces defined in the + [src/include/usr/secureboot/](../../include/usr/secureboot/) directory. + +## Directories +* __base__ + * The modules here define the core secureboot support: **defining and + implementing interfaces to retrieve the security state of the system** + * The directory is called 'base' because its contents are included in the + Hostboot Base Image (HBB) partition + * See [base/README.md](base/README.md) for more details + +* __common__ + * The modules here provide common support like tracing, error callouts, + definitions of the secure "container" header, etc, that is used by the + secureboot modules in the peer directories + * See [common/README.md](common/README.md) for more details + +* __ext__ + * The modules here provide some additional secureboot capabilities that are + beyond the core secureboot functionality found in the "base" directory + * This directory is called 'ext' because its contents are included in the + Hostboot Extended Image (HBI) + * Any module here can call into the Hostboot Base Image (ie the 'base' code + in the HBB partition)), but Hostboot Base Image modules cannot call into + these extended image modules + * See [ext/README.md](ext/README.md) for more details + +* __node_comm__ + * The modules here implement a node-to-node communication protocol that is + used on multinode systems to share secureboot data between the nodes + * See [node_comm/README.md](node_comm/README.md) for more details + +* __runtime__ + * The modules here implement a small subset of secureboot code that is used by + Hostboot runtime services. + * See [runtime/README.md](runtime/README.md) for more details + +* __smf__ + * The modules here distribute different amounts of Secure SMF memory between + the available processors on the system based on a user-configurable petitboot + setting + * If we ever supported this on P9 FSP-based systems, the SMF memory amount + would be passed from the FSP to Hostboot using attributes. + * See [smf/README.md](smf/README.md) for more details + +* __trusted__ + * The modules here define the trusted boot support which uses TPMs (Trusted + Platform Modules) to track what code is running on the system + * See [trusted/README.md](trusted/README.md) for more details + +## Other Files +* __HBconfig__ + * Standard HBconfig file that defines secureboot- and trustedboot-related + Hostboot compile variables + +* __makefile__ + * Standard Hostboot makefile + +* __[README.md](./README.md)__ + * This file + diff --git a/src/usr/secureboot/base/README.md b/src/usr/secureboot/base/README.md new file mode 100644 index 000000000..e761c1f2f --- /dev/null +++ b/src/usr/secureboot/base/README.md @@ -0,0 +1,60 @@ +# **'base'** Secureboot Services in Hostboot +This directory implements the core of the secureboot-related functionality + that Hostboot provides. +It is available in the Hostboot Base Image (ie the HBB partition) and all + non-runtime Hostboot code can invoke functions provided by it. + +## Key Points +* The **libsecureboot_base.so** module created here is available in Hostboot's + base image and is used to securely bringup the rest of the Hostboot. +* It implements the functions in these header files: + * [service.H](../../../include/usr/secureboot/service.H) + * [settings.H](../../../include/usr/secureboot/settings.H) +* It is used to tell if security is enabled at the system or processor level +* It is used to determine the state of the secureboot jumper on the different + processors +* It provides the interface into the SecureRom to verify code packages run + on the system + +## Files + +* __header.C__ + * Implements functions related to loading and retrieving the + Hostboot Base header from Hostboot Base (HBB) PNOR partition + +* __makefile__ + * Standard Hostboot makefile + +* __purge.H__ + * Defines a special purge function + +* __[README.md](./README.md)__ + * This file + +* __securerommgr.C, securerommgr.H__ + * Defines and implements the SecureRomManager class and its member functions + * These functions call into the securerom and takes advantage of + its functionality + +* __service.C__ + * Retrieves the secureboot registers on the processors in the system + * These functions are then used to add information to errorlogs and traces + * Initliaizes the SecureRomManager class + * Function to handle special secureboot failures + * Retrieves some global secureboot settings taken from Hostboot's bootloader + * NOTE: Functions in this file call into functions in settings.C when + appropriate + +* __settings.C__ + * Gets and Sets the two primary Secureboot-related SCOM registers: + * ProcSecurity (aka Proc Security Switch) + * ProcCbsControl + * Also applies knowledge of key bits of these two registers, like returning + if a processor is set in 'secureboot enabled mode' and what the state of its + secureboot jumper is + + +## sub-directories +* __test__ + * Standard Hostboot test directory that implements CXX Unit Tests + diff --git a/src/usr/secureboot/common/README.md b/src/usr/secureboot/common/README.md new file mode 100644 index 000000000..56ff15953 --- /dev/null +++ b/src/usr/secureboot/common/README.md @@ -0,0 +1,33 @@ +# **'common'** Secureboot Services in Hostboot +This directory implements utility functions for tracing and error logging + that other secureboot modules in the peer directories can use. +For example, the secureboot_base, secureboot_rt (runtime), secureboot_trusted, +secureboot_ext, and node_comm modules use these functions. + +## Files + +* __common.mk__ + * Makefile that other makefiles can call to include the generated .o files + +* __containerheader.C__ + * Implements the ContainerHeader class's member functions + * Functions are defined in + [containerheader.H](../../../include/usr/secureboot/containerheader.H) + +* __errlud_secure.C, errlud_secure.H__ + * These files define and implement custom error log user detail sections to + capture security information on the system + +* __[README.md](./README.md)__ + * This file + +* __securetrace.C, securetrace.H__ + * Defines and implements standard Hostboot trace descriptors for the + secureboot component + +## sub-directories +* __plugins__ + * Standard Hostboot 'plugins' directory where the errorlog parser finds the + information to properly parse the custom error log user detail sections + defined in errlud_secure.H + diff --git a/src/usr/secureboot/ext/README.md b/src/usr/secureboot/ext/README.md new file mode 100644 index 000000000..797905b0d --- /dev/null +++ b/src/usr/secureboot/ext/README.md @@ -0,0 +1,24 @@ +# **'ext'** Secureboot Services in Hostboot +This directory implements additional (or 'extended') secureboot functionality + that is not considered part of the 'base' secureboot support. + +## Files + +* __makefile__ + * Standard Hostboot makefile + +* __phys_presence.C__ + * Implements the 'physical presence'-related functions, which are used to + assert that a system owner is physically present at the site of a system. + * This is done by using GPIO devices on the system's power button to + capture that the button was physically pressed. + * Functions are defined in + [phys_presence_if.H](../../../include/usr/secureboot/phys_presence_if.H) + +* __[README.md](./README.md)__ + * This file + +* __service_ext.C__ + * Implements some additional (or 'extended') functionality as defined in + [service_ext.H](../../../include/usr/secureboot/service_ext.H) + diff --git a/src/usr/secureboot/node_comm/README.md b/src/usr/secureboot/node_comm/README.md new file mode 100644 index 000000000..0def94860 --- /dev/null +++ b/src/usr/secureboot/node_comm/README.md @@ -0,0 +1,97 @@ +# **'node\_comm'** Secureboot Services in Hostboot +This directory implements the Hostboot functions necessary to create a + secure channel between nodes using a series of a-bus mailbox registers + enabled after a-bus training but before the iovalid drop. +This secure channel is used in a multi-node evironment for nodes to exchange + cryptographic material that can later be used for internode authentication + higher up the firmware stack. + +## Key Points +* This code implements device driver-like functionality to send messages + across the a-bus connection from one node to another + * This functionality is based on a-bus mailbox registers which are used to + detect incoming messages, retrieve data, and send data messages to/from + specific nodes +* This code establishes a master node which then starts the process of exchanging + information with each of the other slave nodes +* The files are built into libnode_comm.so +* This module implements the interfaces defined in + [nodecommif.H](../../../include/usr/secureboot/nodecommif.H) +* NOTE: The P9 code references "OBUS" a lot which is the specific processor + chiplet that the a-bus messaging system runs through. + +## Algorithm +* First, each node does the following: + * Determine the nodes in the system + * Determine the master processor of this node + * Determine the a-bus connection to its master processor peers on the + other nodes + +* ***The Master Processor on Master Node*** does the following + (see node_comm_exchange.C's nodeCommAbusExchangeMaster()): + * **Loop 1:** Exchange SBID/nonces between Master and each of the Slave Nodes + * Generate SBID/nonce and send to slave node + * Look for return SBID/nonce from the slave + * **Loop 2:** Master Node requests quotes from each Slave Node + * Generate and send Quote Request to a slave + * Look for Quote Response from the slave node + * Process the Quote Response that was returned from the slave node + * NOTE: + * Nonces are encoded 64-bytes of data: part random number, part node ID + * Quotes are a form of attestation between two TPMs on the system. See + TrustedComputingGroup.org's Trusted Platform Module Library Specification, + Family "2.0" for more details. + +* ***The Master Processor on each Slave Node*** does the following + (see node_comm_exchange.C's nodeCommAbusExchangeSlave()): + + * Wait for SBID/nonce from the master node + * Send a SBID/nonce back to the master node + * Wait for Quote Request from master node + * Generate the Quote Response + * Send the Quote Response to the master node + + +* NOTE: Generating the SBID/Nonces, Quote Requests, and Quote Responses above + all require interacting with the TPMs on the different nodes in specific + ways + * The devil is truly in the details, and the details can be found in the + supporting functions of node_comm_exchange.C +* NOTE: In the event that one node fails in this process there will be an + attempt to poison the TPMs on that node and move on in most cases. This is + to prevent an entire system from failing to boot with one bad node. + +## Files + +* __makefile__ + * Standard Hostboot makefile + +* __node_comm.C, node_comm.H__ + * The majority of the sub-functions used to implement the algorithm are + defined and implemented here, including the a-bus mapping details between + the nodes + +* __node_comm_dd.C, node_comm_dd.H__ + * Defines and implements the "NODECOMM" device driver that interacts directly + with the a-bus mailbox registers + +* __node_comm_exchange.C__ + * The core of this module - the primary function nodeCommAbusExchange() + is implemented here and shows the high-level data flow between the nodes + * The procedure for the master node is defined in nodeCommAbusExchangeMaster() + * The procedure for the slave nodes is defiend in nodeCommAbusExchangeSlave() + * The interactions with the TPM - generating and logging SBID/Nonces, Quote + Requests, Quote Responses - are all in this file + +* __node_comm_test.C__ + * Implements the proof-of-concept "nodeCommXbus2ProcTest" test to transfer + data across the x-bus between processors using a similar method to the a-bus + mechanism + +* __node_comm_transfer.C, node_comm_transfer.H__ + * Defines and implements the different types of messages that can be sent + between the nodes, including the actual send and receive functions + +* __[README.md](./README.md)__ + * This file + diff --git a/src/usr/secureboot/runtime/README.md b/src/usr/secureboot/runtime/README.md new file mode 100644 index 000000000..552ca9b6f --- /dev/null +++ b/src/usr/secureboot/runtime/README.md @@ -0,0 +1,21 @@ +# **'runtime'** Secureboot Services in Hostboot +This directory implements a small, select subset of core secureboot-related + functionality that Hostboot provides at runtime, ie as part of + Hostboot runtime services. + +## Files + +* __makefile__ + * Standard Hostboot makefile + +* __[README.md](./README.md)__ + * This file + +* __rt_secureboot.C__ + * This file implements several secureboot functions for hostboot runtime + services + +## sub-directories +* __test__ + * Standard Hostboot test directory that implements CXX Unit Tests + diff --git a/src/usr/secureboot/trusted/README.md b/src/usr/secureboot/trusted/README.md new file mode 100644 index 000000000..effe75f44 --- /dev/null +++ b/src/usr/secureboot/trusted/README.md @@ -0,0 +1,74 @@ +# **'trusted'** Secureboot Services in Hostboot +This directory implements the 'trusted' boot functionality that Hostboot + provides. +It primarily does this by measuring and storing firmware images and system + data into the system's TPMs (Trusted Platform Modules). + +## Key Points +* This code measures specific information on the system, including different + firmware images that are loaded onto the system by hostboot +* These mesasurements, along with other system data, are stored in the TPMs + on the system +* This code also determines which TPMs exist on the system, if they are + functional, and initializes them +* To directly talk to the TPMs this code uses the TPM Device Driver, which + is built on top of the I2C Device Driver: + * [src/usr/i2c/tmpdd.C](../../i2c/tpmdd.C) + * [src/usr/i2c/tpmdd.H](../../i2c/tpmdd.H) + +* The **libsecureboot_trusted.so** module created here is available in + Hostboot's extended image +* However, the code in the 'base' sub-directory is built into + libsecureboot_base.so and is available in Hostboot's base image +* This module implements the interfaces defined in + [trustedbootif.H](../../../include/usr/secureboot/trustedbootif.H) + +## Files + +* __makefile__ + * Standard Hostboot makefile + +* __[README.md](./README.md)__ + * This file + +* __tpmLogMgr.C, tpmLogMgr.H__ + * Defines and implements functions around the TPM Event Log, including + adding new events, extending the log to the TPM, and moving the log to + different memory locations + +* __trustedTypes.C, trustedTypes.H__ + * Defines different structures and methods for sending and receiving data + to and from the TPM + +* __trustedboot.C, trustedboot.H__ + * Defines and implements the majority of the functions that interact with the + TPMs + * Implements the majority of the functions that verify and initialize the TPMs + +* __trustedbootCmds.C, trustedbootCmds.H__ + * Defines and implements commands sent to the TPM and then processes (aka + marshall and unmarshall) the data appropriately + +* __trustedbootUtils.C, trustedbootUtils.H__ + * Defines and implements a few utility functions like a wrapper to the TPM + Device Driver and creating trustedboot error logs. + + +## sub-directories +* __base__ + * These files create a message queue to reserve operations that can be + implemented once the full Hostboot extended code, including + libsecureboot_trusted.so, is available to process them + * These files also take the basic operations that the Hostboot base code + needs and sends them to the message queue + * __trustedboot_base.C__ + * Implements early trustedboot/TPM calls be calling into a message + queue so that they can be processed later + + * __trustedbootMsg.C, trustedbootMsg.H__ + * Defines and implements the message queue so that commands can be + processed later when libsecureboot_trusted.so is available + +* __test__ + * Standard Hostboot test directory that implements CXX Unit Tests + |
