diff options
author | Mike Baiocchi <mbaiocch@us.ibm.com> | 2019-12-20 11:50:01 -0600 |
---|---|---|
committer | Daniel M Crowell <dcrowell@us.ibm.com> | 2020-02-13 08:55:47 -0600 |
commit | 20b285f6301b51c67ab734fe36123fa8da4a6021 (patch) | |
tree | c4f949247bb62fa20fa1394eeb1310c592e04279 /src/usr/secureboot/node_comm | |
parent | 798af67f241d6a8479c952485099e7b60d4aa823 (diff) | |
download | talos-hostboot-20b285f6301b51c67ab734fe36123fa8da4a6021.tar.gz talos-hostboot-20b285f6301b51c67ab734fe36123fa8da4a6021.zip |
Add README.md files to the secureboot component
This commit adds a top-level README.md file to the secureboot
component that then calls into new README.md files in the different
sub-directories.
Change-Id: I7460a0e591232c2f8387321b0251ac3f62a1c76e
Reviewed-on: http://rchgit01.rchland.ibm.com/gerrit1/89025
Reviewed-by: Ilya Smirnov <ismirno@us.ibm.com>
Reviewed-by: Nicholas E Bofferding <bofferdn@us.ibm.com>
Reviewed-by: Christopher J Engel <cjengel@us.ibm.com>
Tested-by: Jenkins Server <pfd-jenkins+hostboot@us.ibm.com>
Tested-by: Jenkins OP Build CI <op-jenkins+hostboot@us.ibm.com>
Tested-by: Jenkins OP HW <op-hw-jenkins+hostboot@us.ibm.com>
Tested-by: FSP CI Jenkins <fsp-CI-jenkins+hostboot@us.ibm.com>
Reviewed-by: Daniel M Crowell <dcrowell@us.ibm.com>
Diffstat (limited to 'src/usr/secureboot/node_comm')
-rw-r--r-- | src/usr/secureboot/node_comm/README.md | 97 |
1 files changed, 97 insertions, 0 deletions
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 + |