Skip to content

Kmyth Tpm2 Details

Jump to bottom
b-carr edited this page Jul 27, 2020 · 4 revisions

This page is specifically about the TPM 2.0. For TPM 1.2's see here.

Enabling the TPM 2.0

TPM 2.0 Tools (Intel)

  • the tpm2-abrmd binary is used to start the TPM Access Broker (TAB) and Resource Manager (RM) daemon.

  • The tpm2_takeownership binary can be used to set (change) the TPM's owner (storage) and endorsement hierarchy passwords (empty string by default), as well as the lockout authorization value.

TPM 2.0 Resource Manager (Intel)

  • Can be run on either emulator or device.

  • Must be run in root if running on device.

  • Must be in white list group or root to run.

  • To white list a group do the following:

    • In /etc/dbus-1/system.d/tpm2-abrmd.conf add:
          <policy group="[insert name of group here]">
      <allow own="com.intel.tss2.Tabrmd">
      </policy>
    • Then reset connection (e.g., dzdo pkill -HUP dbus-daemon)

TPM 2.0 emulator

Kmyth Tools

kmyth-seal

This tool will kmyth-seal a file using the TPM 2.0. In TPM parlance, 'sealing' typically refers to encrypting the file using a key known only to that TPM (i.e., binding that data to a specific TPM) and imposing system state criteria (i.e., Platform Configuration Register or PCR constraints) on the decryption of that data. While kmyth-seal utilizes the TPM's capability to 'seal' and/or 'bind' under the hood, it references the entire process used to create a .ski file result. This includes:

  • generation and use of a wrapping key to symmetrically encrypt the input data
  • use of the TPM to derive the Kmyth SRK as a primary key
  • use of the TPM to create a Kmyth SK that is sealed to the SRK with an authorization policy
  • use of the TPM to seal the symmetric wrapping key to the SK and an authorization policy
  • compilation of the encrypted secret being protected (e.g., CAPK), TPM sealed storage key, TPM sealed symmetric key, and the symmetric cipher specification into a .ski file to facilitate the ability to later kmyth-unseal it

kmyth-unseal

This tool will kmyth-unseal a file using the TPM 2.0. In TPM parlance, 'unsealing' typically refers to decrypting 'sealed' input data using a key known only to that TPM (i.e., the encrypted input is 'bound' to a specific TPM) while imposing system state criteria (i.e., Platform Configuration Register or PCR constraints) on the ability to decrypt. While kmyth-unseal utilizes the TPM's capability to 'unseal' under the hood, it references the entire process used to recover Kmyth protected secret data (e.g., a CAPK) from a .ski file input. This includes:

  • recovery of data contained in the input .ski file
  • use of the TPM and its Kmyth SRK to recover the Kmyth SK
  • loading the recovered Kmyth SK into the TPM
  • use of the TPM and loaded Kmyth SK to recover the symmetric wrapping key
  • use of the symmetric wrapping key and the cipher specification to recover the 'kmyth-sealed' secret
  • providing the recovered result to the user in the required format (e.g., a file)

kmyth-getkey

  1. Use the kmyth-unseal process to access the Client Authentication Private Key
  2. Use the Client Authentication Private Key to establish a TLS connection with the key server
  3. Clear Client Authentication Private Key from memory within kmyth-getkey
  4. Retrieve the Operational Key from the key server
  5. Close the TLS connection
  6. Output the Operational Key (to file or stdout)
  7. Clear the Operational Key from memory within kmyth-getkey

Programmatic API

Kmyth provides access to the TPM without requiring detailed knowledge of the TPM. There is a programmatic API for Kmyth that exposes the core functionality of the TPM but handles many of the underlying details. These tools use the TPM2 TSS to communicate with the TPM. Below are some examples taken from the source code. Kmyth uses Doxygen to produce more complete code docs when the source is built.

int tpm2_init_connection(TSS2_SYS_CONTEXT ** sapi_ctx)

This function initializes the TPM by creating the required context, and it is needed for any/all calls to the TPM.

There are other tools available for creating objects:

int tpm2_kmyth_create_sk(TSS2_SYS_CONTEXT * sapi_ctx, TPM2_HANDLE srk_handle, TPM2B_AUTH srk_authVal,TPM2B_AUTH sk_authVal,
                         TPML_PCR_SELECTION sk_pcrList,TPM2B_DIGEST sk_authPolicy, TPM2_HANDLE * sk_handle, TPM2B_PRIVATE * sk_private,
                         TPM2B_PUBLIC * sk_public)
int tpm2_kmyth_create_object(TSS2_SYS_CONTEXT * sapi_ctx, SESSION * createObjectAuthSession, TPM2_HANDLE parent_handle, 
                             TPM2B_AUTH parent_auth, TPML_PCR_SELECTION parent_pcrList, TPM2B_SENSITIVE_CREATE object_sensitive, 
                             TPM2B_PUBLIC object_template, TPML_PCR_SELECTION object_pcrSelect, TPM2_HANDLE object_dest_handle, 
                             TPM2B_PRIVATE * object_private, TPM2B_PUBLIC * object_public)

These tools create objects used by the TPM. In the case of these two, they create the storage key and data object to be encrypted, and they handle the details of object creation for the developer.

There are more helper functions, but these are not necessary for a user to learn in order to use the programmatic API. Kmyth ships with a couple key functions that allow a developer to use the TPM in a straightforward fashion.

int tpm2_kmyth_seal(char *input_path,
                    char *output_path,
                    char *auth_string,
                    char *pcrs_string,
                    char *owner_auth_passwd, char *cipher_string)

The tpm2_kmyth_seal function takes in the required information and produces encrypted/sealed data for the user. A developer using this function does not need to implement any TPM-specific code themselves. The function handles the TPM calls internally.

int tpm2_kmyth_unseal(char *input_path,
                      char **default_out_path,
                      char *auth_string,
                      char *owner_auth_passwd,
                      uint8_t ** output_data, size_t *output_size)

The tpm2_kmyth_unseal function handles the TPM calls for the developer as well, parsing the input .ski file and returning the original plaintext data.

File Structure

Clone this wiki locally