tpm2_getekcertificate: Add capability to scan NV indices for EK certi…

…ficates

Fixes tpm2-software#1885

Signed-off-by: Imran Desai <imran.desai@intel.com>

man/tpm2_getekcertificate.1.md

@@ -2,32 +2,49 @@
 
 # NAME
 
-**tpm2_getekcertificate**(1) - Retrieve the Endorsement key Certificate for the
-TPM endorsement key from the TPM manufacturer's endorsement certificate hosting
-server.
+**tpm2_getekcertificate**(1) - Retrieve the Endorsement key Certificate.
 
 # SYNOPSIS
 
 **tpm2_getekcertificate** [*OPTIONS*] [*ARGUMENT*]
 
 # DESCRIPTION
 
-**tpm2_getekcertificate**(1) - Retrieve the Endorsement key Certificate for
-the TPM endorsement key from the TPM manufacturer's endorsement certificate
-hosting server. The argument specifies the URL address for the ek certificate
-portal.
+**tpm2_getekcertificate**(1) - Retrieve the endorsement key certificate. The
+certificate is present either on the TCG specified TPM NV indices OR on the TPM
+manufacturer's endorsement certificate hosting server. The certificate lookup is
+in the following order:
+1. Attempts to retrieve from the TPM NV indices first : if an argument
+   specifying the URL address for the EK certificate portal is **not supplied**.
+2. Retrieved from the Intel EK certificate backend:<br>
+   a. If EK certificate is not found on the NV AND the tpmGeneratedEPS bit is
+      CLEAR AND TPM manufacturer is INTC.<br>
+   b. If EK certificate is not found on the NV AND the tpmGeneratedEPS bit is
+      SET and TPM manufacturer is INTC. In this case, The EK certificate itself
+      isn't provided. However, the information on how to download EK
+      certificates from alternative Intel EK certificate backend is provided.<br>
+3. Retrieved from non-Intel web hosting of EK certificates if the argument
+   specifying the URL address for the EK certificate portal is **supplied**.
+
+Note: The default web address if not specified points to the Intel web hosting.
 
 # OPTIONS
 
   * **-o**, **\--ek-certificate**=_FILE_ or _STDOUT_:
 
-    The fileto save the Endorsement key certificate retrieved from the TPM
-    manufacturer provisioning server. Defaults to stdout if not specified.
+    The file to save the Endorsement key certificate. When EK certificates are
+    found in the TPM NV indices, this option can be specified additional times
+    to save the RSA and ECC EK certificates in order. The tool will warn if
+    additional EK certificates are found on the TPM NV indices and only a single
+    output file is specified. If the option isn't specified all the EK
+    certificates retrieved either from the manufacturer web hosting or from the
+    TPM NV indices, are output to stdout.
 
   * **-X**, **\--allow-unverified**:
 
     Specifies to attempt connecting with the TPM manufacturer provisioning
-    server without verifying server certificate.
+    server without verifying server certificate. This option is irrelevant when
+    EK certificates are found on the TPM NV indices.
 
     **WARNING**: This option should be used only on platforms with older CA
     certificates.
@@ -40,14 +57,16 @@ portal.
   * **-x**, **\--offline**:
 
     This flags the tool to operate in an offline mode. In that the certificates
-    can be retrieved for supplied ek public that do not belong to the platform
+    can be retrieved for supplied EK public that do not belong to the platform
     the tool is run on. Useful in factory provisioning of multiple platforms
     that are not individually connected to the Internet. In such a scenario a
     single Internet facing provisioning server can utilize this tool in this
-    mode.
+    mode. This forces the tool to not look for the EK certificates on the NV
+    indices.
 
-  * **ARGUMENT** the command line argument specifies the URL address for the ek
-    certificate portal.
+  * **ARGUMENT** the command line argument specifies the URL address for the EK
+    certificate portal. This forces the tool to not look for the EK certificates
+    on the NV indices.
 
 ## References
 
@@ -65,12 +84,34 @@ provided by setting the curl mode verbose, see
 
 # EXAMPLES
 
+## Retrieve EK certificate from TPM manufacturer backend by supplying EK public.
 ```bash
 tpm2_createek -G rsa -u ek.pub -c key.ctx
 
 tpm2_getekcertificate -X -o ECcert.bin -u ek.pub \
 https://tpm.manufacturer.com/ekcertserver/
+```
+
+## Retrieve EK certificate from Intel backend if certificate not found on NV.
+```bash
+tpm2_createek -G rsa -u ek.pub -c key.ctx
 
+tpm2_getekcertificate -X -o ECcert.bin -u ek.pub
+```
+
+## Retrieve EK certificate from Intel backend for an offline platform.
+```bash
+tpm2_getekcertificate -X -x -o ECcert.bin -u ek.pub
+```
+
+## Retrieve EK certificate from TPM NV indices only, fail otherwise.
+```bash
+tpm2_getekcertificate -o ECcert.bin
+```
+
+## Retrieve multiple EK certificates from TPM NV indices only, fail otherwise.
+```bash
+tpm2_getekcertificate -o RSA_EK_cert.bin -o ECC_EK_cert.bin
 ```
 
 [returns](common/returns.md)

test/integration/tests/getekcertificate.sh

@@ -79,4 +79,43 @@ if [ "$(md5sum ecc_ek_cert.bin| awk '{ print $1 }')" != \
  exit 1
 fi
 
+# Retrieve EK certificates from NV indices
+RSA_EK_CERT_NV_INDEX=0x01C00002
+ECC_EK_CERT_NV_INDEX=0x01C0000A
+
+define_ek_cert_nv_index() {
+    file_size=`ls -l $1 | awk {'print $5'}`
+
+    tpm2 nvdefine $2 -C p -s $file_size \
+    -a 'ppwrite|ppread|ownerread|authread|no_da|platformcreate'
+
+    tpm2 nvwrite -C p -i $1 $2
+}
+
+## ECC only
+define_ek_cert_nv_index ecc_ek_cert.bin $ECC_EK_CERT_NV_INDEX
+
+tpm2 getekcertificate -o nv_ecc_ek_cert.bin
+
+diff nv_ecc_ek_cert.bin ecc_ek_cert.bin
+
+## RSA only
+tpm2 nvundefine -C p $ECC_EK_CERT_NV_INDEX
+
+define_ek_cert_nv_index rsa_ek_cert.bin $RSA_EK_CERT_NV_INDEX
+
+tpm2 getekcertificate -o nv_rsa_ek_cert.bin
+
+diff nv_rsa_ek_cert.bin rsa_ek_cert.bin
+
+## RSA & ECC
+
+define_ek_cert_nv_index ecc_ek_cert.bin $ECC_EK_CERT_NV_INDEX
+
+tpm2 getekcertificate -o nv_rsa_ek_cert.bin -o nv_ecc_ek_cert.bin
+
+diff nv_ecc_ek_cert.bin ecc_ek_cert.bin
+
+diff nv_rsa_ek_cert.bin rsa_ek_cert.bin
+
 exit 0