1a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/* Copyright (c) 2013 The Chromium OS Authors. All rights reserved. 20df08373a2d85d1188751749835e466eee8db878Gaurav Shah * Use of this source code is governed by a BSD-style license that can be 30df08373a2d85d1188751749835e466eee8db878Gaurav Shah * found in the LICENSE file. 40df08373a2d85d1188751749835e466eee8db878Gaurav Shah */ 50df08373a2d85d1188751749835e466eee8db878Gaurav Shah 6a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/* 7a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * TPM Lightweight Command Library. 80df08373a2d85d1188751749835e466eee8db878Gaurav Shah * 90df08373a2d85d1188751749835e466eee8db878Gaurav Shah * A low-level library for interfacing to TPM hardware or an emulator. 100df08373a2d85d1188751749835e466eee8db878Gaurav Shah */ 110df08373a2d85d1188751749835e466eee8db878Gaurav Shah 120df08373a2d85d1188751749835e466eee8db878Gaurav Shah#ifndef TPM_LITE_TLCL_H_ 130df08373a2d85d1188751749835e466eee8db878Gaurav Shah#define TPM_LITE_TLCL_H_ 140c3ba249abb1dc60f5ebabccf84ff13206440b83Bill Richardson#include <stdint.h> 150df08373a2d85d1188751749835e466eee8db878Gaurav Shah 165896b9664d088699e246de964a7c374af663a34eLuigi Semenzato#include "tss_constants.h" 1739f66114c03639715cb88774255f066a2d942557Randall Spangler 1839f66114c03639715cb88774255f066a2d942557Randall Spangler/*****************************************************************************/ 1939f66114c03639715cb88774255f066a2d942557Randall Spangler/* Functions implemented in tlcl.c */ 2039f66114c03639715cb88774255f066a2d942557Randall Spangler 21a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 22a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Call this first. Returns 0 if success, nonzero if error. 2339f66114c03639715cb88774255f066a2d942557Randall Spangler */ 245d9509cbdee7b9c8dd91ed47d967569dbb9af83dChe-Liang Chiouuint32_t TlclLibInit(void); 2539f66114c03639715cb88774255f066a2d942557Randall Spangler 26a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 27a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Call this on shutdown. Returns 0 if success, nonzero if error. 28f9e82e9695d3f208b549cc0208baf24985bbb488Kees Cook */ 29f9e82e9695d3f208b549cc0208baf24985bbb488Kees Cookuint32_t TlclLibClose(void); 30f9e82e9695d3f208b549cc0208baf24985bbb488Kees Cook 313428b4bcd99a6d2e9f8b3e1bdf800d943fbe78c3Luigi Semenzato/* Low-level operations */ 323428b4bcd99a6d2e9f8b3e1bdf800d943fbe78c3Luigi Semenzato 33a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 34a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Perform a raw TPM request/response transaction. 353428b4bcd99a6d2e9f8b3e1bdf800d943fbe78c3Luigi Semenzato */ 36a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangleruint32_t TlclSendReceive(const uint8_t *request, uint8_t *response, 373428b4bcd99a6d2e9f8b3e1bdf800d943fbe78c3Luigi Semenzato int max_length); 383428b4bcd99a6d2e9f8b3e1bdf800d943fbe78c3Luigi Semenzato 39a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 40a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Return the size of a TPM request or response packet. 413428b4bcd99a6d2e9f8b3e1bdf800d943fbe78c3Luigi Semenzato */ 42a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spanglerint TlclPacketSize(const uint8_t *packet); 433428b4bcd99a6d2e9f8b3e1bdf800d943fbe78c3Luigi Semenzato 443428b4bcd99a6d2e9f8b3e1bdf800d943fbe78c3Luigi Semenzato/* Commands */ 453428b4bcd99a6d2e9f8b3e1bdf800d943fbe78c3Luigi Semenzato 46a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 47a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Send a TPM_Startup(ST_CLEAR). The TPM error code is returned (0 for 48a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * success). 490df08373a2d85d1188751749835e466eee8db878Gaurav Shah */ 5059204c57d0a4889e3cace81b3361ea06f7b3fb45Luigi Semenzatouint32_t TlclStartup(void); 510df08373a2d85d1188751749835e466eee8db878Gaurav Shah 52a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 53a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Save the TPM state. Normally done by the kernel before a suspend, included 5454992f9d3379c4b048d8da6171f0e578b2db4facLuigi Semenzato * here for tests. The TPM error code is returned (0 for success). 5554992f9d3379c4b048d8da6171f0e578b2db4facLuigi Semenzato */ 5654992f9d3379c4b048d8da6171f0e578b2db4facLuigi Semenzatouint32_t TlclSaveState(void); 5754992f9d3379c4b048d8da6171f0e578b2db4facLuigi Semenzato 58a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 59a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Resume by sending a TPM_Startup(ST_STATE). The TPM error code is returned 603da063e3f7612464a41a4c9b2b31fb7eade57a13Luigi Semenzato * (0 for success). 613da063e3f7612464a41a4c9b2b31fb7eade57a13Luigi Semenzato */ 623da063e3f7612464a41a4c9b2b31fb7eade57a13Luigi Semenzatouint32_t TlclResume(void); 633da063e3f7612464a41a4c9b2b31fb7eade57a13Luigi Semenzato 64a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 65a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Run the self test. 66a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * 67a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Note---this is synchronous. To run this in parallel with other firmware, 68a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * use ContinueSelfTest(). The TPM error code is returned. 690df08373a2d85d1188751749835e466eee8db878Gaurav Shah */ 703e1081fb71385d72fd3a522599c35b516dda7a37Randall Spangleruint32_t TlclSelfTestFull(void); 7159204c57d0a4889e3cace81b3361ea06f7b3fb45Luigi Semenzato 72a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 73a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Run the self test in the background. 7459204c57d0a4889e3cace81b3361ea06f7b3fb45Luigi Semenzato */ 7559204c57d0a4889e3cace81b3361ea06f7b3fb45Luigi Semenzatouint32_t TlclContinueSelfTest(void); 760df08373a2d85d1188751749835e466eee8db878Gaurav Shah 77a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 78a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Define a space with permission [perm]. [index] is the index for the space, 7959204c57d0a4889e3cace81b3361ea06f7b3fb45Luigi Semenzato * [size] the usable data size. The TPM error code is returned. 800df08373a2d85d1188751749835e466eee8db878Gaurav Shah */ 8159204c57d0a4889e3cace81b3361ea06f7b3fb45Luigi Semenzatouint32_t TlclDefineSpace(uint32_t index, uint32_t perm, uint32_t size); 820df08373a2d85d1188751749835e466eee8db878Gaurav Shah 83a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 84a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Write [length] bytes of [data] to space at [index]. The TPM error code is 8559204c57d0a4889e3cace81b3361ea06f7b3fb45Luigi Semenzato * returned. 860df08373a2d85d1188751749835e466eee8db878Gaurav Shah */ 87a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangleruint32_t TlclWrite(uint32_t index, const void *data, uint32_t length); 880df08373a2d85d1188751749835e466eee8db878Gaurav Shah 89a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 90a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Read [length] bytes from space at [index] into [data]. The TPM error code 9159204c57d0a4889e3cace81b3361ea06f7b3fb45Luigi Semenzato * is returned. 920df08373a2d85d1188751749835e466eee8db878Gaurav Shah */ 93a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangleruint32_t TlclRead(uint32_t index, void *data, uint32_t length); 940df08373a2d85d1188751749835e466eee8db878Gaurav Shah 95a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 96a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Read PCR at [index] into [data]. [length] must be TPM_PCR_DIGEST or 97946370d012a809bba833ff9d37fe0ce86af09860Kees Cook * larger. The TPM error code is returned. 98946370d012a809bba833ff9d37fe0ce86af09860Kees Cook */ 99a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangleruint32_t TlclPCRRead(uint32_t index, void *data, uint32_t length); 100946370d012a809bba833ff9d37fe0ce86af09860Kees Cook 101a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 102a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Write-lock space at [index]. The TPM error code is returned. 1030df08373a2d85d1188751749835e466eee8db878Gaurav Shah */ 10459204c57d0a4889e3cace81b3361ea06f7b3fb45Luigi Semenzatouint32_t TlclWriteLock(uint32_t index); 1050df08373a2d85d1188751749835e466eee8db878Gaurav Shah 106a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 107a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Read-lock space at [index]. The TPM error code is returned. 1080df08373a2d85d1188751749835e466eee8db878Gaurav Shah */ 10959204c57d0a4889e3cace81b3361ea06f7b3fb45Luigi Semenzatouint32_t TlclReadLock(uint32_t index); 1100df08373a2d85d1188751749835e466eee8db878Gaurav Shah 111a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 112a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Assert physical presence in software. The TPM error code is returned. 1130df08373a2d85d1188751749835e466eee8db878Gaurav Shah */ 11459204c57d0a4889e3cace81b3361ea06f7b3fb45Luigi Semenzatouint32_t TlclAssertPhysicalPresence(void); 1150df08373a2d85d1188751749835e466eee8db878Gaurav Shah 116a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 117a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Enable the physical presence command. The TPM error code is returned. 1181d83dd1ba5b825407a8e17972c54577d14ba173dLuigi Semenzato */ 1191d83dd1ba5b825407a8e17972c54577d14ba173dLuigi Semenzatouint32_t TlclPhysicalPresenceCMDEnable(void); 1201d83dd1ba5b825407a8e17972c54577d14ba173dLuigi Semenzato 121a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 122a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Finalize the physical presence settings: sofware PP is enabled, hardware PP 123377557fcb260c9b41abc36ebba5759336436e59cLuigi Semenzato * is disabled, and the lifetime lock is set. The TPM error code is returned. 124377557fcb260c9b41abc36ebba5759336436e59cLuigi Semenzato */ 125377557fcb260c9b41abc36ebba5759336436e59cLuigi Semenzatouint32_t TlclFinalizePhysicalPresence(void); 126377557fcb260c9b41abc36ebba5759336436e59cLuigi Semenzato 127c3d488d155961d2849dfdaa4f0461df1aa95c2caRandall Spangleruint32_t TlclAssertPhysicalPresenceResult(void); 128c3d488d155961d2849dfdaa4f0461df1aa95c2caRandall Spangler 129a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 130a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Turn off physical presence and locks it off until next reboot. The TPM 13159204c57d0a4889e3cace81b3361ea06f7b3fb45Luigi Semenzato * error code is returned. 132596b64052e7a8265b8f4411065036ba51badb6e0Luigi Semenzato */ 133596b64052e7a8265b8f4411065036ba51badb6e0Luigi Semenzatouint32_t TlclLockPhysicalPresence(void); 134596b64052e7a8265b8f4411065036ba51badb6e0Luigi Semenzato 135a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 136a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Set the nvLocked bit. The TPM error code is returned. 1370df08373a2d85d1188751749835e466eee8db878Gaurav Shah */ 13859204c57d0a4889e3cace81b3361ea06f7b3fb45Luigi Semenzatouint32_t TlclSetNvLocked(void); 1390df08373a2d85d1188751749835e466eee8db878Gaurav Shah 140a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 141a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Return 1 if the TPM is owned, 0 otherwise. 1420df08373a2d85d1188751749835e466eee8db878Gaurav Shah */ 1430df08373a2d85d1188751749835e466eee8db878Gaurav Shahint TlclIsOwned(void); 1440df08373a2d85d1188751749835e466eee8db878Gaurav Shah 145a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 146a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Issue a ForceClear. The TPM error code is returned. 1470df08373a2d85d1188751749835e466eee8db878Gaurav Shah */ 14859204c57d0a4889e3cace81b3361ea06f7b3fb45Luigi Semenzatouint32_t TlclForceClear(void); 1490df08373a2d85d1188751749835e466eee8db878Gaurav Shah 150a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 151a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Issue a PhysicalEnable. The TPM error code is returned. 1520df08373a2d85d1188751749835e466eee8db878Gaurav Shah */ 15359204c57d0a4889e3cace81b3361ea06f7b3fb45Luigi Semenzatouint32_t TlclSetEnable(void); 1540df08373a2d85d1188751749835e466eee8db878Gaurav Shah 155a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 156a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Issue a PhysicalDisable. The TPM error code is returned. 157416f681882d8a35fa4c7ad9245a9e544c3115670Luigi Semenzato */ 158416f681882d8a35fa4c7ad9245a9e544c3115670Luigi Semenzatouint32_t TlclClearEnable(void); 159416f681882d8a35fa4c7ad9245a9e544c3115670Luigi Semenzato 160a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 161a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Issue a SetDeactivated. Pass 0 to activate. Returns result code. 1620df08373a2d85d1188751749835e466eee8db878Gaurav Shah */ 16359204c57d0a4889e3cace81b3361ea06f7b3fb45Luigi Semenzatouint32_t TlclSetDeactivated(uint8_t flag); 1640df08373a2d85d1188751749835e466eee8db878Gaurav Shah 165a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 166a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Get flags of interest. Pointers for flags you aren't interested in may 167205190d4ae8080298d9d1b580dd95c885f2af42cRandall Spangler * be NULL. The TPM error code is returned. 1680df08373a2d85d1188751749835e466eee8db878Gaurav Shah */ 169a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangleruint32_t TlclGetFlags(uint8_t *disable, uint8_t *deactivated, 170a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler uint8_t *nvlocked); 1710df08373a2d85d1188751749835e466eee8db878Gaurav Shah 172a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 173a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Set the bGlobalLock flag, which only a reboot can clear. The TPM error 17459204c57d0a4889e3cace81b3361ea06f7b3fb45Luigi Semenzato * code is returned. 175596b64052e7a8265b8f4411065036ba51badb6e0Luigi Semenzato */ 176596b64052e7a8265b8f4411065036ba51badb6e0Luigi Semenzatouint32_t TlclSetGlobalLock(void); 177596b64052e7a8265b8f4411065036ba51badb6e0Luigi Semenzato 178a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 179a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Perform a TPM_Extend. 18039f66114c03639715cb88774255f066a2d942557Randall Spangler */ 181a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangleruint32_t TlclExtend(int pcr_num, const uint8_t *in_digest, uint8_t *out_digest); 18239f66114c03639715cb88774255f066a2d942557Randall Spangler 183a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 184a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Get the permission bits for the NVRAM space with |index|. 1854f11c36ebcc42a8f875ce6ea7cdc36f5c4e965deLuigi Semenzato */ 186a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangleruint32_t TlclGetPermissions(uint32_t index, uint32_t *permissions); 1874f11c36ebcc42a8f875ce6ea7cdc36f5c4e965deLuigi Semenzato 188a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 189a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Get the entire set of permanent flags. 1905896b9664d088699e246de964a7c374af663a34eLuigi Semenzato */ 191a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangleruint32_t TlclGetPermanentFlags(TPM_PERMANENT_FLAGS *pflags); 1925896b9664d088699e246de964a7c374af663a34eLuigi Semenzato 193a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 194a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Get the entire set of volatile (ST_CLEAR) flags. 1955896b9664d088699e246de964a7c374af663a34eLuigi Semenzato */ 196a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangleruint32_t TlclGetSTClearFlags(TPM_STCLEAR_FLAGS *pflags); 1975896b9664d088699e246de964a7c374af663a34eLuigi Semenzato 198a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 199a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Get the ownership flag. The TPM error code is returned. 2008b6da26a6e5978a43233f7a43c7bab5889d3817aKees Cook */ 201a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangleruint32_t TlclGetOwnership(uint8_t *owned); 2028b6da26a6e5978a43233f7a43c7bab5889d3817aKees Cook 203a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler/** 204a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * Request [length] bytes from TPM RNG to be stored in [data]. Actual number of 205a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangler * bytes read is stored in [size]. The TPM error code is returned. 206f0605cbdc36f58829a908a3333e438c565c8c7afKees Cook */ 207a2db67d204c0dd3d152ff54958bf42c5dbe394ffRandall Spangleruint32_t TlclGetRandom(uint8_t *data, uint32_t length, uint32_t *size); 208f0605cbdc36f58829a908a3333e438c565c8c7afKees Cook 2090df08373a2d85d1188751749835e466eee8db878Gaurav Shah#endif /* TPM_LITE_TLCL_H_ */ 210