Expand on restricted keys; describe more TPM commands

Attestation/README.md

@@ -95,10 +95,10 @@ key) encrypted to the EKpub and then the attestation client demonstrate
 that it was able to decrypt that with the EK.  However, this is not
 _quite_ how attestation protocols work!  Instead of plain asymmetric
 encryption the server will use
-[`TPM2_MakeCredential()`](TPM2_MakeCredential.md), while the attestation
+[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md), while
-client will use
+the attestation client will use
-[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) instead of
+[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md)
-plain asymmetric decryption.
+instead of plain asymmetric decryption.
 
 ## Trusted State Attestation
 
@@ -114,15 +114,15 @@ Typically the attestation protocol will have the client generate a
 signing-only asymmetric public key pair known as the attestation key
 (AK) with which to sign the PCR quote and eventlog.  Binding of the
 EKpub and AKpub will happen via
-[`TPM2_MakeCredential()`](TPM2_MakeCredential.md) /
+[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) /
-[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md).
+[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md).
 
-Note that the [`TPM2_Quote()`](TPM2_Quote.md) function produces a signed
+Note that the [`TPM2_Quote()`](/TPM-Commands/TPM2_Quote.md) function produces a signed
 message -- signed with a TPM-resident AK named by the caller (and to
 which they have access), which would be the AK used in the attestation
 protocol.
 
-The output of [`TPM2_Quote()`](TPM2_Quote.md) might be the only part of
+The output of [`TPM2_Quote()`](/TPM-Commands/TPM2_Quote.md) might be the only part of
 a client's messages to the attestation service that include a signature
 made with the AK, but integrity protection of everything else can be
 implied (e.g., the eventlog and PCR values are used to reconstruct the
@@ -140,14 +140,14 @@ digest of the selected PCRs.  `TPM2_Quote()` signs all of:
 
 ## Binding of Other Keys to EKpub
 
-The semantics of [`TPM2_MakeCredential()`](TPM2_MakeCredential.md) /
+The semantics of [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) /
-[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) make it
+[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md) make it
 possible to bind a TPM-resident object to the TPM's EKpub.
 
-[`TPM2_MakeCredential()`](TPM2_MakeCredential.md) encrypts to the EKpub
+[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) encrypts to the EKpub
 a small secret datum and the name (digest of public part) of the
 TPM-resident object being bound.  The counter-part to this,
-[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md), will decrypt
+[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md), will decrypt
 that and return the secret to the application IFF (if and only if) the
 caller has access to the named object.
 
@@ -195,14 +195,14 @@ Let's start with few observations and security considerations:
    timestamps.
 
  - Replay protection of server to client responses is mostly either not
-   needed or implicitly provided by [`TPM2_MakeCredential()`](TMP2_MakeCredential.md)
+   needed or implicitly provided by [`TPM2_MakeCredential()`](TPM2_MakeCredential.md)
    because `TPM2_MakeCredential()` generates a secret seed that
    randomizes its outputs even when all the inputs are the same across
    multiple calls to it.
 
  - Ultimately the protocol *must* make use of
-   [`TPM2_MakeCredential()`](TMP2_MakeCredential.md) and
+   [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) and
-   [`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) in order to
+   [`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md) in order to
    authenticate a TPM-running host via its TPM's EKpub.
 
  - Privacy protection of client identifiers may be needed, in which case
@@ -288,7 +288,7 @@ protocol:
 ![Protocol Diagram](Protocol-Two-Messages.png)
 
 (In this diagram we show the use of a TPM simulator on the server side
-for implementing [`TPM2_MakeCredential()`](TPM2_MakeCredential.md).)
+for implementing [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md).)
 
 The server will validate that the `timestamp` is near the current time,
 the EKcert (if provided, else the EKpub), the signature using the
@@ -340,7 +340,7 @@ desirable anyways for monitoring and alerting purposes.
 ![Protocol Diagram](Protocol-Three-Messages.png)
 
 (In this diagram we show the use of a TPM simulator on the server side
-for implementing [`TPM2_MakeCredential()`](TPM2_MakeCredential.md).)
+for implementing [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md).)
 
 NOTE well that in this protocol, like single round trip attestation
 protocols using only decrypt-only EKs, it is *essential* that the AKcert

Intro/README.md

@@ -291,16 +291,18 @@ necessarily yields a new name.
 > restricted keys.  Still, it may be useful to illustrate cryptographic
 > object naming with one particularly important use of it.
 
-A pair of functions, `TPM2_MakeCredential()` and
+A pair of functions,
-`TPM2_ActivateCredential()`, illustrate the use of cryptographic object
+[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) and
-naming as a binding or a sort of authorization function.
+[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md),
+illustrate the use of cryptographic object naming as a binding or a sort
+of authorization function.
 
-`TPM2_MakeCredential()` can be used to encrypt a datum (a "credential")
+[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) can be
-to a target TPM such that the target will _only be willing to decrypt
+used to encrypt a datum (a "credential") to a target TPM such that the
-it_ if *and only if* the application calling `TPM2_ActivateCredential()`
+target will _only be willing to decrypt it_ if *and only if* the
-to decrypt that credential has access to some key named by the sender,
+application calling `TPM2_ActivateCredential()` to decrypt that
-and that name is a cryptographic name that the sender can and must
+credential has access to some key named by the sender, and that name is
-compute for itself.
+a cryptographic name that the sender can and must compute for itself.
 
 The semantics of these two functions can be used to defeat a
 cut-and-paste attack in attestation protocols.
@@ -312,21 +314,21 @@ keys, each with zero, one, or more children keys:
 
 ```
                 seed
-                 |
+                /|\
-                 |
+               / | \
-                 v
+              v  v  v
      primary key (asymmetric encryption)
-                 |
+                /|\
-                 |
+               / | \
-                 v
+              v  v  v
        secondary keys (of any kind)
-                 |
+                /|\
-                 |
+               / | \
-                 v
+              v  v  v
                 ...
 ```
 
-Note that every key has a parent or is a primary key.
+Keys that have no parent are primary keys.
 
 There are four built-in hierarchies:
 
@@ -540,21 +542,53 @@ Cryptographic keys can either be unrestricted or restricted.
 
 An unrestricted signing key can be used to sign arbitrary content.
 
+An unrestricted decryption key can be used to decrypt arbitrary
+ciphertexts encrypted to that key's public key.
+
+> NOTE WELL: The endorsement key (EK) is a restricted key.
+
+### Restricted Signing Keys
+
 A restricted signing key can be used to sign only TPM-generated content
 as part of specific TPM restricted signing commands.  Such content
 always begins with a magic byte sequence.  Conversely, the TPM refuses
 to sign externally generated content that starts with that magic byte
-sequence.
+sequence.  See the [`TPM2_Certify()`](/TPM-Commands/TPM2_Certify.md),
+[`TPM2_Quote()`](/TPM-Commands/TPM2_Quote.md), `TPM2_CertifyCreation()`,
+`TPM2_GetSessionAuditDigest()`, and `TPM2_GetCommandAuditDigest()` TPM
+commands.
+
+There is also a notion of signing keys that can only be used to sign
+PKIX certificates using `TPM2_CertifyX509()`.
+
+### Restricted Decryption Keys
+
+> NOTE WELL: The endorsement key (EK) is a restricted key.
 
 A restricted decryption key can only be used to decrypt ciphertexts
 whose plaintexts have a certain structure.  In particular these are used
-for `TPM2_MakeCredential()`/`TPM2_ActivateCredential()` to allow the
+for [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) /
-TPM-using application to get the plaintext if and only if (IFF) the
+[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md)
-plaintext cryptographically names an object that the application has
+to allow the TPM-using application to get the plaintext if and only if
-access to.  This is used to communicate secrets ("credentials") to TPMs.
+(IFF) the plaintext cryptographically names an object that the
+application has access to.  This is used to communicate secrets
+("credentials") to TPMs.
 
-There is also a notion of signing keys that can only be used to sign
+Another operation that a restricted decryption key can perform is
-PKIX certificates.
+[`TPM2_Import()`](/TPM-Commands/TPM2_Import.md), which decrypts a key
+wrapped to the given decrypt-only key and outputs a file that can be
+loaded with [`TPM2_Load()`](/TPM-Commands/TPM2_Load.md).  The wrapped
+key payload given to [`TPM2_Import()`](/TPM-Commands/TPM2_Import.md) too
+has a particular structure and is produced by a remote peer using
+[`TPM2_Duplicate()`](/TPM-Commands/TPM2_Duplicate.md).
+
+To recap, a restricted decryption key can only be used to:
+
+ - "activate credentials" (made with
+   [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md))
+
+ - receive wrapped keys sent by a peer (made with
+   [`TPM2_Duplicate()`](/TPM-Commands/TPM2_Duplicate.md))
 
 ## Attestation
 

TPM-Commands/TPM2_Certify.md

@@ -0,0 +1,21 @@
+# `TPM2_Certify()`
+
+`TPM2_Certify()` signs an assertion that some named object is loaded in
+the TPM.
+
+## Inputs
+
+ - `TPMI_DH_OBJECT objectHandle` (object to be certified)
+ - `TPMI_DH_OBJECT signHandle` (handle for a signing key)
+ - `TPM2B_DATA qualifyingData` (extra data)
+ - `TPMT_SIG_SCHEME inScheme` ("signing scheme to use if the schemefor signHandleis `TPM_ALG_NULL`")
+
+## Outputs (success case)
+
+ - `TPM2B_ATTEST certifyInfo` (what was signed)
+ - `TPMT_SIGNATURE signature` (signature)
+
+## References
+
+ - [TCG TPM Library part 3: Commands, section 18.2](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf)
+

TPM-Commands/TPM2_Duplicate.md

@@ -0,0 +1,25 @@
+# `TPM2_Duplicate()`
+
+`TPM2_Duplicate()` wraps a key, typically encrypting it to a public key
+for a key on a remote TPM.
+
+I.e., this is used to export a wrapped key for some target, typically a
+remote TPM.
+
+## Inputs
+
+ - `TPMI_DH_OBJECT objectHandle` (handle for key to encrypt with)
+ - `TPMI_DH_OBJECT newParentHandle` (optional; handle for key to wrap to -- "Only the  public  area  of newParentHandle is required to be loaded")
+ - `TPM2B_DATA encryptionKeyIn` (optional; symmetric key to encrypt with)
+ - `TPMT_SYM_DEF_OBJECT+ symmetricAlg` ("definition for the symmetric algorithm to be used for the inner wrapper")
+
+## Outputs (success case)
+
+ - `TPM2B_DATA encryptionKeyOut`
+ - `TPM2B_PRIVATE duplicate`
+ - `TPM2B_ENCRYPTED_SECRET outSymSeed`
+
+## References
+
+ - [TCG TPM Library part 3: Commands, section 18.4](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf)
+

TPM-Commands/TPM2_Import.md

@@ -0,0 +1,22 @@
+# `TPM2_Import()`
+
+`TPM2_Import()` reads a wrapped key produced by
+[`TPM2_Duplicate()`](TPM2_Duplicate.md) and outputs a blob that can be
+saved and later loaded with [`TPM2_Load()`](TPM2_Load.md).
+
+## Inputs
+
+ - `TPM2B_DATA encryptionKey` (optional; symmetric key to decrypt with)
+ - `TPM2B_PUBLIC objectPublic`
+ - `TPM2B_PRIVATE duplicate`
+ - `TPM2B_ENCRYPTED_SECRET inSymSeed`
+ - `TPMT_SYM_DEF_OBJECT+ symmetricAlg`
+
+## Outputs (success case)
+
+ - `TPM2B_PRIVATE outPrivate`
+
+## References
+
+ - [TCG TPM Library part 3: Commands, section 13.3](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf)
+

TPM-Commands/TPM2_Load.md

@@ -0,0 +1,19 @@
+# `TPM2_Load()`
+
+`TPM2_Load()` loads a saved key.
+
+## Inputs
+
+ - `TPMI_DH_OBJECT parentHandle`
+ - `TPM2B_PRIVATE inPrivate`
+ - `TPM2B_PUBLIC inPublic`
+
+## Outputs (success case)
+
+ - `TPM_HANDLE objectHandle`
+ - `TPM2B_NAME name`
+
+## References
+
+ - [TCG TPM Library part 3: Commands, section 12.2.2](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf)
+