Merge pull request #143 from tomoveu/add-sym-keygen

Author: elms

.gitignore

@@ -50,6 +50,8 @@ tests/unit.test
 examples/keygen/keyload
 examples/keygen/keygen
 examples/keygen/keyimport
+examples/nvram/store
+examples/nvram/read
 
 # Generated Cert Files
 certs/ca-*.pem

README.md

@@ -12,19 +12,23 @@ Portable TPM 2.0 project designed for embedded use.
 * wolfTPM can also use the Linux TPM kernel interface (/dev/tpmX) to talk with any physical TPM on SPI, I2C and even LPC bus.
 * Platform support for Raspberry Pi, STM32 with CubeMX, Atmel ASF and Barebox.
 * The design allows for easy portability to different platforms:
-	* Native C code designed for embedded use.
-	* Single IO callback for hardware SPI interface.
-	* No external dependencies.
-	* Compact code size and minimal memory use.
+    * Native C code designed for embedded use.
+    * Single IO callback for hardware SPI interface.
+    * No external dependencies.
+    * Compact code size and minimal memory use.
 * Includes example code for:
     * Most TPM2 native API’s
     * All TPM2 wrapper API's
-	* PKCS 7
-	* Certificate Signing Request (CSR)
-	* TLS Client
-	* TLS Server
-	* Benchmarking TPM algorithms and TLS
-* Parameter encryption support using AES-CFB or XOR. Supports salted unbound authenticated sessions.
+    * PKCS 7
+    * Certificate Signing Request (CSR)
+    * TLS Client
+    * TLS Server
+    * Use of the TPM's Non-volatile memory
+    * Attestation (TPM2_Quote and TPM2_GetTime)
+    * Benchmarking TPM algorithms and TLS
+* Parameter encryption support using AES-CFB or XOR.
+* Support for salted unbound authenticated sessions.
+* Support for HMAC Sessions.
 
 Note: See [examples/README.md](examples/README.md) for details on using the examples.
 

examples/README.md

@@ -236,8 +236,35 @@ TPM2.0 Key load example
 Loading SRK: Storage 0x81000200 (282 bytes)
 Reading 744 bytes from keyblob.bin
 Loaded key to 0x80000001
+
+./examples/keygen/keygen -sym=aescfb128
+TPM2.0 Key generation example
+	Key Blob: keyblob.bin
+	Algorithm: SYMCIPHER
+		 aescfb mode, 128 keybits
+	Template: Default
+	Use Parameter Encryption: NULL
+Loading SRK: Storage 0x81000200 (282 bytes)
+Symmetric template
+Creating new SYMCIPHER key...
+Created new key (pub 50, priv 142 bytes)
+Wrote 198 bytes to keyblob.bin
+
+$ ./examples/keygen/keyload
+TPM2.0 Key load example
+	Key Blob: keyblob.bin
+	Use Parameter Encryption: NULL
+Loading SRK: Storage 0x81000200 (282 bytes)
+Reading 198 bytes from keyblob.bin
+Reading the private part of the key
+Loaded key to 0x80000001
+
 ```
 
+When filename is not supplied, a default filename "keyblob.bin" is used, therefore `keyload` and `keygen` can be used without additional parameters for quick TPM 2.0 key generation demonstration.
+
+To see the complete list of supported cryptographic algorithms and options by the `keygen` example, use one of the `--help` switches.
+
 Example for importing a private key as TPM key blob and storing to disk, then loading from disk and loading into temporary TPM handle.
 
 ```
@@ -271,26 +298,79 @@ The `keyload` tool takes only one argument, the filename of the stored key. Beca
 
 ## Storing keys into the TPM's NVRAM
 
-These examples demonstrates how to use the TPM as secure vault for keys. There are two programs, one to store a TPM key into the TPM's NVRAM and another to extract the key from the TPM's NVRAM. Both examples can use parameter encryption to protect from MITM attacks. The Non-volatile memory location is protected with a password authorization that is passed in encrypted form, when "-aes" or "-xor" is given on the commmand line.
+These examples demonstrates how to use the TPM as a secure vault for keys. There are two programs, one to store a TPM key into the TPM's NVRAM and another to extract the key from the TPM's NVRAM. Both examples can use parameter encryption to protect from MITM attacks. The Non-volatile memory location is protected with a password authorization that is passed in encrypted form, when "-aes" is given on the command line.
 
 Before running the examples, make sure there is a keyblob.bin generated using the keygen tool. The key can be of any type, RSA, ECC or symmetric. The example will store the private and public part. In case of a symmetric key the public part is meta data from the TPM. How to generate a key you can see above, in the description of the keygen example.
 
-Typical output for storing and then reading an RSA key using parameter encryption:
+Typical output for storing and then reading an RSA key with parameter encryption enabled:
 
 ```
+
 $ ./examples/nvram/store -aes
+Parameter Encryption: Enabled (AES CFB).
+
 TPM2_StartAuthSession: sessionHandle 0x2000000
 Reading 840 bytes from keyblob.bin
 Storing key at TPM NV index 0x1800202 with password protection
+
 Public part = 616 bytes
+NV write of public part succeeded
+
 Private part = 222 bytes
-NV write succeeded
+Stored 2-byte size marker before the private part
+NV write of private part succeeded
+
+
+$ ./examples/nvram/read -aes
+Parameter Encryption: Enabled (AES CFB).
 
-$ ./examples/nvram/read 616 222 -aes
 TPM2_StartAuthSession: sessionHandle 0x2000000
 Trying to read 616 bytes of public key part from NV
+Successfully read public key part from NV
+
+Trying to read size marker of the private key part from NV
+Successfully read size marker from NV
+
+Trying to read 222 bytes of private key part from NV
+Successfully read private key part from NV
+
+Extraction of key from NVRAM at index 0x1800202 succeeded
+Loading SRK: Storage 0x81000200 (282 bytes)
+Trying to load the key extracted from NVRAM
+Loaded key to 0x80000001
+
+```
+
+The "read" example will try to load the extracted key, if both the public and private part of the key were stored in NVRAM. The "-aes" switches triggers the use of parameter encryption.
+
+The examples can work with partial key material - private or public. This is achieved by using the "-priv" and "-pub" options.
+
+Typical output of storing only the private key of RSA asymmetric key pair in NVRAM and without parameter encryption enabled.
+
+```
+
+$ ./examples/nvram/store -priv
+Parameter Encryption: Not enabled (try -aes or -xor).
+
+Reading 506 bytes from keyblob.bin
+Reading the private part of the key
+Storing key at TPM NV index 0x1800202 with password protection
+
+Private part = 222 bytes
+Stored 2-byte size marker before the private part
+NV write of private part succeeded
+
+$ ./examples/nvram/read -priv
+Parameter Encryption: Not enabled (try -aes or -xor).
+
+Trying to read size marker of the private key part from NV
+Successfully read size marker from NV
+
 Trying to read 222 bytes of private key part from NV
+Successfully read private key part from NV
+
 Extraction of key from NVRAM at index 0x1800202 succeeded
+
 ```
 
-The read example takes as first argument the size of the public part and as second argument the private part. This information is given from the store example. The "-aes" swiches triggers the use of parameter encryption.
+After successful key extraction using "read", the NV Index is destroyed. Therefore, to use "read" again, the "store" example must be run again as well.

examples/keygen/keygen.c

@@ -1,6 +1,6 @@
 /* keygen.c
  *
- * Copyright (C) 2006-2020 wolfSSL Inc.
+ * Copyright (C) 2006-2021 wolfSSL Inc.
  *
  * This file is part of wolfTPM.
  *
@@ -29,34 +29,99 @@
 #include <examples/tpm_test_keys.h>
 
 #include <stdio.h>
+#include <stdlib.h> /* atoi */
 
 #ifndef WOLFTPM2_NO_WRAPPER
 
+#define SYM_EXTRA_OPTS_LEN 14 /* 5 for "-sym=" and 6 for extra options */
+#define SYM_EXTRA_OPTS_POS 4  /* Array pos of the equal sign for extra opts */
+#define SYM_EXTRA_OPTS_AES_MODE_POS 8
+#define SYM_EXTRA_OPTS_KEY_BITS_POS 11
+
+
+
 /******************************************************************************/
 /* --- BEGIN TPM Keygen Example -- */
 /******************************************************************************/
 static void usage(void)
 {
     printf("Expected usage:\n");
-    printf("./examples/keygen/keygen [keyblob.bin] [-ecc/-rsa] [-t] [-aes/xor]\n");
-    printf("* -ecc: Use RSA or ECC for keys\n");
+    printf("./examples/keygen/keygen [keyblob.bin] [-ecc/-rsa/-sym] [-t] [-aes/xor]\n");
+    printf("* -rsa: Use RSA for asymmetric key generation (DEFAULT)\n");
+    printf("* -ecc: Use ECC for asymmetric key generation \n");
+    printf("* -sym: Use Symmetric Cypher for key generation\n");
+    printf("\tDefault Symmetric Cypher is AES CTR with 256 bits\n");
     printf("* -t: Use default template (otherwise AIK)\n");
     printf("* -aes/xor: Use Parameter Encryption\n");
+    printf("Example usage:\n");
+    printf("\t* RSA, default template\n");
+    printf("\t\t keygen -t\n");
+    printf("\t* ECC, Attestation Key template "\
+           "with AES CFB parameter encryption\n");
+    printf("\t\t keygen -ecc -aes\n");
+    printf("\t* Symmetric key, AES, CTR mode, 128 bits\n");
+    printf("\t\t keygen -sym=aesctr128\n");
+    printf("\t* Symmetric key, AES, CFB mode, 256 bits\n");
+    printf("\t\t keygen -sym=aescfb256\n");
+    printf("\t* Symmetric key, AES, CBC mode, 128 bits, "\
+           "with XOR parameter encryption\n");
+    printf("\t\t keygen -sym=aescbc256 -xor\n");
+}
+
+static int symChoice(const char* arg, TPM_ALG_ID* algSym, int* keyBits,
+                     char* symMode)
+{
+    size_t len = XSTRLEN(arg);
+
+    if (len != SYM_EXTRA_OPTS_LEN) {
+        return TPM_RC_FAILURE;
+    }
+    if (XSTRNCMP(&arg[SYM_EXTRA_OPTS_POS+1], "aes", 3)) {
+        return TPM_RC_FAILURE;
+    }
+
+    /* Copy string for user information later */
+    XMEMCPY(symMode, &arg[SYM_EXTRA_OPTS_POS+1], 6);
+
+    if (XSTRNCMP(&arg[SYM_EXTRA_OPTS_AES_MODE_POS], "cfb", 3) == 0) {
+        *algSym = TPM_ALG_CFB;
+    }
+    else if (XSTRNCMP(&arg[SYM_EXTRA_OPTS_AES_MODE_POS], "ctr", 3) == 0) {
+        *algSym = TPM_ALG_CTR;
+    }
+    else if (XSTRNCMP(&arg[SYM_EXTRA_OPTS_AES_MODE_POS], "cbc", 3) == 0) {
+        *algSym = TPM_ALG_CBC;
+    }
+    else {
+        return TPM_RC_FAILURE;
+    }
+
+    *keyBits = atoi(&arg[SYM_EXTRA_OPTS_KEY_BITS_POS]);
+    if(*keyBits != 128 && *keyBits != 192 && *keyBits != 256) {
+        return TPM_RC_FAILURE;
+    }
+
+    return TPM_RC_SUCCESS;
 }
 
 int TPM2_Keygen_Example(void* userCtx, int argc, char *argv[])
 {
     int rc;
     WOLFTPM2_DEV dev;
     WOLFTPM2_KEY storage; /* SRK */
+    WOLFTPM2_KEY aesKey; /* Symmetric key */
     WOLFTPM2_KEYBLOB newKey;
     TPMT_PUBLIC publicTemplate;
-    TPMI_ALG_PUBLIC alg = TPM_ALG_RSA; /* TPM_ALG_ECC */
+    TPMI_ALG_PUBLIC alg = TPM_ALG_RSA; /* default, see usage() for options */
+    TPM_ALG_ID algSym = TPM_ALG_CTR; /* default Symmetric Cypher, see usage */
     TPM_ALG_ID paramEncAlg = TPM_ALG_NULL;
     WOLFTPM2_SESSION tpmSession;
     TPM2B_AUTH auth;
     int bAIK = 1;
+    int keyBits = 256;
     const char* outputFile = "keyblob.bin";
+    size_t len = 0;
+    char symMode[] = "aesctr";
 
     if (argc >= 2) {
         if (XSTRNCMP(argv[1], "-?", 2) == 0 ||
@@ -69,9 +134,29 @@ int TPM2_Keygen_Example(void* userCtx, int argc, char *argv[])
             outputFile = argv[1];
     }
     while (argc > 1) {
+        if (XSTRNCMP(argv[argc-1], "-rsa", 4) == 0) {
+            alg = TPM_ALG_RSA;
+        }
         if (XSTRNCMP(argv[argc-1], "-ecc", 4) == 0) {
             alg = TPM_ALG_ECC;
         }
+        if (XSTRNCMP(argv[argc-1], "-sym", 4) == 0) {
+            len = XSTRLEN(argv[argc-1]);
+            if (len >= SYM_EXTRA_OPTS_LEN) {
+                /* Did the user provide specific options? */
+                if (argv[argc-1][SYM_EXTRA_OPTS_POS] == '=') {
+                    rc = symChoice(argv[argc-1], &algSym, &keyBits, symMode);
+                }
+                /* In case of incorrect extra options, abort execution */
+                if (rc != TPM_RC_SUCCESS) {
+                    usage();
+                    return 0;
+                }
+                /* Otherwise, defaults are used: AES CTR, 256 key bits */
+            }
+            alg = TPM_ALG_SYMCIPHER;
+            bAIK = 0;
+        }
         if (XSTRNCMP(argv[argc-1], "-t", 2) == 0) {
             bAIK = 0;
         }
@@ -86,12 +171,16 @@ int TPM2_Keygen_Example(void* userCtx, int argc, char *argv[])
 
     XMEMSET(&storage, 0, sizeof(storage));
     XMEMSET(&newKey, 0, sizeof(newKey));
+    XMEMSET(&aesKey, 0, sizeof(aesKey));
     XMEMSET(&tpmSession, 0, sizeof(tpmSession));
     XMEMSET(&auth, 0, sizeof(auth));
 
     printf("TPM2.0 Key generation example\n");
     printf("\tKey Blob: %s\n", outputFile);
     printf("\tAlgorithm: %s\n", TPM2_GetAlgName(alg));
+    if(alg == TPM_ALG_SYMCIPHER) {
+        printf("\t\t %s mode, %d keybits\n", symMode, keyBits);
+    }
     printf("\tTemplate: %s\n", bAIK ? "AIK" : "Default");
     printf("\tUse Parameter Encryption: %s\n", TPM2_GetAlgName(paramEncAlg));
 
@@ -129,6 +218,10 @@ int TPM2_Keygen_Example(void* userCtx, int argc, char *argv[])
             printf("ECC AIK template\n");
             rc = wolfTPM2_GetKeyTemplate_ECC_AIK(&publicTemplate);
         }
+        else if (alg == TPM_ALG_SYMCIPHER) {
+            printf("AIK are expected to be RSA or ECC, not symmetric keys.\n");
+            rc = BAD_FUNC_ARG;
+        }
         else {
             rc = BAD_FUNC_ARG;
         }
@@ -152,6 +245,11 @@ int TPM2_Keygen_Example(void* userCtx, int argc, char *argv[])
                      TPMA_OBJECT_sign | TPMA_OBJECT_noDA,
                      TPM_ECC_NIST_P256, TPM_ALG_ECDSA);
         }
+        else if (alg == TPM_ALG_SYMCIPHER) {
+            printf("Symmetric template\n");
+            rc = wolfTPM2_GetKeyTemplate_Symmetric(&publicTemplate, keyBits,
+                    algSym, YES, YES);
+        }
         else {
             rc = BAD_FUNC_ARG;
         }
@@ -176,6 +274,9 @@ int TPM2_Keygen_Example(void* userCtx, int argc, char *argv[])
 #if !defined(WOLFTPM2_NO_WOLFCRYPT) && !defined(NO_FILESYSTEM)
     rc = writeKeyBlob(outputFile, &newKey);
 #else
+    if(alg == TPM_ALG_SYMCIPHER) {
+        printf("The Public Part of a symmetric key contains only meta data\n");
+    }
     printf("Key Public Blob %d\n", newKey.pub.size);
     TPM2_PrintBin((const byte*)&newKey.pub.publicArea, newKey.pub.size);
     printf("Key Private Blob %d\n", newKey.priv.size);