TPM2 Sample Provisioning Files 
May 11, 2015
This directory contains:
- sample TPM2 definition files
- sample provisioning scripts
This document describes how to use the contents of this directory and how to run the provisioning scripts.

These files were produced for use with the Tpm2ProvTool.efi and includes batch script files (*.nsh) intended to run in the UEFI shell. To use these files: 
-	copy the files to a USB drive
-	insert the drive in the target platform
-	execute map r
-	make the USB drive the active directory (e.g., FS0:)
-	change to the directory that contains these files
-	execute the scripts as described below 

================ NOTE ================
The set of allowed NV Index handles have changed and thus there are now old definitions using the original NV Index handles and new definitions using the new NV Index handles. In addition there are Default definitions and development Examples. Some (client) platforms still require the older original NV indexes. Thus you will need to know the platform requirements before selecting a set. Note even though it is possible to provision a TPM with both original and new NV Indexes, that does waste valuable TPM resources (i.e., the unused set consumes NV RAM. 
===========================================================================

There are 4 sets of sample definitions
- New Default Provisioning (Default*.*)              - see warning below
- Original Default Provisioning (OriginalDefault*.*) - see warning below
- New Development examples (Example*.*)
- Original Development examples (Original*.*)
Warning: The Default files (original and new) are for those who just don't have the time or the inclination to create their own private authPolicies. 
Their use is not recommended because once you provision a TPM with the default NV Indexes, those indexes cannot be deleted nor will you be able to change the NV data of the PS index.

On the other hand, the original and new development definitions were produced as examples of how the NV Indexes can be created to give you the ability to modify the PS data and to delete the NV Indexes if the need arises (such as for platform refurbishing).
Because the "secret value" used for the example definitions is not secure, example definitions should never be used on production platforms that will 
be shipped to a customer. At a minimum, you should modify them to use your own "secret value". 

Intel provides tools and a TPM2 Provisioning Tutorial that will walk you through the steps of creating your own custom definitions.

Definition (def) files use the following naming convention:
    <fileNamePrefix><purpose><alg>.<ext> 
      Where:
      <ext> is the file extension that indicates the file type
        .iDef  NV Index definition 
        .sDef  Session definition
        .pDef  Policy Assertion
        .hash  a hash digest
        .auth  an authValue
        .pSet  instructs the tool to set hierarchy authPolicy 
        .nsh  UEFI batch file
        .pol  Intel TXT policy for PS NV Data 
      <alg> is a supported hash algorithm such as SHA1, SHA256, SHA384, SHA512, SM3 
      <purpose> indicates the use of the definition
      <fileNamePrefix> is an arbitrary file name prefix that identifies the 
	    project or platform (e.g., MyFirst; Example; Purley) 
	    The sample files use the following File Name Prefixes 
              Default OriginalDefault "Example" and Original 
          Files that are not platform specific do not have a prefix 
            - you should not modify those files.

  In order to use the sample scripts with your own definitions, modify the sample definitions and rename the definitions using your own file name prefix.
  For example modify ExamplePsSha256.idef and save as PurleyPsSha256.
It is suggested that OEMs use a different authPolicy for each generation of platform and thus the FileNamePrefix will help you identify which platform the defs should be used.

=================== Provisioning Scripts =========================
  This directory also contains script files that use the definition files to provision the TPM. These scripts were written for both algorithm and platform agility so they accept Algorithm and platform-name as command line parameters.
==========
--- ResetPlatformAuth.nsh <alg> <fileNamePrefix>  
Uses the platform's authPolicy to set platformAuth to EMPTY.  Needs to be used before running any of the other scripts
 To use with SHA256 examples execute: ResetPlatformAuth SHA256 EXAMPLE
   or substitute your own platfrom-name for "EXAMPLE"
========
--- SetPlatformPolicy.nsh  <alg>  <fileNamePrefix> 
For develpment testing, can be used to set a specific PlatformPolicy. Allows you to experiment with different platform policies. Is not needed for normal provisioning
 To set PlatformPolicy to the example value execute: SetPlatformPolicy.nsh SHA256 EXAMPLE
========
--- Tpm2TxtProv.nsh  <alg>  <fileNamePrefix>  [-o]
Will create the AUX and PS NV Indexes for Intel TXT. The examples are for the new NV Handles and there are also def files for older NV Indexes which have "Original" or "OriginalDefault" for the fileNamePrefix -- they require the -o parameter to create the original AUX index.
  To create the new SHA256 AUX and PS indexes: Tpm2TxtProv SHA256 EXAMPLE
  To create the old SHA256 AUX and PS indexes: Tpm2TxtProv SHA256 Original -o
========
--- Tpm2DeleteAUX.nsh <alg>  <fileNamePrefix>  [-o]
Will delete the AUX index. The fileNamePrefix parameter must be the same as used for creating the PS Index (because PS NV data has to be modified to allow
the AUX index to be deleted).  You must use the -o argument to delete the older AUX index (and have the correct ACM).
 To delete the SHA256 example index execute: Tpm2DeleteAUX SHA256 EXAMPLE
 To delete the original SHA256 AUX index execute: Tpm2DeleteAUX SHA256 Original -o
========

--- Tpm2DeletePS.nsh <alg>  <fileNamePrefix>
Will Delete the PS Index. 
 To delete the SHA256 example index execute: Tpm2DeletePS SHA256 EXAMPLE
 To delete the original SHA256 PS index execute:  Tpm2DeletePS SHA256 Original 
========
 
--- Tpm2PpiProvDev.nsh <alg> <fileNamePrefix> [-D]
Will either create or delete the PPI Index depending on the -D parameter
 To Create the SHA256 example index execute: Tpm2PpiProvDev SHA256 EXAMPLE
 To Create the original SHA256 PPI index execute: Tpm2PpiProvDev SHA256 Original 
 To delete the SHA256 example index execute: Tpm2PpiProvDev SHA256 EXAMPLE -D
 To delete the original SHA256 PPI index execute: Tpm2PpiProvDev SHA256 Original -D
========
--- Tpm2SgxiProv.nsh <alg> <fileNamePrefix> [-D]
Will either create or delete the SGX Index depending on the -D parameter
 To Create the SHA256 example index execute: Tpm2SgxProvDev SHA256 EXAMPLE
 To Create the original SHA256 Sgx index execute: Tpm2SgxProvDev SHA256 Original 
 To delete the SHA256 example index execute: Tpm2SgxProvDev SHA256 EXAMPLE -D
 To delete the original SHA256 SGX index execute: Tpm2SgxProvDev SHA256 Original -D

 ============================================================================ 
 The following scripts might be needed on development platforms, but not on platforms being shipped to customers.
- TakeOwnership.nsh  <alg>  <fileNamePrefix> [-NE]
This will enable the storage hierarchy and if -NE parameter is specified, sets the OwnerAuth value (if it is not already set).
 To set OwnerAuth to "IntelTXT" execute: TakeOwnership SHA256 EXAMPLE -NE
 To set OwnerAuth to <EMPTY> execute:  TakeOwnership SHA256 EXAMPLE

 - Tpm2PoProv.nsh   <alg>  <filename Prefix>  [ {-D |-C} [-NE] ]
Will either create or delete the PO Index depending on if the -D parameter is present. Script assumes that OwnerAuth is empty, if not, specify the -NE parameter
When OwnerAuth is EMPTY 
 To Create the SHA256 example index execute: Tpm2PoProv SHA256 EXAMPLE
 To Create the original SHA256 PO index execute: Tpm2PoProv SHA256 Original 
 To delete the SHA256 example index execute: Tpm2PoProv SHA256 EXAMPLE -D
 To delete the original SHA256 PO index execute: Tpm2PoProv SHA256 Original -D
When OwnerAuth is not EMPTY 
 To Create the SHA256 example index execute: Tpm2PoProv SHA256 EXAMPLE -C -NE
 To Create the original SHA256 PO index execute: Tpm2PoProv SHA256 Original -C -NE
 To delete the SHA256 example index execute: Tpm2PoProv SHA256 EXAMPLE -D -NE
 To delete the original SHA256 PO index execute: Tpm2PoProv SHA256 Original -D -NE

 
 

