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
29typedef 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
60typedef 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
81uint32_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 */
91uint32_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 */
100uint32_t RollbackFirmwareWrite(uint32_t version);
101
102/**
103 * Lock must be called.
104 */
105uint32_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 */
115uint32_t RollbackKernelRead(uint32_t *version);
116
117/**
118 * Write stored kernel version.
119 */
120uint32_t RollbackKernelWrite(uint32_t version);
121
122/**
123 * Read backup data.
124 */
125uint32_t RollbackBackupRead(uint8_t *raw);
126
127/**
128 * Write backup data.
129 */
130uint32_t RollbackBackupWrite(uint8_t *raw);
131
132/**
133 * Lock must be called.  Internally, it's ignored in recovery mode.
134 */
135uint32_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 */
147uint32_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 */
155uint32_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 */
163uint32_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 */
172uint32_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 */
179uint32_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 */
185uint32_t SetVirtualDevMode(int val);
186
187#endif  /* VBOOT_REFERENCE_ROLLBACK_INDEX_H_ */
188