Use ADRs; GATT flow and FDO DI ADRs

.adr-dir

@@ -0,0 +1 @@
+docs/decisions

docs/decisions/0001-record-architecture-decisions.md

@@ -0,0 +1,35 @@
+# 1. Record architecture decisions
+
+Date: 2025-07-24
+
+## Status
+
+Accepted
+
+## Context
+
+We want to record architectural decisions made in this project independent whether decisions concern the architecture ("architectural decision record"), the code, or other fields.
+
+## Considered Options
+
+- [MADR](https://adr.github.io/madr/) 4.0.0 – The Markdown Architectural Decision Records
+- [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
+- [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements
+- Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
+- Formless – No conventions for file format and structure
+
+## Decision
+
+We will use "MADR 4.0.0", because
+
+- Implicit assumptions should be made explicit.
+  Design documentation is important to enable people understanding the decisions later on.
+  See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
+- MADR allows for structured capturing of any decision.
+- The MADR format is lean and fits our development style.
+- The MADR structure is comprehensible and facilitates usage & maintenance.
+- The MADR project is vivid.
+
+## Consequences
+
+See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).

docs/decisions/0002-gatt-flow.md

@@ -0,0 +1,46 @@
+# 2. GATT flow
+
+Date: 2025-07-24
+
+## Status
+
+Accepted
+
+## Context
+
+Bluetooth LE (BLE) Peripherals typically implement a GATT server, whereas BLE Centrals, such as a mobile phone, typically implement a GATT client to connect to and retrieve values, such as "beats per minute" in a heart rate monitor.
+
+It is more common to find BLE stack implementations that enable a GAP Central and GATT Client for use cases such as connecting and using a BLE keyboard.
+
+Under perfect conditions, it would be desirable to use both GATT Client and GATT Servers because the proposed flows would ideally use both.
+
+The Bluetooth protocol in the UEFI standard does not include interfaces to configure or use a GATT server.  Adding such support will require significant changes including but not limited to:
+
+- Adding services
+- Adding characteristics and handlers/callbacks
+
+Addressing the above gaps would result in a significantly larger upstream pull request into EDK2 because it introduces a new UEFI protocol as opposed to using an existing protocol.  Submitting such a PR would also be introducing a driver that consumes a protocol that is not available in open source.
+
+For these reasons it is strongly desired to use the existing GATT client available in existing implementations.
+
+In terms of functional viability, a test GAP Peripheral + GATT Client (running on Linux) and test GAP Central + GATT Server (mobile phone) were built and tested to confirm technical interoperability and behavior.
+
+## Decision
+
+Reverse the flow and use a GAP Peripheral and GATT Client in UEFI, with a GAP Central and GATT Server implemented in remote clients (e.g. phone, tablet, etc.)
+
+## Consequences
+
+Instead of building reference code, an actual library for mobiles device ecosystems, such as iOS and Android, will likely be required to abstract the Bluetooth service.  Notably this may already be the case because the pre-requisite developer knowledge of both the Bluetooth specification and implementation architecture is much more substantial than more trivial implementations like a REST API.
+
+### Positive
+
+- Decreases the complexity in the UEFI implementation, which is a significant consideration because the tooling and ecosystem is richer for mobile devices than UEFI.
+
+- Potentially smaller UEFI binary size.
+
+### Negative
+
+- Increases the implementation complexity in native app implementations and will likely require additional reference code because this is not the typical flow in the mobile device Bluetooth framework documentation.
+
+- Unable to leverage the Web Bluetooth library, so any remote device implementations will require a native app implementation (e.g. iOS, Android, etc.).

docs/decisions/0003-fdo-di.md

@@ -0,0 +1,60 @@
+# 3. FDO DI
+
+Date: 2025-07-24
+
+## Status
+
+Accepted
+
+## Context
+
+In the context of just-in-time provisioning, FDO Device Initialization (DI) needs to be completed at the time the provisioning occurs as opposed to being completed in a manufacturer environment.  This eliminates supply chain infrastructure and dependencies that would otherwise have to be in place.
+
+This process requires a manufacturer key that is generated and used during DI to create the device certificate chain and it is used for the first FDO voucher extension (assigning a voucher to an Owner key).
+
+In the BLE onboarding flow, the manufacturer key can therefore be generated:
+
+- ephemerally on the device
+- on the handset or tablet
+- in a device management service
+
+The handset or tablet is already within the security scope boundary because it is being used for initial proof of possession of a device.
+
+Considering the choice between a handset or central device management service, for operational security, simplicity, and scalability, the manufacturer key should be generated in the device management service.  For potential offline scenarios, the key could be generated on the handset or tablet.
+
+If the manufacturer key is generated ephemerally on the device:
+
+- it requires an additional data transfer of the voucher over BLE from the device to the management service
+- the device management service will be unable to validate the device certificate chain in the voucher because the key manufacturing is unknown to the device management service
+- the device management servvice must instead trust the chain indirectly based on the trust of the handset providing the voucher
+
+### Security Considerations
+
+The device uses a Trust-on-first-Use model, which means that the handset is in scope for the security model and assumed to be trusted.  More broadly, FDO considers all infrastructure involved in DI to be trusted.
+
+As an intermediary, the handset or tablet intentionally receives and provides **all** data between the device and the device management service.  The following scenarios were considered and illustrate how there are no practical mitigations between two endpoints that have no pre-shared context:
+
+|Mitigation|Description|Gap|
+|--|--|--|
+|Hardware Attestation|The device sends a hardware signed attestation quote and the device management service verifies the quote hierarchy up to the known manufacturer's public root key.|Adversary could use any alternate hardware from that manufacturer as a malicious intermediary.|
+|Web PKI|Using public CA infrastructure, the device management service public identity and nonce is validated by the device against the pool of trusted global Certificate Authorities that are used for TLS.|Global CA pool is not unilaterally trustworthy and is subject to update at a much more frequent interval than typical firmware update life cycles.  Not all device management services may use public CA certificates.|
+
+Additionally, if an ephemeral manufacturer key was generated on the device, the derived voucher would be still transferred to the handset or tablet as a trusted endpoint.
+
+The overall provisioning risk of a man-in-the-middle attack during device initialization does not change whether the manufacturer key is generated internal (ephemerally) or external to the device. Expected mitigations include but are not limited to BLE pairing security, user verification of a presented serial number to that printed on the physical chassis, and TLS certificate pinning.
+
+## Decision
+
+Generate and use the manufacturer key off the device.
+
+## Consequences
+
+### Positive
+
+- Significantly reduces data that needs to be exchanged over BLE because the voucher no longer needs to be transferred
+- Manufacture chain verification can be performed
+- Manufacture key can be managed
+
+### Negative
+
+- Increases key control responsibility to the mobile device and device manager

docs/decisions/templates/template.md

@@ -0,0 +1,23 @@
+# NUMBER. TITLE
+
+Date: DATE
+
+## Status
+
+STATUS
+
+## Context
+
+The issue motivating this decision, and any context that influences or constrains the decision.
+
+## Considered Options
+
+Pros and cons of a few reasonable approaches. This does not need to be comprehensive.
+
+## Decision
+
+The change that we're proposing or have agreed to implement.
+
+## Consequences
+
+What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.