1 /* Copyright (c) 2013 The Chromium OS Authors. All rights reserved.
2  * Use of this source code is governed by a BSD-style license that can be
3  * found in the LICENSE file.
4  *
5  * Functions for querying, manipulating and locking rollback indices
6  * stored in the TPM NVRAM.
7  */
8 
9 #ifndef VBOOT_REFERENCE_ROLLBACK_INDEX_H_
10 #define VBOOT_REFERENCE_ROLLBACK_INDEX_H_
11 
12 #include "sysincludes.h"
13 #include "tss_constants.h"
14 
15 /* TPM NVRAM location indices. */
16 #define FIRMWARE_NV_INDEX               0x1007
17 #define KERNEL_NV_INDEX                 0x1008
18 /* This is just an opaque space for backup purposes */
19 #define BACKUP_NV_INDEX                 0x1009
20 #define BACKUP_NV_SIZE 16
21 
22 
23 /* Structure definitions for TPM spaces */
24 
25 /* Kernel space - KERNEL_NV_INDEX, locked with physical presence. */
26 #define ROLLBACK_SPACE_KERNEL_VERSION 2
27 #define ROLLBACK_SPACE_KERNEL_UID 0x4752574C  /* 'GRWL' */
28 
29 typedef struct RollbackSpaceKernel {
30 	/* Struct version, for backwards compatibility */
31 	uint8_t struct_version;
32 	/* Unique ID to detect space redefinition */
33 	uint32_t uid;
34 	/* Kernel versions */
35 	uint32_t kernel_versions;
36 	/* Reserved for future expansion */
37 	uint8_t reserved[3];
38 	/* Checksum (v2 and later only) */
39 	uint8_t crc8;
40 } __attribute__((packed)) RollbackSpaceKernel;
41 
42 /* Flags for firmware space */
43 /*
44  * Last boot was developer mode.  TPM ownership is cleared when transitioning
45  * to/from developer mode.
46  */
47 #define FLAG_LAST_BOOT_DEVELOPER 0x01
48 /*
49  * Some systems may not have a dedicated dev-mode switch, but enter and leave
50  * dev-mode through some recovery-mode magic keypresses. For those systems, the
51  * dev-mode "switch" state is in this bit (0=normal, 1=dev). To make it work, a
52  * new flag is passed to VbInit(), indicating that the system lacks a physical
53  * dev-mode switch. If a physical switch is present, this bit is ignored.
54  */
55 #define FLAG_VIRTUAL_DEV_MODE_ON 0x02
56 
57 /* Firmware space - FIRMWARE_NV_INDEX, locked with global lock. */
58 #define ROLLBACK_SPACE_FIRMWARE_VERSION 2
59 
60 typedef struct RollbackSpaceFirmware {
61 	/* Struct version, for backwards compatibility */
62 	uint8_t struct_version;
63 	/* Flags (see FLAG_* above) */
64 	uint8_t flags;
65 	/* Firmware versions */
66 	uint32_t fw_versions;
67 	/* Reserved for future expansion */
68 	uint8_t reserved[3];
69 	/* Checksum (v2 and later only) */
70 	uint8_t crc8;
71 } __attribute__((packed)) RollbackSpaceFirmware;
72 
73 
74 /* All functions return TPM_SUCCESS (zero) if successful, non-zero if error */
75 
76 /*
77  * These functions are called from VbInit().  They cannot use global
78  * variables.
79  */
80 
81 uint32_t RollbackS3Resume(void);
82 
83 /*
84  * These functions are callable from VbSelectFirmware().  They cannot use
85  * global variables.
86  */
87 
88 /**
89  * This must be called.
90  */
91 uint32_t RollbackFirmwareSetup(int is_hw_dev,
92                                int disable_dev_request,
93                                int clear_tpm_owner_request,
94                                /* two outputs on success */
95                                int *is_virt_dev, uint32_t *tpm_version);
96 
97 /**
98  * Write may be called if the versions change.
99  */
100 uint32_t RollbackFirmwareWrite(uint32_t version);
101 
102 /**
103  * Lock must be called.
104  */
105 uint32_t RollbackFirmwareLock(void);
106 
107 /*
108  * These functions are callable from VbSelectAndLoadKernel().  They may use
109  * global variables.
110  */
111 
112 /**
113  * Read stored kernel version.
114  */
115 uint32_t RollbackKernelRead(uint32_t *version);
116 
117 /**
118  * Write stored kernel version.
119  */
120 uint32_t RollbackKernelWrite(uint32_t version);
121 
122 /**
123  * Read backup data.
124  */
125 uint32_t RollbackBackupRead(uint8_t *raw);
126 
127 /**
128  * Write backup data.
129  */
130 uint32_t RollbackBackupWrite(uint8_t *raw);
131 
132 /**
133  * Lock must be called.  Internally, it's ignored in recovery mode.
134  */
135 uint32_t RollbackKernelLock(int recovery_mode);
136 
137 /****************************************************************************/
138 
139 /*
140  * The following functions are internal apis, listed here for use by unit tests
141  * only.
142  */
143 
144 /**
145  * Issue a TPM_Clear and reenable/reactivate the TPM.
146  */
147 uint32_t TPMClearAndReenable(void);
148 
149 /**
150  * Like TlclWrite(), but checks for write errors due to hitting the 64-write
151  * limit and clears the TPM when that happens.  This can only happen when the
152  * TPM is unowned, so it is OK to clear it (and we really have no choice).
153  * This is not expected to happen frequently, but it could happen.
154  */
155 uint32_t SafeWrite(uint32_t index, const void *data, uint32_t length);
156 
157 /**
158  * Similarly to SafeWrite(), this ensures we don't fail a DefineSpace because
159  * we hit the TPM write limit.  This is even less likely to happen than with
160  * writes because we only define spaces once at initialization, but we'd rather
161  * be paranoid about this.
162  */
163 uint32_t SafeDefineSpace(uint32_t index, uint32_t perm, uint32_t size);
164 
165 /**
166  * Perform one-time initializations.
167  *
168  * Create the NVRAM spaces, and set their initial values as needed.  Sets the
169  * nvLocked bit and ensures the physical presence command is enabled and
170  * locked.
171  */
172 uint32_t OneTimeInitializeTPM(RollbackSpaceFirmware *rsf,
173                               RollbackSpaceKernel *rsk);
174 
175 /**
176  * Start the TPM and establish the root of trust for the anti-rollback
177  * mechanism.
178  */
179 uint32_t SetupTPM(int developer_mode, int disable_dev_request,
180                   int clear_tpm_owner_request, RollbackSpaceFirmware *rsf);
181 
182 /**
183  * Utility function to turn the virtual dev-mode flag on or off. 0=off, 1=on.
184  */
185 uint32_t SetVirtualDevMode(int val);
186 
187 #endif  /* VBOOT_REFERENCE_ROLLBACK_INDEX_H_ */
188