Intro: Describe encrypted sessions

Intro/README.md

@@ -606,6 +606,9 @@ other state.  TPM commands may check that an authorization session's
 state satisfies the requirements for use of the argument objects passed
 to the commands.
 
+> NOTE: Every command input parameter that is a handle that requires
+> authorization must have its own session associated with it.
+
 ### Authorization Session State
 
 Authorization sessions have a number of state attributes.  Some of these
@@ -688,13 +691,89 @@ ways.  These state attributes are:
 
 ### Encryption Sessions
 
-> Work in progress.
-
 Sessions can also be used for encrypting TPM command arguments and
 results.  This can be useful when one does not trust the path to the
 TPM, such as when the TPM is remote.
 
-> TODO: Discuss key exchange options, etc.
+Only the first input parameter of a TPM command will be encrypted, and
+only the first output parameter of a TPM command will be encrypted, and
+that only if when that first parameter is of type `TPM2B`.  Those first
+`TPM2B` type command input and/or output parameters will be encrypted
+with a symmetrict AES key derived from a secret key established via RSA
+key transport or ECDH key agreement.
+
+> Encryption sessions are useful for when the path to a TPM is not
+> trused, such as when a TPM is a remote TPM, or when otherwise the path
+> to the TPM is not trusted.
+
+### Key Exchange for Encryption Sessions
+
+> Encryption sessions are useful for when the path to a TPM is not
+> trused, such as when a TPM is a remote TPM, or when otherwise the path
+> to the TPM is not trusted.  This section talks about key exchange for
+> such situations.
+
+The symmetric keys used for TPM command encryption are exchanged at
+session creation time.
+
+Keys can be provided by one of either RSA key transport or ECC key
+agreement, and/or the secret `authValue` of a loaded entity.
+
+Sessions are created with
+[`TPM2_StartAuthSession()`](/TPM-Commands/TPM2_StartAuthSession.md),
+which has serveral _optional_ input and output parameters related to
+session encryption.  In particular it provides ways to create a session
+key for command parameter encryption:
+
+ - RSA key transport
+
+   The caller can encrypt a secret to a public key for which the TPM has
+   loaded the private key as identified by the `tpmKey` input parameter
+   of [`TPM2_StartAuthSession()`].
+
+ - ECDH key agreement
+
+   The caller can generate an ephemeral ECDH key and use it with the
+   public key of the ECDH key object identified by the `tpmKey` input
+   parameter of [`TPM2_StartAuthSession()`].  The TPM will use the
+   private key of the object identified by the `tpmKey` input parameter
+   and the ephemeral public key sent by the caller in the
+   `encryptedSalt` input parameter.
+
+ - use the `authHash` of the entity identified by the `bind` input
+   parameter
+
+The caller computes the same session key as the TPM.
+
+To authenticate the TPM and prevent active attacks, the caller of
+`TPM2_StartAuthSession()` should use an `EK` as the `tpmKey` and its
+`EKpub` to locally compute the session key.  Alternatively the caller
+can use a non-`EK` key object created over an earlier encrypted session
+that authenticated the target TPM.
+
+> A non-null `bind` parameter can be used to create a "bound" session
+> that can be used to satisfy HMAC-based authorization for specific
+> objects.  We will not cover this in detail here.
+
+### HMAC Sessions
+
+An HMAC session proves the caller knows the `authValue` secret of some
+entity.  This functions a lot like a password, with the `authValue`
+used to compute HMACs that prove possession, but with the `authValue`
+generally being large and randomly generated, thus much stronger than a
+password.
+
+Typically the `authValue` of some entity should be sent encrypted to the
+TPM when creating an entity, with [the encrypted session being keyed via
+RSA key transport or ECDH](#Key-Exchange-for-Encryption-Sessions).  This
+way an `authValue`, though a simple, password-like binary string, can be
+strong and secure due to being large, randomly chosen and sent over
+an encrypted session.
+
+### Password Sessions
+
+> WIP [Say something about passwords and password sessions, besides
+> "don't use them" and "support remains mostly for TPM 1.2 reasons".]
 
 ## Restricted Cryptographic Keys
 

TPM-Commands/TPM2_StartAuthSession.md

@@ -0,0 +1,151 @@
+# `TPM2_StartAuthSession()`
+
+This command starts a session that can be used for authorization and/or
+encryption.
+
+## Inputs
+
+ - `TPMI_DH_OBJECT+ tpmKey`
+
+   This optional _input_ parameter specifies the handle of a loaded RSA
+   decryption key or of a loaded ECDH key.
+
+ - `TPMI_DH_ENTITY+ bind`
+
+   This parameter, if not null, references a loaded entity whose
+   `authValue` will be used in the session key computation.
+
+ - `TPM2B_NONCE nonceCaller`
+
+   This is a nonce chosen by the caller.
+
+ - `TPM2B_ENCRYPTED_SECRET encryptedSalt`
+
+   This optional _input_ parameter must be present if `tpmKey` is
+   present.
+
+   If `tpmKey` is an RSA decryption key then `encryptedSalt` must be an
+   RSA OEAP ciphertext that will be decrypted with the `tpmKey`.  The
+   plaintext will be used to derive symmetric AES-CFB encryption keys.
+
+   If `tpmKey` is an ECDH key, then `encryptedSalt` must be a public key
+   that will be used to generate a shared secret key from which
+   symmetric AES-CFB encryption keys will be derived.
+
+ - `TPM_SE sessionType`
+ - `TPMT_SYM_DEF+ symmetric`
+ - `TPMI_ALG_HASH authHash`
+
+   A hash algorithm for the key derivation function.
+
+## Outputs (success case)
+
+ - `TPMI_SH_AUTH_SESSION sessionHandle`
+ - `TPM2B_NONCE nonceTPM`
+
+   This is an _output_ parameter that is generated by the TPM, and it is
+   a nonce that is used for key derivation.
+
+## Session Types
+
+The `sessionType` input parameter must be one of:
+
+ - `TPM_SE_HMAC`
+ - `TPM_SE_POLICY`
+ - `TPM_SE_TRIAL`
+
+### HMAC Sessions
+
+If the session is to be an HMAC session authenticating knowledge of some
+entity's `authValue`, then the `bind` argument must be provided.
+
+### Authorization Sessions
+
+For policy sessions, the caller should now call one or more
+`TPM2_Policy*()` commands to execute the policy identified by the
+`authPolicy` value of the entity to be accessed via this session.
+
+### Trial Policies
+
+For trial sessions, the caller should now call one or more
+`TPM2_Policy*()` commands as will be used in future actual policy
+sessions, then extract the `policyDigest` of the
+session after the last policy command -- that will be a value
+suitablefor use as an `authPolicy` value for TPM entities.
+
+### Encryption Sessions
+
+> All sessions can be used for encryption that were created with either
+> or both of the `bind` input parameter and the pair of input parameters
+> `tpmKey` and `encryptedSalt` set.
+
+> Encryption sessions are useful for when the path to a TPM is not
+> trused, such as when a TPM is a remote TPM, or when otherwise the path
+> to the TPM is not trusted.  This section talks about key exchange for
+> such situations.
+
+For encryption sessions the `symmetric` parameter should also be set.
+
+Encryption sessions can have a session key derived from either or both
+of the `authValue` of the `bind` entity or the key exchange represented
+by the `tpmKey` and `encryptedSalt` inputs.  The `nonceCaller` input and
+the `nonceTPM` output will also salt the key derivation.
+
+The symmetric keys used for TPM command encryption are set at session
+creation time.
+
+Session keys are derived from the `tpmKey` and `encryptedSalt` inputs
+(if provided) and the `authValue` of a loaded entity referred to by
+`bind` (if provided), along with the nonces and other things.
+
+The `tpmKey` and `encryptedSalt` inputs can inject a secret either via
+RSA key transport or elliptic curve Diffie-Hellman (ECDH).
+
+The key will be derived as follows:
+
+ - if `tpmKey` and `encryptedSalt` are provided, then the key is
+   recovered (RSA case) or computed (ECDH case)
+
+   In the RSA case the `encryptedSalt` is the ciphertext resulting from
+   RSA PKCS#2 (OEAP) encryption to the public key of the object referred
+   to by `tpmKey`.  The TPM will decrypt the `encryptedSalt` to recover
+   the secret.
+
+   In the ECDH case the `encryptedSalt` is an ephemeral public key, and
+   the secret will be the ECDH shared secret constructed from that key
+   and the private part of the `tpmKey`.
+
+ - then the internal `KDFa()` function will invoked as follows:
+
+   ```
+   sessionKey := KDFa(authHash,
+                      (bind.authValue || tmpKey.get(encryptedSalt)),
+                      "ATH",
+                      nonceTPM,
+                      nonceCaller,
+                      authHash.digestSize)
+   ```
+
+   where:
+
+    - `bind.authValue` is the `authValue` of the `bind` entity (if
+      provided)
+
+    - `tmpKey.get(encryptedSalt)` is the result of RSA decryption of
+      `encryptedSalt` if `tpmKey` is an RSA key, or the result of ECDH
+      key agreement between the private part of `tpmKey` and the public
+      ECDH key in `encryptedSalt` if `tpmKey` is an ECDH key
+
+To avoid active attacks, one would use the EK as the `tpmKey` input
+parameter of `TPM2_StartAuthSession()`.  Or one could use a `tpmKey`
+input created with, e.g., `TPM2_Create()` over another encrypted session
+that itself used the EK as its `tpmKey` input.
+
+> A non-null `bind` parameter can be used to create a "bound" session
+> that can be used to satisfy HMAC-based authorization for specific
+> objects.  We will not cover this in detail here.
+
+## References
+
+ - [TCG TPM Library part 1: Architecture, sections 18.6, 19, and 21](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part1_Architecture.pdf)
+ - [TCG TPM Library part 3: Commands, section 11.1](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf)