include/efi_variable.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * Copyright (c) 2020, Heinrich Schuchardt <xypron.glpk@gmx.de>
   4  */
   5
   6 #ifndef _EFI_VARIABLE_H
   7 #define _EFI_VARIABLE_H
   8
   9 #include <linux/bitops.h>
  10
  11 #define EFI_VARIABLE_READ_ONLY BIT(31)
  12
  13 enum efi_auth_var_type {
  14         EFI_AUTH_VAR_NONE = 0,
  15         EFI_AUTH_MODE,
  16         EFI_AUTH_VAR_PK,
  17         EFI_AUTH_VAR_KEK,
  18         EFI_AUTH_VAR_DB,
  19         EFI_AUTH_VAR_DBX,
  20         EFI_AUTH_VAR_DBT,
  21         EFI_AUTH_VAR_DBR,
  22 };
  23
  24 /**
  25  * efi_get_variable() - retrieve value of a UEFI variable
  26  *
  27  * @variable_name:      name of the variable
  28  * @vendor:             vendor GUID
  29  * @attributes:         attributes of the variable
  30  * @data_size:          size of the buffer to which the variable value is copied
  31  * @data:               buffer to which the variable value is copied
  32  * @timep:              authentication time (seconds since start of epoch)
  33  * Return:              status code
  34  */
  35 efi_status_t efi_get_variable_int(const u16 *variable_name,
  36                                   const efi_guid_t *vendor,
  37                                   u32 *attributes, efi_uintn_t *data_size,
  38                                   void *data, u64 *timep);
  39
  40 /**
  41  * efi_set_variable() - set value of a UEFI variable
  42  *
  43  * @variable_name:      name of the variable
  44  * @vendor:             vendor GUID
  45  * @attributes:         attributes of the variable
  46  * @data_size:          size of the buffer with the variable value
  47  * @data:               buffer with the variable value
  48  * @ro_check:           check the read only read only bit in attributes
  49  * Return:              status code
  50  */
  51 efi_status_t efi_set_variable_int(const u16 *variable_name,
  52                                   const efi_guid_t *vendor,
  53                                   u32 attributes, efi_uintn_t data_size,
  54                                   const void *data, bool ro_check);
  55
  56 /**
  57  * efi_get_next_variable_name_int() - enumerate the current variable names
  58  *
  59  * @variable_name_size: size of variable_name buffer in byte
  60  * @variable_name:      name of uefi variable's name in u16
  61  * @vendor:             vendor's guid
  62  *
  63  * See the Unified Extensible Firmware Interface (UEFI) specification for
  64  * details.
  65  *
  66  * Return: status code
  67  */
  68 efi_status_t efi_get_next_variable_name_int(efi_uintn_t *variable_name_size,
  69                                             u16 *variable_name,
  70                                             efi_guid_t *vendor);
  71
  72 /**
  73  * efi_query_variable_info_int() - get information about EFI variables
  74  *
  75  * This function implements the QueryVariableInfo() runtime service.
  76  *
  77  * See the Unified Extensible Firmware Interface (UEFI) specification for
  78  * details.
  79  *
  80  * @attributes:                         bitmask to select variables to be
  81  *                                      queried
  82  * @maximum_variable_storage_size:      maximum size of storage area for the
  83  *                                      selected variable types
  84  * @remaining_variable_storage_size:    remaining size of storage are for the
  85  *                                      selected variable types
  86  * @maximum_variable_size:              maximum size of a variable of the
  87  *                                      selected type
  88  * Returns:                             status code
  89  */
  90 efi_status_t efi_query_variable_info_int(u32 attributes,
  91                                          u64 *maximum_variable_storage_size,
  92                                          u64 *remaining_variable_storage_size,
  93                                          u64 *maximum_variable_size);
  94
  95 #define EFI_VAR_FILE_NAME "ubootefi.var"
  96
  97 #define EFI_VAR_BUF_SIZE CONFIG_EFI_VAR_BUF_SIZE
  98
  99 /*
 100  * This constant identifies the file format for storing UEFI variables in
 101  * struct efi_var_file.
 102  */
 103 #define EFI_VAR_FILE_MAGIC 0x0161566966456255 /* UbEfiVa, version 1 */
 104
 105 /**
 106  * struct efi_var_entry - UEFI variable file entry
 107  *
 108  * @length:     length of enty, multiple of 8
 109  * @attr:       variable attributes
 110  * @time:       authentication time (seconds since start of epoch)
 111  * @guid:       vendor GUID
 112  * @name:       UTF16 variable name
 113  */
 114 struct efi_var_entry {
 115         u32 length;
 116         u32 attr;
 117         u64 time;
 118         efi_guid_t guid;
 119         u16 name[];
 120 };
 121
 122 /**
 123  * struct efi_var_file - file for storing UEFI variables
 124  *
 125  * @reserved:   unused, may be overwritten by memory probing
 126  * @magic:      identifies file format, takes value %EFI_VAR_FILE_MAGIC
 127  * @length:     length including header
 128  * @crc32:      CRC32 without header
 129  * @var:        variables
 130  */
 131 struct efi_var_file {
 132         u64 reserved;
 133         u64 magic;
 134         u32 length;
 135         u32 crc32;
 136         struct efi_var_entry var[];
 137 };
 138
 139 /**
 140  * efi_var_to_file() - save non-volatile variables as file
 141  *
 142  * File ubootefi.var is created on the EFI system partion.
 143  *
 144  * Return:      status code
 145  */
 146 efi_status_t efi_var_to_file(void);
 147
 148 /**
 149  * efi_var_collect() - collect variables in buffer
 150  *
 151  * A buffer is allocated and filled with variables in a format ready to be
 152  * written to disk.
 153  *
 154  * @bufp:               pointer to pointer of buffer with collected variables
 155  * @lenp:               pointer to length of buffer
 156  * @check_attr_mask:    bitmask with required attributes of variables to be collected.
 157  *                      variables are only collected if all of the required
 158  *                      attributes are set.
 159  * Return:              status code
 160  */
 161 efi_status_t __maybe_unused efi_var_collect(struct efi_var_file **bufp, loff_t *lenp,
 162                                             u32 check_attr_mask);
 163
 164 /**
 165  * efi_var_restore() - restore EFI variables from buffer
 166  *
 167  * Only if @safe is set secure boot related variables will be restored.
 168  *
 169  * @buf:        buffer
 170  * @safe:       restoring from tamper-resistant storage
 171  * Return:      status code
 172  */
 173 efi_status_t efi_var_restore(struct efi_var_file *buf, bool safe);
 174
 175 /**
 176  * efi_var_from_file() - read variables from file
 177  *
 178  * File ubootefi.var is read from the EFI system partitions and the variables
 179  * stored in the file are created.
 180  *
 181  * In case the file does not exist yet or a variable cannot be set EFI_SUCCESS
 182  * is returned.
 183  *
 184  * Return:      status code
 185  */
 186 efi_status_t efi_var_from_file(void);
 187
 188 /**
 189  * efi_var_mem_init() - set-up variable list
 190  *
 191  * Return:      status code
 192  */
 193 efi_status_t efi_var_mem_init(void);
 194
 195 /**
 196  * efi_var_mem_find() - find a variable in the list
 197  *
 198  * @guid:       GUID of the variable
 199  * @name:       name of the variable
 200  * @next:       on exit pointer to the next variable after the found one
 201  * Return:      found variable
 202  */
 203 struct efi_var_entry *efi_var_mem_find(const efi_guid_t *guid, const u16 *name,
 204                                        struct efi_var_entry **next);
 205
 206 /**
 207  * efi_var_mem_del() - delete a variable from the list of variables
 208  *
 209  * @var:        variable to delete
 210  */
 211 void efi_var_mem_del(struct efi_var_entry *var);
 212
 213 /**
 214  * efi_var_mem_ins() - append a variable to the list of variables
 215  *
 216  * The variable is appended without checking if a variable of the same name
 217  * already exists. The two data buffers are concatenated.
 218  *
 219  * @variable_name:      variable name
 220  * @vendor:             GUID
 221  * @attributes:         variable attributes
 222  * @size1:              size of the first data buffer
 223  * @data1:              first data buffer
 224  * @size2:              size of the second data field
 225  * @data2:              second data buffer
 226  * @time:               time of authentication (as seconds since start of epoch)
 227  * Result:              status code
 228  */
 229 efi_status_t efi_var_mem_ins(const u16 *variable_name,
 230                              const efi_guid_t *vendor, u32 attributes,
 231                              const efi_uintn_t size1, const void *data1,
 232                              const efi_uintn_t size2, const void *data2,
 233                              const u64 time);
 234
 235 /**
 236  * efi_var_mem_free() - determine free memory for variables
 237  *
 238  * Return:      maximum data size plus variable name size
 239  */
 240 u64 efi_var_mem_free(void);
 241
 242 /**
 243  * efi_init_secure_state - initialize secure boot state
 244  *
 245  * Return:      status code
 246  */
 247 efi_status_t efi_init_secure_state(void);
 248
 249 /**
 250  * efi_auth_var_get_type() - convert variable name and guid to enum
 251  *
 252  * @name:       name of UEFI variable
 253  * @guid:       guid of UEFI variable
 254  * Return:      identifier for authentication related variables
 255  */
 256 enum efi_auth_var_type efi_auth_var_get_type(const u16 *name,
 257                                              const efi_guid_t *guid);
 258
 259 /**
 260  * efi_auth_var_get_guid() - get the predefined GUID for a variable name
 261  *
 262  * @name:       name of UEFI variable
 263  * Return:      guid of UEFI variable
 264  */
 265 const efi_guid_t *efi_auth_var_get_guid(const u16 *name);
 266
 267 /**
 268  * efi_get_next_variable_name_mem() - Runtime common code across efi variable
 269  *                                    implementations for GetNextVariable()
 270  *                                    from the cached memory copy
 271  * @variable_name_size: size of variable_name buffer in byte
 272  * @variable_name:      name of uefi variable's name in u16
 273  * @vendor:             vendor's guid
 274  *
 275  * Return: status code
 276  */
 277 efi_status_t __efi_runtime
 278 efi_get_next_variable_name_mem(efi_uintn_t *variable_name_size, u16 *variable_name,
 279                                efi_guid_t *vendor);
 280 /**
 281  * efi_get_variable_mem() - Runtime common code across efi variable
 282  *                          implementations for GetVariable() from
 283  *                          the cached memory copy
 284  *
 285  * @variable_name:      name of the variable
 286  * @vendor:             vendor GUID
 287  * @attributes:         attributes of the variable
 288  * @data_size:          size of the buffer to which the variable value is copied
 289  * @data:               buffer to which the variable value is copied
 290  * @timep:              authentication time (seconds since start of epoch)
 291  * Return:              status code
 292  */
 293 efi_status_t __efi_runtime
 294 efi_get_variable_mem(const u16 *variable_name, const efi_guid_t *vendor,
 295                      u32 *attributes, efi_uintn_t *data_size, void *data,
 296                      u64 *timep);
 297
 298 /**
 299  * efi_get_variable_runtime() - runtime implementation of GetVariable()
 300  *
 301  * @variable_name:      name of the variable
 302  * @guid:               vendor GUID
 303  * @attributes:         attributes of the variable
 304  * @data_size:          size of the buffer to which the variable value is copied
 305  * @data:               buffer to which the variable value is copied
 306  * Return:              status code
 307  */
 308 efi_status_t __efi_runtime EFIAPI
 309 efi_get_variable_runtime(u16 *variable_name, const efi_guid_t *guid,
 310                          u32 *attributes, efi_uintn_t *data_size, void *data);
 311
 312 /**
 313  * efi_get_next_variable_name_runtime() - runtime implementation of
 314  *                                        GetNextVariable()
 315  *
 316  * @variable_name_size: size of variable_name buffer in byte
 317  * @variable_name:      name of uefi variable's name in u16
 318  * @guid:               vendor's guid
 319  * Return:              status code
 320  */
 321 efi_status_t __efi_runtime EFIAPI
 322 efi_get_next_variable_name_runtime(efi_uintn_t *variable_name_size,
 323                                    u16 *variable_name, efi_guid_t *guid);
 324
 325 /**
 326  * efi_var_buf_update() - udpate memory buffer for variables
 327  *
 328  * @var_buf:    source buffer
 329  *
 330  * This function copies to the memory buffer for UEFI variables. Call this
 331  * function in ExitBootServices() if memory backed variables are only used
 332  * at runtime to fill the buffer.
 333  */
 334 void efi_var_buf_update(struct efi_var_file *var_buf);
 335
 336 #endif