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,64 @@
 
 # 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. Following are the
+conditions dictating the certificate location lookup.
+
+1. NV-Index:
+
+    Default search location when **ARGUMENT** is not specified.
+
+2. Intel-EK-certificate-server:
+
+    Search location when EK certificate could not be found in the NV index AND
+    tpmEPSgenerated bit is CLEAR AND manufacturer is INTC.
+
+3. Intel-EK-Re-certification-server:
+
+    Search location when EK certificate could not be found in the NV index AND
+    tpmEPSgenerated bit is SET AND manufacturer is INTC.
+
+    Note:
+
+    In this operation information is provided regarding additional software to
+    be run as part of the re-provisioning/ re-certification service.
+
+    After re-provisioning/ recertification process is complete, EK certificates
+    can be read from the NV indexes by running another instance of
+    **tpm2_getekcertificate**.
+
+4. Generic or other EK-certificate-server:
+
+    Search location when **ARGUMENT** specifies the EK certificate web hosting
+    address.
 
 # 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 +72,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 +99,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