blob: 5373120066f08f325b0367cb86240411f1588544 [file] [log] [blame]
Randall Spanglera2db67d2013-01-24 16:15:35 -08001/* Copyright (c) 2013 The Chromium OS Authors. All rights reserved.
Gaurav Shah0df08372010-03-24 14:22:41 -07002 * Use of this source code is governed by a BSD-style license that can be
3 * found in the LICENSE file.
4 */
5
Randall Spanglera2db67d2013-01-24 16:15:35 -08006/*
7 * TPM Lightweight Command Library.
Gaurav Shah0df08372010-03-24 14:22:41 -07008 *
9 * A low-level library for interfacing to TPM hardware or an emulator.
10 */
11
12#ifndef TPM_LITE_TLCL_H_
13#define TPM_LITE_TLCL_H_
Bill Richardson0c3ba242013-03-29 11:09:30 -070014#include <stdint.h>
Gaurav Shah0df08372010-03-24 14:22:41 -070015
Luigi Semenzato5896b962010-08-25 07:16:03 -070016#include "tss_constants.h"
Randall Spangler39f66112010-07-14 09:10:23 -070017
18/*****************************************************************************/
19/* Functions implemented in tlcl.c */
20
Randall Spanglera2db67d2013-01-24 16:15:35 -080021/**
22 * Call this first. Returns 0 if success, nonzero if error.
Randall Spangler39f66112010-07-14 09:10:23 -070023 */
Che-Liang Chiou5d9509c2010-12-16 14:11:17 +080024uint32_t TlclLibInit(void);
Randall Spangler39f66112010-07-14 09:10:23 -070025
Randall Spanglera2db67d2013-01-24 16:15:35 -080026/**
27 * Call this on shutdown. Returns 0 if success, nonzero if error.
Kees Cookf9e82e92012-04-03 11:57:04 -070028 */
29uint32_t TlclLibClose(void);
30
Luigi Semenzato3428b4b2013-01-11 15:50:39 -080031/* Low-level operations */
32
Randall Spanglera2db67d2013-01-24 16:15:35 -080033/**
34 * Perform a raw TPM request/response transaction.
Luigi Semenzato3428b4b2013-01-11 15:50:39 -080035 */
Randall Spanglera2db67d2013-01-24 16:15:35 -080036uint32_t TlclSendReceive(const uint8_t *request, uint8_t *response,
Luigi Semenzato3428b4b2013-01-11 15:50:39 -080037 int max_length);
38
Randall Spanglera2db67d2013-01-24 16:15:35 -080039/**
40 * Return the size of a TPM request or response packet.
Luigi Semenzato3428b4b2013-01-11 15:50:39 -080041 */
Randall Spanglera2db67d2013-01-24 16:15:35 -080042int TlclPacketSize(const uint8_t *packet);
Luigi Semenzato3428b4b2013-01-11 15:50:39 -080043
44/* Commands */
45
Randall Spanglera2db67d2013-01-24 16:15:35 -080046/**
47 * Send a TPM_Startup(ST_CLEAR). The TPM error code is returned (0 for
48 * success).
Gaurav Shah0df08372010-03-24 14:22:41 -070049 */
Luigi Semenzato59204c52010-06-09 13:37:15 -070050uint32_t TlclStartup(void);
Gaurav Shah0df08372010-03-24 14:22:41 -070051
Randall Spanglera2db67d2013-01-24 16:15:35 -080052/**
53 * Save the TPM state. Normally done by the kernel before a suspend, included
Luigi Semenzato54992f92011-03-16 10:56:48 -070054 * here for tests. The TPM error code is returned (0 for success).
55 */
56uint32_t TlclSaveState(void);
57
Randall Spanglera2db67d2013-01-24 16:15:35 -080058/**
59 * Resume by sending a TPM_Startup(ST_STATE). The TPM error code is returned
Luigi Semenzato3da063e2010-08-31 14:31:30 -070060 * (0 for success).
61 */
62uint32_t TlclResume(void);
63
Randall Spanglera2db67d2013-01-24 16:15:35 -080064/**
65 * Run the self test.
66 *
67 * Note---this is synchronous. To run this in parallel with other firmware,
68 * use ContinueSelfTest(). The TPM error code is returned.
Gaurav Shah0df08372010-03-24 14:22:41 -070069 */
Randall Spangler3e1081f2010-07-19 10:04:21 -070070uint32_t TlclSelfTestFull(void);
Luigi Semenzato59204c52010-06-09 13:37:15 -070071
Randall Spanglera2db67d2013-01-24 16:15:35 -080072/**
73 * Run the self test in the background.
Luigi Semenzato59204c52010-06-09 13:37:15 -070074 */
75uint32_t TlclContinueSelfTest(void);
Gaurav Shah0df08372010-03-24 14:22:41 -070076
Randall Spanglera2db67d2013-01-24 16:15:35 -080077/**
78 * Define a space with permission [perm]. [index] is the index for the space,
Luigi Semenzato59204c52010-06-09 13:37:15 -070079 * [size] the usable data size. The TPM error code is returned.
Gaurav Shah0df08372010-03-24 14:22:41 -070080 */
Luigi Semenzato59204c52010-06-09 13:37:15 -070081uint32_t TlclDefineSpace(uint32_t index, uint32_t perm, uint32_t size);
Gaurav Shah0df08372010-03-24 14:22:41 -070082
Randall Spanglera2db67d2013-01-24 16:15:35 -080083/**
84 * Write [length] bytes of [data] to space at [index]. The TPM error code is
Luigi Semenzato59204c52010-06-09 13:37:15 -070085 * returned.
Gaurav Shah0df08372010-03-24 14:22:41 -070086 */
Randall Spanglera2db67d2013-01-24 16:15:35 -080087uint32_t TlclWrite(uint32_t index, const void *data, uint32_t length);
Gaurav Shah0df08372010-03-24 14:22:41 -070088
Randall Spanglera2db67d2013-01-24 16:15:35 -080089/**
90 * Read [length] bytes from space at [index] into [data]. The TPM error code
Luigi Semenzato59204c52010-06-09 13:37:15 -070091 * is returned.
Gaurav Shah0df08372010-03-24 14:22:41 -070092 */
Randall Spanglera2db67d2013-01-24 16:15:35 -080093uint32_t TlclRead(uint32_t index, void *data, uint32_t length);
Gaurav Shah0df08372010-03-24 14:22:41 -070094
Randall Spanglera2db67d2013-01-24 16:15:35 -080095/**
96 * Read PCR at [index] into [data]. [length] must be TPM_PCR_DIGEST or
Kees Cook946370d2012-01-09 14:17:40 -080097 * larger. The TPM error code is returned.
98 */
Randall Spanglera2db67d2013-01-24 16:15:35 -080099uint32_t TlclPCRRead(uint32_t index, void *data, uint32_t length);
Kees Cook946370d2012-01-09 14:17:40 -0800100
Randall Spanglera2db67d2013-01-24 16:15:35 -0800101/**
102 * Write-lock space at [index]. The TPM error code is returned.
Gaurav Shah0df08372010-03-24 14:22:41 -0700103 */
Luigi Semenzato59204c52010-06-09 13:37:15 -0700104uint32_t TlclWriteLock(uint32_t index);
Gaurav Shah0df08372010-03-24 14:22:41 -0700105
Randall Spanglera2db67d2013-01-24 16:15:35 -0800106/**
107 * Read-lock space at [index]. The TPM error code is returned.
Gaurav Shah0df08372010-03-24 14:22:41 -0700108 */
Luigi Semenzato59204c52010-06-09 13:37:15 -0700109uint32_t TlclReadLock(uint32_t index);
Gaurav Shah0df08372010-03-24 14:22:41 -0700110
Randall Spanglera2db67d2013-01-24 16:15:35 -0800111/**
112 * Assert physical presence in software. The TPM error code is returned.
Gaurav Shah0df08372010-03-24 14:22:41 -0700113 */
Luigi Semenzato59204c52010-06-09 13:37:15 -0700114uint32_t TlclAssertPhysicalPresence(void);
Gaurav Shah0df08372010-03-24 14:22:41 -0700115
Randall Spanglera2db67d2013-01-24 16:15:35 -0800116/**
117 * Enable the physical presence command. The TPM error code is returned.
Luigi Semenzato1d83dd12010-08-30 10:23:43 -0700118 */
119uint32_t TlclPhysicalPresenceCMDEnable(void);
120
Randall Spanglera2db67d2013-01-24 16:15:35 -0800121/**
122 * Finalize the physical presence settings: sofware PP is enabled, hardware PP
Luigi Semenzato377557f2010-08-31 13:20:53 -0700123 * is disabled, and the lifetime lock is set. The TPM error code is returned.
124 */
125uint32_t TlclFinalizePhysicalPresence(void);
126
Randall Spanglerc3d488d2013-01-28 16:23:48 -0800127uint32_t TlclAssertPhysicalPresenceResult(void);
128
Randall Spanglera2db67d2013-01-24 16:15:35 -0800129/**
130 * Turn off physical presence and locks it off until next reboot. The TPM
Luigi Semenzato59204c52010-06-09 13:37:15 -0700131 * error code is returned.
Luigi Semenzato596b6402010-05-27 14:04:52 -0700132 */
133uint32_t TlclLockPhysicalPresence(void);
134
Randall Spanglera2db67d2013-01-24 16:15:35 -0800135/**
136 * Set the nvLocked bit. The TPM error code is returned.
Gaurav Shah0df08372010-03-24 14:22:41 -0700137 */
Luigi Semenzato59204c52010-06-09 13:37:15 -0700138uint32_t TlclSetNvLocked(void);
Gaurav Shah0df08372010-03-24 14:22:41 -0700139
Randall Spanglera2db67d2013-01-24 16:15:35 -0800140/**
141 * Return 1 if the TPM is owned, 0 otherwise.
Gaurav Shah0df08372010-03-24 14:22:41 -0700142 */
143int TlclIsOwned(void);
144
Randall Spanglera2db67d2013-01-24 16:15:35 -0800145/**
146 * Issue a ForceClear. The TPM error code is returned.
Gaurav Shah0df08372010-03-24 14:22:41 -0700147 */
Luigi Semenzato59204c52010-06-09 13:37:15 -0700148uint32_t TlclForceClear(void);
Gaurav Shah0df08372010-03-24 14:22:41 -0700149
Randall Spanglera2db67d2013-01-24 16:15:35 -0800150/**
151 * Issue a PhysicalEnable. The TPM error code is returned.
Gaurav Shah0df08372010-03-24 14:22:41 -0700152 */
Luigi Semenzato59204c52010-06-09 13:37:15 -0700153uint32_t TlclSetEnable(void);
Gaurav Shah0df08372010-03-24 14:22:41 -0700154
Randall Spanglera2db67d2013-01-24 16:15:35 -0800155/**
156 * Issue a PhysicalDisable. The TPM error code is returned.
Luigi Semenzato416f6812010-07-08 12:12:12 -0700157 */
158uint32_t TlclClearEnable(void);
159
Randall Spanglera2db67d2013-01-24 16:15:35 -0800160/**
161 * Issue a SetDeactivated. Pass 0 to activate. Returns result code.
Gaurav Shah0df08372010-03-24 14:22:41 -0700162 */
Luigi Semenzato59204c52010-06-09 13:37:15 -0700163uint32_t TlclSetDeactivated(uint8_t flag);
Gaurav Shah0df08372010-03-24 14:22:41 -0700164
Randall Spanglera2db67d2013-01-24 16:15:35 -0800165/**
166 * Get flags of interest. Pointers for flags you aren't interested in may
Randall Spangler205190d2010-08-05 15:55:06 -0700167 * be NULL. The TPM error code is returned.
Gaurav Shah0df08372010-03-24 14:22:41 -0700168 */
Randall Spanglera2db67d2013-01-24 16:15:35 -0800169uint32_t TlclGetFlags(uint8_t *disable, uint8_t *deactivated,
170 uint8_t *nvlocked);
Gaurav Shah0df08372010-03-24 14:22:41 -0700171
Randall Spanglera2db67d2013-01-24 16:15:35 -0800172/**
173 * Set the bGlobalLock flag, which only a reboot can clear. The TPM error
Luigi Semenzato59204c52010-06-09 13:37:15 -0700174 * code is returned.
Luigi Semenzato596b6402010-05-27 14:04:52 -0700175 */
176uint32_t TlclSetGlobalLock(void);
177
Randall Spanglera2db67d2013-01-24 16:15:35 -0800178/**
179 * Perform a TPM_Extend.
Randall Spangler39f66112010-07-14 09:10:23 -0700180 */
Randall Spanglera2db67d2013-01-24 16:15:35 -0800181uint32_t TlclExtend(int pcr_num, const uint8_t *in_digest, uint8_t *out_digest);
Randall Spangler39f66112010-07-14 09:10:23 -0700182
Randall Spanglera2db67d2013-01-24 16:15:35 -0800183/**
184 * Get the permission bits for the NVRAM space with |index|.
Luigi Semenzato4f11c362010-06-10 11:01:04 -0700185 */
Randall Spanglera2db67d2013-01-24 16:15:35 -0800186uint32_t TlclGetPermissions(uint32_t index, uint32_t *permissions);
Luigi Semenzato4f11c362010-06-10 11:01:04 -0700187
Randall Spanglera2db67d2013-01-24 16:15:35 -0800188/**
189 * Get the entire set of permanent flags.
Luigi Semenzato5896b962010-08-25 07:16:03 -0700190 */
Randall Spanglera2db67d2013-01-24 16:15:35 -0800191uint32_t TlclGetPermanentFlags(TPM_PERMANENT_FLAGS *pflags);
Luigi Semenzato5896b962010-08-25 07:16:03 -0700192
Randall Spanglera2db67d2013-01-24 16:15:35 -0800193/**
194 * Get the entire set of volatile (ST_CLEAR) flags.
Luigi Semenzato5896b962010-08-25 07:16:03 -0700195 */
Randall Spanglera2db67d2013-01-24 16:15:35 -0800196uint32_t TlclGetSTClearFlags(TPM_STCLEAR_FLAGS *pflags);
Luigi Semenzato5896b962010-08-25 07:16:03 -0700197
Randall Spanglera2db67d2013-01-24 16:15:35 -0800198/**
199 * Get the ownership flag. The TPM error code is returned.
Kees Cook8b6da262012-06-07 13:48:26 -0700200 */
Randall Spanglera2db67d2013-01-24 16:15:35 -0800201uint32_t TlclGetOwnership(uint8_t *owned);
Kees Cook8b6da262012-06-07 13:48:26 -0700202
Randall Spanglera2db67d2013-01-24 16:15:35 -0800203/**
204 * Request [length] bytes from TPM RNG to be stored in [data]. Actual number of
205 * bytes read is stored in [size]. The TPM error code is returned.
Kees Cookf0605cb2012-02-29 16:09:14 -0800206 */
Randall Spanglera2db67d2013-01-24 16:15:35 -0800207uint32_t TlclGetRandom(uint8_t *data, uint32_t length, uint32_t *size);
Kees Cookf0605cb2012-02-29 16:09:14 -0800208
Gaurav Shah0df08372010-03-24 14:22:41 -0700209#endif /* TPM_LITE_TLCL_H_ */