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,52 +2,72 @@
 
 # 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. On the TPM NV indices: if an EK public file is **not specified** and argument
+   specifying the URL address for the EK certificate portal is **not supplied**.
+2. On the Intel EK certificate backend: if an EK public file, either RSA or ECC,
+   is **specified** and the tpmGeneratedEPS bit is clear and TPM manufacturer is
+   INTC.
+3. Provides information on how to download EK certificates from alternative
+   Intel EK certificate backend: if an EK public file, either RSA or ECC, is
+   **specified** and the tpmGeneratedEPS bit is set and TPM manufacturer is INTC.
+4. On a generic web hosting of EK certificates if an EK public, either RSA or
+   ECC, is **specified** and 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 on 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.
 
   * **-u**, **\--ek-public**=_FILE_:
 
     Specifies the file path for the endorsement key public portion in tss
-    format.
+    format. This forces the tool to not look for the EK certificates on the TPM
+    NV indices.
 
   * **-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 option is irrelevant when EK certificates are found on the TPM 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 +85,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 by supplying EK public.
+```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 by supplying EK public from another platform
+```bash
+tpm2_getekcertificate -X -x -o ECcert.bin -u ek.pub
+```
+
+## Retrieve EK certificate from TPM NV indices if possible
+```bash
+tpm2_getekcertificate -o ECcert.bin
+```
+
+## Retrieve multiple EK certificates from TPM NV indices if possible
+```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,48 @@ 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
+tpm2 clear -c p
+
+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 clear -c p
+
+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
+tpm2 clear -c p
+
+define_ek_cert_nv_index rsa_ek_cert.bin $RSA_EK_CERT_NV_INDEX
+
+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