osresearch · nicowilliams · Jul 31, 2021 · Jul 26, 2021 · Jul 28, 2021 · Jul 29, 2021
diff --git a/Makefile b/Makefile
@@ -307,8 +307,10 @@ shellcheck:
  sbin/tpm2-recv \
  sbin/tpm2-policy \
  initramfs/*/* \
+ rbin/* \
+ tests/test-enroll.sh \
  ; do \
- shellcheck $$file functions.sh ; \
+ shellcheck -x $$file functions.sh ; \
  done
 
 # Fetch several of the TPM certs and make them usable

diff --git a/docs/attest-enroll.md b/docs/attest-enroll.md
@@ -93,14 +93,14 @@ Decryption is implemented by [`sbin/tpm2-recv`](/sbin/tpm2-recv).
 
 Two methods are possible for encryption to a target TPM's `EKpub`:
 
- - the "EK" method (our name for it)
+ - the "WK" method (our name for it)
  - the "TK" method (our name for it)
 
 Both methods support setting a policy on the ciphertext such that any
 application using the target's TPM to decrypt it must first execute and
 satisfy that policy.
 
-The "EK" method uses `TPM2_MakeCredential()` via tpm2-tools' `tpm2
+The "WK" method uses `TPM2_MakeCredential()` via tpm2-tools' `tpm2
 makecredential` command, using the `none` TCTI (i.e., implemented in
 software). The target's `EKpub` is used as the `handle` input parameter
 to `TPM2_MakeCredential()`. A well-known key (`WK`), and the desired policy

diff --git a/docs/images/attestation.png b/docs/images/attestation.png
diff --git a/docs/images/attestation.puml b/docs/images/attestation.puml
@@ -0,0 +1,28 @@
+@startuml
+participant TPM as T
+participant Client as C
+participant Server as S
+title Safeboot attestation protocol
+activate C
+C --> T: TPM2_Quote(AK, set-of-all-PCRs,\n\t\t timestamp = gettimeofday())
+activate T
+T --> C: quote = \n Signed_AK({hash-of-PCRs,\n\t\t misc, timestamp})
+deactivate T
+C -> S: HTTP POST w/ tarball as req-body:\n {EKpub, [EKcert], AKpub,\n PCRs, eventlog, timestamp,\n quote}
+deactivate C
+|||
+activate S
+S -> C: check that timestamp is recent;\ndata = Lookup(EKpub);\n\nif EKcert\n\tValidate(EKcert);\nelse if EKcert_required\n\tfail();\n\nvalidate(PCRs, eventlog);\nvalidate(quote);\n\nsession_key = genkey();\nstuff = Encrypt(session_key,\n\t\t\t tarball(data.secrets))\n\n/* Software, not TPM: */\n(credentialBlob, secret) = \n TPM2_MakeCredential(EKpub, AKpub,\n\t\t\t\t session_key);\nPOST response body:\n tarball(credentialBlob, secret, stuff)
+note over S
+TPM2_MakeCredential() is
+a software operation
+end note
+deactivate S
+activate C
+C --> T: TPM2_ActivateCredential(AKhandle,\n\t\t\t\t\tEKhandle,\n\t\t\t\t\tcredentialBlob,\n\t\t\t\t\tsecret);
+activate T
+T --> C: certInfo
+deactivate T
+C -> C: session_key = certInfo;\nsecrets = Decrypt(session_key, stuff);\nvalidate_signatures(secrets);
+deactivate C
+@enduml
diff --git a/docs/images/enrollment.png b/docs/images/enrollment.png
diff --git a/docs/images/enrollment.puml b/docs/images/enrollment.puml
@@ -0,0 +1,21 @@
+@startuml
+participant Client as C
+participant EnrollmentServer as S
+title Safeboot off-line enrollment protocol
+activate C
+note right of C
+If a browser, fetch the enrollment page
+end note
+C -> S: GET /
+deactivate C
+activate S
+S -> C: <HTML with forms>
+deactivate S
+activate C
+C -> S: POST /v1/add\n\treq-body: {EKpub, hostname} (as HTML form)
+|||
+deactivate C
+activate S
+S -> C: e = Lookup(EKpub)\ne2 = Lookup(hostname)\nif (e || e2) && e != e2\n\treturn 409; /* conflict */\n\n/* create and/or update enrolled entry */\nif !e\n\te = create(EKpub, hostname);\nif !e\n\treturn 503;\n\n/* create enrolled assets / add missing assets */\nif !add_missing_assets(e)\n\treturn 503;\nreturn 200;
+deactivate S
+@enduml