1 files changed, 147 insertions, 0 deletions
diff --git a/roms/skiboot/libstb/keys/README.md b/roms/skiboot/libstb/keys/README.md
new file mode 100644
index 000000000..f70e6c28d
--- /dev/null
+++ b/roms/skiboot/libstb/keys/README.md
@@ -0,0 +1,147 @@
+# Important Information About Secure and Trusted Boot And Signing Keys
+
+## Background
+
+IBM P8 OpenPOWER systems support a limited set of Secure and Trusted Boot
+functionality.  Secure Boot implements a processor based chain of trust.  The
+chain starts with an implicitly trusted component with other components being
+authenticated and integrity checked before being executed on the host processor
+cores.  At the root of this trust chain is the Host Platform Core Root of Trust
+for Measurement (CRTM).  Immutable Read Only Memory (ROM - fixed in the POWER
+processor chip) verifies the initial firmware load.  That firmware verifies
+cryptographic signatures on all subsequent "to be trusted" firmware that is
+loaded for execution on the P8 cores.  Trusted Boot also makes use of this same
+CRTM by measuring and recording FW images via a Trusted Platform Module (TPM)
+before control is passed on to the next layer in the boot stack.  The CRTM
+design is based on a Public Key Infrastructure (PKI) process to validate the
+firmware images before they are executed.  This process makes use of a set of
+hardware and firmware asymmetric keys.  Multiple organizations will want to
+deliver POWER hardware, digitally signed firmware, signed boot code,
+hypervisors, and operating systems.  Each platform manufacturer wants to
+maintain control over its own code and sign it with its own keys.  A single key
+hash is stored in host processor module SEEPROM representing the anchoring root
+set of hardware keys.  The P8 Trusted Boot supports a key management flow that
+makes use of two kinds of hardware root keys, a wide open, well-known, openly
+published public/private key pair (imprint keys) and a set of production keys
+where the private key is protected by a hardware security module (HSM) internal
+to the manufacturing facility of the key owner.
+
+## Purpose Of Imprint Public/Private Keys
+
+It is critical to note that the imprint keys are not to be used for production.
+These are strictly for manufacturing and development level support given the
+open nature of the private part of the Hardware keys.  This allows developers
+and testers to sign images and create builds for Secure and Trusted Boot
+development lab testing.  Systems must be transitioned to production level
+keys for customer environments.
+
+## Manufacturer Key Management Role
+
+If a system is shipped from the System Manufacturer with imprint keys installed
+rather than production level hardware keys, the system must be viewed as running
+with a set of well-known default keys and vulnerable to exploitation.  The
+System Access Administrator must work with the System Manufacturer to insure
+that a key transition process is utilized once a hardware based chain of trust
+is to be enabled as part of Secure or Trusted Boot functionality.
+
+## Intentional Public Release Of Imprint Public/Private Keys
+
+All public and private keys in this directory are being intentionally released
+to enable the developer community to sign code images.  For true security, a
+different set of production signing keys should be used, and the private
+production signing key should be carefully guarded.  Currently, we do not yet
+support production key signing, only development signing.
+
+### Imprint Private Keys
+
+#### Hardware Private Keys
+
+The following files contain the Imprint private keys, in PEM format:
+
+hw_key_a.key
+hw_key_b.key
+hw_key_c.key
+
+#### Software Private Keys
+
+The project does not contain any Software keys.  The sample scripts reuse the
+Hardware keys where input is required for the Software keys.  To generate your
+own software keys use the openssl "ecparam" command.  The following commands
+will generate private software keys P, Q and R:
+
+$ openssl ecparam -genkey -outform pem -noout -name secp521r1 -out sw_key_p.key
+$ openssl ecparam -genkey -outform pem -noout -name secp521r1 -out sw_key_q.key
+$ openssl ecparam -genkey -outform pem -noout -name secp521r1 -out sw_key_r.key
+
+OpenPOWER secure boot supports three keys for Hardware (HW) key signing and (up
+to) three keys for Software (SW) key signing,  This permits a "separation of
+duties" in the firmware signing process, if such a separation is desired.  All
+three HW keys are required, but the SW keys allow for the use of one, two or
+three keys.  A signature is required (i.e. must be present in the container) by
+*all three* firmare keys, and by every (1-3) SW key in use, to create a
+container that will boot with secure mode on.  If a separation of duties is not
+required, the signer may use the same key for all three required HW keys, and
+for the (1-3) required SW keys.  The container will boot as long as all required
+signatures are present.
+
+#### Hardware and Software Public Keys
+
+The public keys can be easily extracted from the private keys.  Use the openssl
+"pkey" command, for example:
+
+$ openssl pkey -pubout -inform pem -outform pem -in sw_key_p.key -out sw_key_p.pub
+
+To build and sign a container locally, the public keys are not required.  The
+signing tool will automatically extract the public key from the private key (for
+inclusion in the container) and will use the private key to create the required
+signatures.
+
+The recommended process for production keys is to not have the private keys
+present on thy system used to build firmware.  In this mode you want to create
+the signatures independently from the op-build process.  Create your private HW
+and SW keys as described above.  Protect the private portion of the key (the
+private key).  Add the public portion of the key (the public key) to ./keys
+directory.  The signing tool will use the public key to populate the container.
+
+In this mode of operation you must sign the Prefix header and Software header
+with the HW and SW keys, respectively.  TODO: Instructions to follow.
+
+#### Hardware Keys Hash
+
+As mentioned above, a single key hash is stored in host processor module SEEPROM
+representing the anchoring root set of HW keys.  This is a 64 byte, SHA512 hash
+of the three HW keys.  On a running OpenPOWER machine this hash may be read from
+an entry in the device tree:
+
+# cat /proc/device-tree/ibm,secureboot/hw-key-hash | xxd -p
+40d487ff7380ed6ad54775d5795fea0de2f541fea9db06b8466a42a320e6
+5f75b48665460017d907515dc2a5f9fc50954d6ee0c9b67d219dfb708535
+1d01d6d1
+
+Note this file is readable both from the target OS and the petitboot shell
+environment.
+
+OpenPOWER secure boot protects the containerized firmware by comparing this hash
+to the hash of the HW public keys in the container (as well as verifying the
+signatures, of course).  If the hashes don't match, the machine won't boot.  For
+this reason you might want to check that the HW keys hash will be correct in
+container you are building.
+
+To check the hash of your HW keys, run the "create-container" tool from the
+sb-signing-utils project.  This command will create no container, but will
+display the SHA512 hash of the input keys:
+
+$ create-container -v -w0 -a /tmp/keys/hw_key_a.key \
+                          -b /tmp/keys/hw_key_b.key \
+                          -c /tmp/keys/hw_key_c.key \
+                          --payload /dev/zero --imagefile /dev/null \
+                          | grep "HW keys hash"
+
+HW keys hash = 40d487ff7380ed6a...
+
+Note this command will work with either public or private keys as input.  The
+tool will also display the hash during normal container creation, when the
+program is run in verbose mode.
+
+To check the hash of the HW keys in an existing container, run the
+"print-container" tool: TODO