Updating TPM contributor docs. (#31043)

Fixes #30477

docs/Contributing/product-groups/orchestration/tpm-backed-http-signing.md

@@ -1,17 +1,17 @@
-# TPM-backed HTTP signing for fleetd requests
-
-> **⚠️ Proof of Concept**: This is currently a Proof of Concept (POC) implementation in the `victor/29935-tpm-agent` branch. Additional features and refinements are currently being added.
+# TPM-backed HTTP message signing for fleetd requests
 
 ## Overview
 
-TPM-backed HTTP signing is a security feature that uses the device’s TPM 2.0 (Trusted Platform Module) hardware to securely generate and store cryptographic keys for signing HTTP requests. By ensuring that private keys never leave the TPM's secure boundary, this feature provides hardware-backed assurance that requests to the Fleet server originate from the same physical device that initially enrolled.
+TPM-backed HTTP message signing is a security feature that uses the device’s TPM 2.0 (Trusted Platform Module) hardware to securely generate and store cryptographic keys for signing HTTP requests. By ensuring that private keys never leave the TPM's secure boundary, this feature provides hardware-backed assurance that requests to the Fleet server originate from the same physical device that initially enrolled.
 
 A **device identity certificate** is an X.509 certificate whose private key is bound to the TPM, enabling cryptographic proof of device identity.
 
 This feature includes:
 
 * **Device identity certificate enrollment** via SCEP (Simple Certificate Enrollment Protocol)
+  * **Rate limiting** for certificate enrollment to prevent abuse
 * **HTTP request signing** using TPM-protected keys
+  * **Server-side signature verification** with certificate validation
 
 Together, these mechanisms establish a strong trust foundation for authenticated communication between `fleetd` and the Fleet server.
 
@@ -34,7 +34,7 @@ Together, these mechanisms establish a strong trust foundation for authenticated
 
 ### Components
 
-The TPM-backed HTTP signing feature consists of several key components:
+The TPM-backed HTTP message signing feature consists of several key components:
 
 #### orbit components
 
@@ -43,18 +43,20 @@ fleetd is the Fleet agent that includes orbit (the main agent process), osquery,
 1. **Secure hardware interface** - Hardware-agnostic Go abstraction for TPM (and, in the future, Apple's Secure Enclave)
 2. **TPM 2.0 implementation** - Linux-specific TPM 2.0 integration with automatic ECC curve selection
 3. **SCEP client** - Certificate enrollment client for obtaining device identity certificates
-4. **HTTP signing proxy** - Proxy component that intercepts osquery traffic and adds HTTP signature headers
-5. **HTTP signing integration** - Direct HTTP signature support for orbit's own communications
+4. **HTTP message signing proxy** - Proxy component that intercepts osquery traffic and adds HTTP signature headers
+5. **HTTP message signing integration** - Direct HTTP signature support for orbit's own communications
 
 #### Server components
 1. **SCEP server interface** - Certificate Authority (CA) with dedicated keys for issuing device identity certificates
+   * **Rate limiting** - Configurable cooldown periods to prevent certificate enrollment abuse
+   * **Certificate management** - Automatic certificate lifecycle management including revocation and cleanup
 2. **HTTP signature verification** - Server-side verification of TPM-signed HTTP requests and associated certificates
 
 ### Architecture diagrams
 
 ```mermaid
 ---
-title: TPM-backed HTTP signing (high level)
+title: TPM-backed HTTP message signing (high level)
 ---
 flowchart TD
     subgraph Host
@@ -84,7 +86,7 @@ flowchart TD
 
 ```mermaid
 ---
-title: TPM-backed HTTP signing
+title: TPM-backed HTTP message signing
 ---
 sequenceDiagram
     autonumber
@@ -152,7 +154,7 @@ Filename used is `host_identity_tpm.pem`
 
 ### Overview
 
-The SCEP (Simple Certificate Enrollment Protocol) client enables fleetd to obtain device identity certificates from a Certificate Authority. The certificates are used to establish device identity and can be used in conjunction with HTTP signing for enhanced authentication.
+The SCEP (Simple Certificate Enrollment Protocol) client enables fleetd to obtain device identity certificates from a Certificate Authority. The certificates are used to establish device identity and can be used in conjunction with HTTP message signing for enhanced authentication.
 
 ### Certificate enrollment process
 
@@ -163,9 +165,10 @@ The SCEP enrollment process follows these steps:
 3. **CSR Creation**: Generate a Certificate Signing Request using the TPM key
 4. **Temporary RSA Key**: Create a temporary RSA key for SCEP protocol encryption/decryption
 5. **SCEP Request**: Send the CSR to the SCEP server with challenge authentication
-  * challenge is the enrollment secret
-6. **Certificate Retrieval**: Decrypt and parse the issued certificate
-7. **Certificate Storage**: Save the certificate as `host_identity.crt` in the specified directory
+   * challenge is the enrollment secret
+6. **Rate Limit Check**: Server validates that the host is not requesting certificates too frequently
+7. **Certificate Retrieval**: Decrypt and parse the issued certificate
+8. **Certificate Storage**: Save the certificate as `host_identity.crt`
 
 #### Key usage separation
 
@@ -184,7 +187,7 @@ This separation is necessary because:
 
 ### Architecture overview
 
-The TPM-backed HTTP signing operates at two levels within fleetd:
+The TPM-backed HTTP message signing operates at two levels within fleetd:
 
 1. **Direct Integration**: orbit's own HTTP communications are signed directly using TPM keys
 2. **Proxy Integration**: A proxy component intercepts osquery traffic and adds HTTP signature headers
@@ -193,6 +196,19 @@ This proxy approach allows osquery (which doesn't natively support HTTP signatur
 
 The TPM implementation produces RFC 9421-compatible ECDSA signatures.
 
+### Implementation details
+
+The HTTP message signing implementation uses a `signerWrapper` pattern that wraps HTTP clients to automatically sign requests:
+
+```go
+// signerWrapper wraps an HTTP client to add signing capabilities
+signerWrapper := func(client *http.Client) *http.Client {
+    return httpsig.NewHTTPClient(client, signer, nil)
+}
+```
+
+This approach allows existing HTTP client code to be enhanced with signing capabilities without requiring extensive modifications to the codebase.
+
 ### HTTP signature fields
 
 Both direct and proxy signing use the same HTTP signature fields:
@@ -206,7 +222,7 @@ Both direct and proxy signing use the same HTTP signature fields:
 > **Note**: We did not include the scheme (e.g., http, https) as part of the signature to prevent potential hard-to-debug issues with proxies and HTTP forwarding. We did not include Content-Type header in the signature because not all requests have this header.
 
 Additional metadata included:
-- **`keyid`**: Identifier for the signing key, which maps to identity certificate's serial number
+- **`keyid`**: Identifier for the signing key, which maps to identity certificate's serial number in uppercase hexadecimal format
 - **`created`**: Timestamp of signature creation
 - **`nonce`**: Random value for replay protection
 
@@ -242,44 +258,99 @@ The `created` and `nonce` fields can be used in the future to prevent replay att
 - **fleetd proxy → TPM**: Proxy uses TPM to sign the intercepted requests
 - **fleetd proxy → Fleet Server**: Proxy forwards signed requests to the server
 
+### Fleet desktop authentication
+
+Fleet desktop (the Fleet UI that is shown in the browser) uses a token-based authentication approach that integrates with TPM-backed signing:
+
+1. **Token retrieval**: Fleet Desktop retrieves an authentication token from the Fleet server using an HTTP-signed endpoint
+2. **TPM-backed security**: The token retrieval request is signed using the TPM-backed key, ensuring the token is only issued to the authenticated device
+3. **Token validity**: The token is valid for 1 hour
+4. **API access**: Fleet Desktop uses this token to access `/fleet/device` API endpoints
+
 ## Configuration
 
 ### Client configuration
 
-Enable TPM-backed HTTP signing when packaging or running fleetd:
+Enable TPM-backed HTTP message signing when packaging or running fleetd:
 
 ```bash
 # Package with TPM signing enabled
-fleetctl package --fleet-managed-client-certificate ...
+fleetctl package --fleet-managed-host-identity-certificate ...
 
 # Run orbit with TPM signing enabled
-orbit --fleet-managed-client-certificate ...
+orbit --fleet-managed-host-identity-certificate ...
 ```
 
 ### Server configuration
 
-No additional server configuration is required. The SCEP endpoint is automatically available on Fleet servers with:
+The SCEP endpoint is automatically available on Fleet servers with:
 - **Premium license**
 - **Configured server private key**
 
-The server automatically verifies that:
+#### HTTP message signature enforcement
+
+To require HTTP message signatures for host identity endpoints:
+
+```yaml
+auth:
+  require_http_message_signature: true  # Default: false
+```
+
+When `require_http_message_signature` is enabled:
+- Orbit and osquery requests will require valid HTTP message signatures
+- Hosts without valid signatures will be rejected
+- This allows organizations to enforce TPM-backed authentication for enhanced security
+
+The server always verifies that:
 - Requests with HTTP message signatures match the certificate public key and the host node key
-- Requests without HTTP message signatures do not have associated host identity certificates
+- When the above switch is disabled, requests without HTTP message signatures from hosts **without certificates** are allowed
+- When the above switch is enabled, all requests to protected server endpoints must have valid signatures
+
+#### Rate limiting configuration
+
+Certificate enrollment rate limiting is configurable through the Fleet server configuration, using the same setting as for host enrollment rate limiting:
+
+```yaml
+osquery:
+  enroll_cooldown: 5m
+```
+
+When rate limiting is enabled:
+- Hosts requesting certificates too frequently receive HTTP 429 (Too Many Requests) responses
+- Rate limiting applies per host based on the certificate Common Name (CN)
+- Different hosts are not affected by each other's rate limits
+- Rate limiting uses the same configuration as host enrollment cooldown
+
+### Load testing configuration
+
+For load testing TPM-backed HTTP message signing without actual TPM hardware, use the `osquery-perf` tool with the following flag (other flags not shown):
+
+```bash
+# Run with 10% of hosts using HTTP signatures (default)
+go run agent.go
+
+# Run with 30% of hosts using HTTP signatures
+go run agent.go --http_message_signature_prob 0.3
+
+# Run with all hosts using HTTP signatures
+go run agent.go --http_message_signature_prob 1.0
+```
+
+The `--http_message_signature_prob` flag controls the probability (0.0 to 1.0) that each simulated host will use HTTP message signatures. This allows testing Fleet's HTTP message signing feature at scale without requiring actual TPM hardware on load testing machines.
 
 ## Future enhancements
 
-As this an initial implementation, future features may include:
+Additional features that may be implemented in future releases:
 
-1. **One-time enrollment secret**: This provides additional security to make sure an unauthorized device cannot get an identity certificate and enroll in Fleet.
-2. **Key Rotation/Renewal**: Automatic key rotation policies and certificate renewal
-3. **Rate limits**: Limit the rate/number of certificates issues for the same host. This guards against agent issues.
-4. **Fleet server visibility**: Allow IT admin to see which hosts have host identity certificates. For example, we can add a field to `orbit_info` table and IT admin could set up a policy to make sure all hosts have certificates.
-5. **Windows Support**: TPM support for Windows platforms using TBS (TPM Base Services)
-6. **Apple Secure Enclave**: Integration with Apple's Secure Enclave for macOS devices
-7. **Multiple Key Support**: Support for multiple signing keys and certificates, like a separate key for WiFi/VPN.
-8. **Hardware Attestation**: TPM-based device attestation and platform integrity
-9. **SCEP Extensions**: Support for additional SCEP features and external CA integrations
-10. **ACME**: Use ACME protocol instead of SCEP to get a certificate.
+1. **Key Rotation/Renewal**: Automatic key rotation policies and certificate renewal
+2. **One-time enrollment secret**: This provides additional security to make sure an unauthorized device cannot get an identity certificate and enroll in Fleet.
+3. **Windows Support**: TPM support for Windows platforms using TBS (TPM Base Services)
+4. **Apple Secure Enclave**: Integration with Apple's Secure Enclave for macOS devices
+5. **Fleet server visibility**: Allow IT admin to see which hosts have host identity certificates. For example, we can add a field to `orbit_info` table and IT admin could set up a policy to make sure all hosts have certificates.
+6. **Multiple Key Support**: Support for multiple signing keys and certificates, like a separate key for WiFi/VPN.
+7. **Hardware Attestation**: TPM-based device attestation and platform integrity
+8. **SCEP Extensions**: Support for additional SCEP features and external CA integrations
+9. **ACME**: Use ACME protocol instead of SCEP to get a certificate.
 
 ## Troubleshooting
 
@@ -310,6 +381,12 @@ As this an initial implementation, future features may include:
 
 3. **Certificate enrollment failures**
    - Review SCEP server logs for rejection reasons
+   - Check if rate limiting is causing HTTP 429 responses
+
+4. **Rate limiting issues**
+   - Check if the host is requesting certificates too frequently
+   - Verify the configured cooldown period in server configuration
+   - Monitor for HTTP 429 responses indicating rate limiting
 
 ### General debugging