diff --git a/Makefile.am b/Makefile.am index 5d6be19..497357b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -38,10 +38,9 @@ include scripts/include.am include IDE/include.am include certs/include.am include tests/include.am +include docs/include.am EXTRA_DIST+= README.md -EXTRA_DIST+= docs/SWTPM.md -EXTRA_DIST+= docs/WindowTBS.md EXTRA_DIST+= ChangeLog.md EXTRA_DIST+= LICENSE EXTRA_DIST+= autogen.sh diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..44055b8 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,112 @@ +# wolfTPM User Manual + +## Introduction + +wolfTPM is a portable TPM 2.0 project, designed for embedded use. It is highly portable, due to having been written in native C, having a single IO callback for SPI hardware interface, no external dependencies, and its compacted code with low resource usage. + +### Protocol Overview + +Trusted Platform Module (TPM, also known as ISO/IEC 11889) is an international standard for a secure crypto processor, a dedicated micro-controller designed to secure hardware through integrated cryptographic keys. Computer programs can use a TPM to authenticate hardware devices, since each TPM chip has a unique and secret RSA key burned in as it is produced. + +According to Wikipedia, a TPM provides the following: + +* A random number generator +* Facilities for the secure generation of cryptographic keys for limited uses. +* Remote attestation: Creates a nearly unforgettable hash key summary of the hardware and software configuration. The software in charge of hashing the configuration data determines the extent of the summary. This allows a third party to verify that the software has not been changed. +* Binding: Encrypts data using the TPM bind key, a unique RSA key descended from a storage key. +* Sealing: Similar to binding, but in addition, specifies the TPM state for the data to be decrypted (unsealed). + +In addition, TPM can also be used for various applications such as platform integrity, disk encryption, password protection, and software license protection. + +### Hierarchies + +* Platform: `TPM_RH_PLATFORM` +* Owner: `PM_RH_OWNER` +* Endorsement: `TPM_RH_ENDORSEMENT` + +Each hierarchy has their own manufacture generated seed. The arguments used on `TPM2_Create` or `TPM2_CreatePrimary` create a template, which is fed into a KDF to produce the same key based hierarchy used. The key generated is the same each time; even after reboot. The generation of a new RSA 2048 bit key takes about 15 seconds. Typically these are created and then stored in NV using TPM2_EvictControl. Each TPM generates their own keys uniquely based on the seed. + +There is also an Ephemeral hierarchy (TPM_RH_NULL), which can be used to create ephemeral keys. + +### Platform Configuration Registers (PCRs) + +Platform Configuration Registers (PCRs) are one of the essential features of a TPM. Their prime use case is to provide a method to cryptographically record (measure) software state: both the software running on a platform and configuration data used by that software. + +wolfTPM contains hash digests for SHA-1 and SHA-256 with an index 0-23. These hash digests can be extended to prove the integrity of a boot sequence (secure boot). + +## Building wolfTPM + +To build the wolfTPM library, it's required to first build and install the wolfSSL library. This can be downloaded from the download page, or through a "git clone" command, shown below: + +```sh +git clone https://github.com/wolfssl/wolfssl +``` + +Once the wolfSSL library has been downloaded, it needs to be built with the following options being passed to the configure script: + +```sh +./configure --enable-wolftpm && make && sudo make install +``` + +Then the wolfSSL library just needs to be built and installed however the user prefers. + +The next step is to download and install the wolfTPM library. At the time this documentation was written, the wolfTPM library does not have a stable release yet and needs to be cloned from GitHub. The following commands show how to clone and install wolfTPM: + +```sh +git clone https://github.com/wolfssl/wolftpm +cd wolftpm +./autogen.sh +./configure +make +``` + +For detailed build instructions see [/README.md](/README.md#building). + +## Getting Started + +The wolfTPM library has TPM 2.0 wrapper tests, native tests, and a sample benchmark application that come ready-to-use after a successful installation of wolfTPM. Below are some instructions on how to run the sample applications yourself. + +To interface with the hardware platform that is running these applications, please see the function "TPM2_IoCb" inside of examples/tpm_io.c. + +### Examples + +See [/examples/README.md](/examples/README.md) + +### Benchmarks + +See [/README.md](/README.md#tpm2-benchmarks) + +## wolfTPM Library Design + +### Library Headers + +wolfTPM header files are located in [/wolftpm](/wolftpm). + +The general header files that should be included from wolfTPM is shown below: + +```c +#include +#include /* If using wrappers */ +``` + +### Example Design + +Every example application that is included with wolfTPM includes the `tpm_io.h` header file, located in `/examples`. + +The `tpm_io.c` file sets up the example HAL IO callback necessary for testing and running the example applications with a Linux Kernel, STM32 CubeMX HAL or Atmel/Microchip ASF. The reference is easily modified, such that custom IO callbacks or different callbacks may be added or removed as desired. + +## API Reference + +See [https://www.wolfssl.com/docs/wolftpm-manual/](https://www.wolfssl.com/docs/wolftpm-manual/). + +### TPM 2.0 TCG API's + +See [/wolftpm/tpm2.h](/wolftpm/tpm2.h) for inline doxygen style API documentation. + +### wolfTPM Wrapper API's + +See [/wolftpm/tpm2_wrap.h](/wolftpm/tpm2_wrap.h) for inline doxygen style API documentation. + +## Support + +For questions please email support@wolfssl.com diff --git a/docs/include.am b/docs/include.am new file mode 100644 index 0000000..6f0f40d --- /dev/null +++ b/docs/include.am @@ -0,0 +1,7 @@ +# vim:ft=automake +# included from Top Level Makefile.am +# All paths should be given relative to the root + +EXTRA_DIST+= docs/README.md +EXTRA_DIST+= docs/SWTPM.md +EXTRA_DIST+= docs/WindowTBS.md diff --git a/wolftpm/tpm2.h b/wolftpm/tpm2.h index a92fc48..8eedad9 100644 --- a/wolftpm/tpm2.h +++ b/wolftpm/tpm2.h @@ -2823,13 +2823,39 @@ WOLFTPM_API int TPM2_GPIO_Config(GpioConfig_In* in); #endif /* WOLFTPM_ST33 || WOLFTPM_AUTODETECT */ /* Non-standard API's */ + +/*! + \ingroup TPM2_Proprietary + \brief Initializes a TPM with HAL IO callback and user supplied context. + When using devtpm or swtpm, the ioCb and userCtx are not used. + Note: TPM2_Init_minimal() calls TPM2_Init_ex() with both ioCb and userCtx set to NULL. + In other modes, the ioCb shall be set in order to use TIS. + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: general error (possibly IO) + \return BAD_FUNC_ARG Check arguments provided + + \param ctx pointer to a TPM2_CTX struct + \param ioCb pointer to TPM2HalIoCb (HAL IO) callback function + \param userCtx pointer to the user's context that will be stored as a member of the ctx struct + + _Example_ + \code + int rc; + TPM2_CTX tpm2Ctx; + + rc = TPM2_Init(&tpm2Ctx, TPM2_IoCb, userCtx); + if (rc != TPM_RC_SUCCESS) { + // TPM2_Init failed + } + \endcode + + \sa TPM2_Startup + \sa TPM2_GetRCString + \sa TPM2_Init_minimal + \sa TPM2_Init_ex +*/ #define _TPM_Init TPM2_Init -/* When using devtpm or swtpm, the ioCb and userCtx are not used - * and should be NULL. TPM2_Init_minimal() calls TPM2_Init_ex() - * with them set to NULL. - * - * In other modes, the ioCb shall be set in order to use TIS. - */ WOLFTPM_API TPM_RC TPM2_Init(TPM2_CTX* ctx, TPM2HalIoCb ioCb, void* userCtx); WOLFTPM_API TPM_RC TPM2_Init_ex(TPM2_CTX* ctx, TPM2HalIoCb ioCb, void* userCtx, int timeoutTries);