lib/luks2/luks2.h

   1 /*
   2  * LUKS - Linux Unified Key Setup v2
   3  *
   4  * Copyright (C) 2015-2021 Red Hat, Inc. All rights reserved.
   5  * Copyright (C) 2015-2021 Milan Broz
   6  *
   7  * This program is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation; either version 2
  10  * of the License, or (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  20  */
  21
  22 #ifndef _CRYPTSETUP_LUKS2_ONDISK_H
  23 #define _CRYPTSETUP_LUKS2_ONDISK_H
  24
  25 #include <stdbool.h>
  26 #include <stdint.h>
  27 #include <sys/types.h>
  28
  29 #include "libcryptsetup.h"
  30
  31 #define LUKS2_MAGIC_1ST "LUKS\xba\xbe"
  32 #define LUKS2_MAGIC_2ND "SKUL\xba\xbe"
  33 #define LUKS2_MAGIC_L 6
  34 #define LUKS2_UUID_L 40
  35 #define LUKS2_LABEL_L 48
  36 #define LUKS2_SALT_L 64
  37 #define LUKS2_CHECKSUM_ALG_L 32
  38 #define LUKS2_CHECKSUM_L 64
  39
  40 #define LUKS2_KEYSLOTS_MAX       32
  41 #define LUKS2_TOKENS_MAX         32
  42 #define LUKS2_SEGMENT_MAX        32
  43
  44 #define LUKS2_BUILTIN_TOKEN_PREFIX "luks2-"
  45 #define LUKS2_BUILTIN_TOKEN_PREFIX_LEN 6
  46
  47 #define LUKS2_TOKEN_KEYRING LUKS2_BUILTIN_TOKEN_PREFIX "keyring"
  48
  49 #define LUKS2_DIGEST_MAX 8
  50
  51 #define CRYPT_ANY_SEGMENT -1
  52 #define CRYPT_DEFAULT_SEGMENT -2
  53 #define CRYPT_ONE_SEGMENT -3
  54
  55 #define CRYPT_ANY_DIGEST -1
  56
  57 /* 20 MiBs */
  58 #define LUKS2_DEFAULT_NONE_REENCRYPTION_LENGTH 0x1400000
  59
  60 /* 1 GiB */
  61 #define LUKS2_REENCRYPT_MAX_HOTZONE_LENGTH 0x40000000
  62
  63 struct device;
  64 struct luks2_reencrypt;
  65 struct crypt_lock_handle;
  66 struct crypt_dm_active_device;
  67 struct luks_phdr; /* LUKS1 for conversion */
  68
  69 /*
  70  * LUKS2 header on-disk.
  71  *
  72  * Binary header is followed by JSON area.
  73  * JSON area is followed by keyslot area and data area,
  74  * these are described in JSON metadata.
  75  *
  76  * Note: uuid, csum_alg are intentionally on the same offset as LUKS1
  77  * (checksum alg replaces hash in LUKS1)
  78  *
  79  * String (char) should be zero terminated.
  80  * Padding should be wiped.
  81  * Checksum is calculated with csum zeroed (+ full JSON area).
  82  */
  83 struct luks2_hdr_disk {
  84         char            magic[LUKS2_MAGIC_L];
  85         uint16_t        version;        /* Version 2 */
  86         uint64_t        hdr_size;       /* in bytes, including JSON area */
  87         uint64_t        seqid;          /* increased on every update */
  88         char            label[LUKS2_LABEL_L];
  89         char            checksum_alg[LUKS2_CHECKSUM_ALG_L];
  90         uint8_t         salt[LUKS2_SALT_L]; /* unique for every header/offset */
  91         char            uuid[LUKS2_UUID_L];
  92         char            subsystem[LUKS2_LABEL_L]; /* owner subsystem label */
  93         uint64_t        hdr_offset;     /* offset from device start in bytes */
  94         char            _padding[184];
  95         uint8_t         csum[LUKS2_CHECKSUM_L];
  96         char            _padding4096[7*512];
  97         /* JSON area starts here */
  98 } __attribute__ ((packed));
  99
 100 /*
 101  * LUKS2 header in-memory.
 102  */
 103 struct luks2_hdr {
 104         size_t          hdr_size;
 105         uint64_t        seqid;
 106         unsigned int    version;
 107         char            label[LUKS2_LABEL_L];
 108         char            subsystem[LUKS2_LABEL_L];
 109         char            checksum_alg[LUKS2_CHECKSUM_ALG_L];
 110         uint8_t         salt1[LUKS2_SALT_L];
 111         uint8_t         salt2[LUKS2_SALT_L];
 112         char            uuid[LUKS2_UUID_L];
 113         void            *jobj;
 114 };
 115
 116 struct luks2_keyslot_params {
 117         enum { LUKS2_KEYSLOT_AF_LUKS1 = 0 } af_type;
 118         enum { LUKS2_KEYSLOT_AREA_RAW = 0 } area_type;
 119
 120         union {
 121         struct {
 122                 char hash[LUKS2_CHECKSUM_ALG_L]; // or include luks.h
 123                 unsigned int stripes;
 124         } luks1;
 125         } af;
 126
 127         union {
 128         struct {
 129                 char encryption[65]; // or include utils_crypt.h
 130                 size_t key_size;
 131         } raw;
 132         } area;
 133 };
 134
 135 /*
 136  * Supportable header sizes (hdr_disk + JSON area)
 137  * Also used as offset for the 2nd header.
 138  */
 139 #define LUKS2_HDR_16K_LEN 0x4000
 140
 141 #define LUKS2_HDR_BIN_LEN sizeof(struct luks2_hdr_disk)
 142
 143 //#define LUKS2_DEFAULT_HDR_SIZE 0x400000  /* 4 MiB */
 144 #define LUKS2_DEFAULT_HDR_SIZE 0x1000000 /* 16 MiB */
 145
 146 #define LUKS2_MAX_KEYSLOTS_SIZE 0x8000000 /* 128 MiB */
 147
 148 #define LUKS2_HDR_OFFSET_MAX 0x400000 /* 4 MiB */
 149
 150 /* Offsets for secondary header (for scan if primary header is corrupted). */
 151 #define LUKS2_HDR2_OFFSETS { 0x04000, 0x008000, 0x010000, 0x020000, \
 152                              0x40000, 0x080000, 0x100000, 0x200000, LUKS2_HDR_OFFSET_MAX }
 153
 154 int LUKS2_hdr_version_unlocked(struct crypt_device *cd,
 155         const char *backup_file);
 156
 157 int LUKS2_hdr_read(struct crypt_device *cd, struct luks2_hdr *hdr, int repair);
 158 int LUKS2_hdr_write(struct crypt_device *cd, struct luks2_hdr *hdr);
 159 int LUKS2_hdr_write_force(struct crypt_device *cd, struct luks2_hdr *hdr);
 160 int LUKS2_hdr_dump(struct crypt_device *cd, struct luks2_hdr *hdr);
 161
 162 int LUKS2_hdr_uuid(struct crypt_device *cd,
 163         struct luks2_hdr *hdr,
 164         const char *uuid);
 165
 166 int LUKS2_hdr_labels(struct crypt_device *cd,
 167         struct luks2_hdr *hdr,
 168         const char *label,
 169         const char *subsystem,
 170         int commit);
 171
 172 void LUKS2_hdr_free(struct crypt_device *cd, struct luks2_hdr *hdr);
 173
 174 int LUKS2_hdr_backup(struct crypt_device *cd,
 175                      struct luks2_hdr *hdr,
 176                      const char *backup_file);
 177 int LUKS2_hdr_restore(struct crypt_device *cd,
 178                       struct luks2_hdr *hdr,
 179                       const char *backup_file);
 180
 181 uint64_t LUKS2_hdr_and_areas_size(struct luks2_hdr *hdr);
 182 uint64_t LUKS2_keyslots_size(struct luks2_hdr *hdr);
 183 uint64_t LUKS2_metadata_size(struct luks2_hdr *hdr);
 184
 185 int LUKS2_keyslot_cipher_incompatible(struct crypt_device *cd, const char *cipher_spec);
 186
 187 /*
 188  * Generic LUKS2 keyslot
 189  */
 190 int LUKS2_keyslot_open(struct crypt_device *cd,
 191         int keyslot,
 192         int segment,
 193         const char *password,
 194         size_t password_len,
 195         struct volume_key **vk);
 196
 197 int LUKS2_keyslot_open_all_segments(struct crypt_device *cd,
 198         int keyslot_old,
 199         int keyslot_new,
 200         const char *password,
 201         size_t password_len,
 202         struct volume_key **vks);
 203
 204 int LUKS2_keyslot_store(struct crypt_device *cd,
 205         struct luks2_hdr *hdr,
 206         int keyslot,
 207         const char *password,
 208         size_t password_len,
 209         const struct volume_key *vk,
 210         const struct luks2_keyslot_params *params);
 211
 212 int LUKS2_keyslot_wipe(struct crypt_device *cd,
 213         struct luks2_hdr *hdr,
 214         int keyslot,
 215         int wipe_area_only);
 216
 217 crypt_keyslot_priority LUKS2_keyslot_priority_get(struct crypt_device *cd,
 218         struct luks2_hdr *hdr,
 219         int keyslot);
 220
 221 int LUKS2_keyslot_priority_set(struct crypt_device *cd,
 222         struct luks2_hdr *hdr,
 223         int keyslot,
 224         crypt_keyslot_priority priority,
 225         int commit);
 226
 227 /*
 228  * Generic LUKS2 token
 229  */
 230 int LUKS2_token_json_get(struct crypt_device *cd,
 231         struct luks2_hdr *hdr,
 232         int token,
 233         const char **json);
 234
 235 int LUKS2_token_assign(struct crypt_device *cd,
 236         struct luks2_hdr *hdr,
 237         int keyslot,
 238         int token,
 239         int assign,
 240         int commit);
 241
 242 int LUKS2_token_is_assigned(struct crypt_device *cd,
 243         struct luks2_hdr *hdr,
 244         int keyslot,
 245         int token);
 246
 247 int LUKS2_token_assignment_copy(struct crypt_device *cd,
 248                         struct luks2_hdr *hdr,
 249                         int keyslot_from,
 250                         int keyslot_to,
 251                         int commit);
 252
 253 int LUKS2_token_create(struct crypt_device *cd,
 254         struct luks2_hdr *hdr,
 255         int token,
 256         const char *json,
 257         int commit);
 258
 259 crypt_token_info LUKS2_token_status(struct crypt_device *cd,
 260         struct luks2_hdr *hdr,
 261         int token,
 262         const char **type);
 263
 264 int LUKS2_builtin_token_get(struct crypt_device *cd,
 265         struct luks2_hdr *hdr,
 266         int token,
 267         const char *type,
 268         void *params);
 269
 270 int LUKS2_builtin_token_create(struct crypt_device *cd,
 271         struct luks2_hdr *hdr,
 272         int token,
 273         const char *type,
 274         const void *params,
 275         int commit);
 276
 277 int LUKS2_token_open_and_activate(struct crypt_device *cd,
 278                 struct luks2_hdr *hdr,
 279                 int token,
 280                 const char *name,
 281                 uint32_t flags,
 282                 void *usrptr);
 283
 284 int LUKS2_token_open_and_activate_any(struct crypt_device *cd,
 285         struct luks2_hdr *hdr,
 286         const char *name,
 287         uint32_t flags);
 288
 289 /*
 290  * Generic LUKS2 digest
 291  */
 292 int LUKS2_digest_any_matching(struct crypt_device *cd,
 293                 struct luks2_hdr *hdr,
 294                 const struct volume_key *vk);
 295
 296 int LUKS2_digest_verify_by_segment(struct crypt_device *cd,
 297         struct luks2_hdr *hdr,
 298         int segment,
 299         const struct volume_key *vk);
 300
 301 int LUKS2_digest_verify(struct crypt_device *cd,
 302         struct luks2_hdr *hdr,
 303         const struct volume_key *vk,
 304         int keyslot);
 305
 306 int LUKS2_digest_assign(struct crypt_device *cd,
 307         struct luks2_hdr *hdr,
 308         int keyslot,
 309         int digest,
 310         int assign,
 311         int commit);
 312
 313 int LUKS2_digest_segment_assign(struct crypt_device *cd,
 314         struct luks2_hdr *hdr,
 315         int segment,
 316         int digest,
 317         int assign,
 318         int commit);
 319
 320 int LUKS2_digest_by_keyslot(struct luks2_hdr *hdr, int keyslot);
 321
 322 int LUKS2_digest_by_segment(struct luks2_hdr *hdr, int segment);
 323
 324 int LUKS2_digest_create(struct crypt_device *cd,
 325         const char *type,
 326         struct luks2_hdr *hdr,
 327         const struct volume_key *vk);
 328
 329 /*
 330  * LUKS2 generic
 331  */
 332 int LUKS2_activate(struct crypt_device *cd,
 333         const char *name,
 334         struct volume_key *vk,
 335         uint32_t flags);
 336
 337 int LUKS2_activate_multi(struct crypt_device *cd,
 338         const char *name,
 339         struct volume_key *vks,
 340         uint64_t device_size,
 341         uint32_t flags);
 342
 343 int LUKS2_deactivate(struct crypt_device *cd,
 344         const char *name,
 345         struct luks2_hdr *hdr,
 346         struct crypt_dm_active_device *dmd,
 347         uint32_t flags);
 348
 349 int LUKS2_generate_hdr(
 350         struct crypt_device *cd,
 351         struct luks2_hdr *hdr,
 352         const struct volume_key *vk,
 353         const char *cipherName,
 354         const char *cipherMode,
 355         const char *integrity,
 356         const char *uuid,
 357         unsigned int sector_size,
 358         uint64_t data_offset,
 359         uint64_t align_offset,
 360         uint64_t required_alignment,
 361         uint64_t metadata_size,
 362         uint64_t keyslots_size);
 363
 364 int LUKS2_check_metadata_area_size(uint64_t metadata_size);
 365 int LUKS2_check_keyslots_area_size(uint64_t keyslots_size);
 366
 367 int LUKS2_wipe_header_areas(struct crypt_device *cd,
 368         struct luks2_hdr *hdr, bool detached_header);
 369
 370 uint64_t LUKS2_get_data_offset(struct luks2_hdr *hdr);
 371 int LUKS2_get_data_size(struct luks2_hdr *hdr, uint64_t *size, bool *dynamic);
 372 int LUKS2_get_sector_size(struct luks2_hdr *hdr);
 373 const char *LUKS2_get_cipher(struct luks2_hdr *hdr, int segment);
 374 const char *LUKS2_get_integrity(struct luks2_hdr *hdr, int segment);
 375 int LUKS2_keyslot_params_default(struct crypt_device *cd, struct luks2_hdr *hdr,
 376          struct luks2_keyslot_params *params);
 377 int LUKS2_get_volume_key_size(struct luks2_hdr *hdr, int segment);
 378 int LUKS2_get_keyslot_stored_key_size(struct luks2_hdr *hdr, int keyslot);
 379 const char *LUKS2_get_keyslot_cipher(struct luks2_hdr *hdr, int keyslot, size_t *key_size);
 380 int LUKS2_keyslot_find_empty(struct luks2_hdr *hdr);
 381 int LUKS2_keyslot_active_count(struct luks2_hdr *hdr, int segment);
 382 crypt_keyslot_info LUKS2_keyslot_info(struct luks2_hdr *hdr, int keyslot);
 383 int LUKS2_keyslot_area(struct luks2_hdr *hdr,
 384         int keyslot,
 385         uint64_t *offset,
 386         uint64_t *length);
 387 int LUKS2_keyslot_pbkdf(struct luks2_hdr *hdr, int keyslot, struct crypt_pbkdf_type *pbkdf);
 388
 389 /*
 390  * Permanent activation flags stored in header
 391  */
 392 int LUKS2_config_get_flags(struct crypt_device *cd, struct luks2_hdr *hdr, uint32_t *flags);
 393 int LUKS2_config_set_flags(struct crypt_device *cd, struct luks2_hdr *hdr, uint32_t flags);
 394
 395 /*
 396  * Requirements for device activation or header modification
 397  */
 398 int LUKS2_config_get_requirements(struct crypt_device *cd, struct luks2_hdr *hdr, uint32_t *reqs);
 399 int LUKS2_config_set_requirements(struct crypt_device *cd, struct luks2_hdr *hdr, uint32_t reqs, bool commit);
 400
 401 int LUKS2_config_get_reencrypt_version(struct luks2_hdr *hdr, uint32_t *version);
 402
 403 int LUKS2_unmet_requirements(struct crypt_device *cd, struct luks2_hdr *hdr, uint32_t reqs_mask, int quiet);
 404
 405 int LUKS2_key_description_by_segment(struct crypt_device *cd,
 406                 struct luks2_hdr *hdr, struct volume_key *vk, int segment);
 407 int LUKS2_volume_key_load_in_keyring_by_keyslot(struct crypt_device *cd,
 408                 struct luks2_hdr *hdr, struct volume_key *vk, int keyslot);
 409 int LUKS2_volume_key_load_in_keyring_by_digest(struct crypt_device *cd,
 410                 struct luks2_hdr *hdr, struct volume_key *vk, int digest);
 411
 412 int LUKS2_luks1_to_luks2(struct crypt_device *cd,
 413                          struct luks_phdr *hdr1,
 414                          struct luks2_hdr *hdr2);
 415 int LUKS2_luks2_to_luks1(struct crypt_device *cd,
 416                          struct luks2_hdr *hdr2,
 417                          struct luks_phdr *hdr1);
 418
 419 /*
 420  * LUKS2 reencryption
 421  */
 422 int LUKS2_reencrypt_locked_recovery_by_passphrase(struct crypt_device *cd,
 423         int keyslot_old,
 424         int keyslot_new,
 425         const char *passphrase,
 426         size_t passphrase_size,
 427         uint32_t flags,
 428         struct volume_key **vks);
 429
 430 void LUKS2_reencrypt_free(struct crypt_device *cd,
 431         struct luks2_reencrypt *rh);
 432
 433 crypt_reencrypt_info LUKS2_reencrypt_status(struct luks2_hdr *hdr);
 434
 435 crypt_reencrypt_info LUKS2_reencrypt_get_params(struct luks2_hdr *hdr,
 436         struct crypt_params_reencrypt *params);
 437
 438 int LUKS2_reencrypt_lock(struct crypt_device *cd,
 439         struct crypt_lock_handle **reencrypt_lock);
 440
 441 int LUKS2_reencrypt_lock_by_dm_uuid(struct crypt_device *cd,
 442         const char *dm_uuid,
 443         struct crypt_lock_handle **reencrypt_lock);
 444
 445 void LUKS2_reencrypt_unlock(struct crypt_device *cd,
 446         struct crypt_lock_handle *reencrypt_lock);
 447
 448 int LUKS2_reencrypt_check_device_size(struct crypt_device *cd,
 449         struct luks2_hdr *hdr,
 450         uint64_t check_size,
 451         uint64_t *dev_size,
 452         bool activation,
 453         bool dynamic);
 454
 455 int LUKS2_reencrypt_digest_verify(struct crypt_device *cd,
 456         struct luks2_hdr *hdr,
 457         struct volume_key *vks);
 458
 459 #endif