lib/luks2/luks2.h

   1 /*
   2  * LUKS - Linux Unified Key Setup v2
   3  *
   4  * Copyright (C) 2015-2023 Red Hat, Inc. All rights reserved.
   5  * Copyright (C) 2015-2023 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_NAME_MAX 64
  48
  49 #define LUKS2_TOKEN_KEYRING LUKS2_BUILTIN_TOKEN_PREFIX "keyring"
  50
  51 #define LUKS2_DIGEST_MAX 8
  52
  53 #define CRYPT_ANY_SEGMENT -1
  54 #define CRYPT_DEFAULT_SEGMENT -2
  55 #define CRYPT_ONE_SEGMENT -3
  56
  57 #define CRYPT_ANY_DIGEST -1
  58
  59 /* 20 MiBs */
  60 #define LUKS2_DEFAULT_NONE_REENCRYPTION_LENGTH 0x1400000
  61
  62 /* 1 GiB */
  63 #define LUKS2_REENCRYPT_MAX_HOTZONE_LENGTH 0x40000000
  64
  65 /* supported reencryption requirement versions */
  66 #define LUKS2_REENCRYPT_REQ_VERSION         UINT8_C(2)
  67 #define LUKS2_DECRYPT_DATASHIFT_REQ_VERSION UINT8_C(3)
  68
  69 /* see reencrypt_assembly_verification_data() in luks2_reencrypt_digest.c */
  70 /*      LUKS2_REENCRYPT_MAX_VERSION         UINT8_C(207) */
  71
  72 struct device;
  73 struct luks2_reencrypt;
  74 struct reenc_protection;
  75 struct crypt_lock_handle;
  76 struct crypt_dm_active_device;
  77 struct luks_phdr; /* LUKS1 for conversion */
  78
  79 /*
  80  * LUKS2 header on-disk.
  81  *
  82  * Binary header is followed by JSON area.
  83  * JSON area is followed by keyslot area and data area,
  84  * these are described in JSON metadata.
  85  *
  86  * Note: uuid, csum_alg are intentionally on the same offset as LUKS1
  87  * (checksum alg replaces hash in LUKS1)
  88  *
  89  * String (char) should be zero terminated.
  90  * Padding should be wiped.
  91  * Checksum is calculated with csum zeroed (+ full JSON area).
  92  */
  93 struct luks2_hdr_disk {
  94         char            magic[LUKS2_MAGIC_L];
  95         uint16_t        version;        /* Version 2 */
  96         uint64_t        hdr_size;       /* in bytes, including JSON area */
  97         uint64_t        seqid;          /* increased on every update */
  98         char            label[LUKS2_LABEL_L];
  99         char            checksum_alg[LUKS2_CHECKSUM_ALG_L];
 100         uint8_t         salt[LUKS2_SALT_L]; /* unique for every header/offset */
 101         char            uuid[LUKS2_UUID_L];
 102         char            subsystem[LUKS2_LABEL_L]; /* owner subsystem label */
 103         uint64_t        hdr_offset;     /* offset from device start in bytes */
 104         char            _padding[184];
 105         uint8_t         csum[LUKS2_CHECKSUM_L];
 106         char            _padding4096[7*512];
 107         /* JSON area starts here */
 108 } __attribute__ ((packed));
 109
 110 /*
 111  * LUKS2 header in-memory.
 112  */
 113 struct luks2_hdr {
 114         size_t          hdr_size;
 115         uint64_t        seqid;
 116         unsigned int    version;
 117         char            label[LUKS2_LABEL_L];
 118         char            subsystem[LUKS2_LABEL_L];
 119         char            checksum_alg[LUKS2_CHECKSUM_ALG_L];
 120         uint8_t         salt1[LUKS2_SALT_L];
 121         uint8_t         salt2[LUKS2_SALT_L];
 122         char            uuid[LUKS2_UUID_L];
 123         void            *jobj;
 124         void            *jobj_rollback;
 125 };
 126
 127 struct luks2_keyslot_params {
 128         enum { LUKS2_KEYSLOT_AF_LUKS1 = 0 } af_type;
 129         enum { LUKS2_KEYSLOT_AREA_RAW = 0 } area_type;
 130
 131         union {
 132         struct {
 133                 char hash[LUKS2_CHECKSUM_ALG_L]; // or include luks.h
 134                 unsigned int stripes;
 135         } luks1;
 136         } af;
 137
 138         union {
 139         struct {
 140                 char encryption[65]; // or include utils_crypt.h
 141                 size_t key_size;
 142         } raw;
 143         } area;
 144 };
 145
 146 /*
 147  * Supportable header sizes (hdr_disk + JSON area)
 148  * Also used as offset for the 2nd header.
 149  */
 150 #define LUKS2_HDR_16K_LEN 0x4000
 151
 152 #define LUKS2_HDR_BIN_LEN sizeof(struct luks2_hdr_disk)
 153
 154 //#define LUKS2_DEFAULT_HDR_SIZE 0x400000  /* 4 MiB */
 155 #define LUKS2_DEFAULT_HDR_SIZE 0x1000000 /* 16 MiB */
 156
 157 #define LUKS2_MAX_KEYSLOTS_SIZE 0x8000000 /* 128 MiB */
 158
 159 #define LUKS2_HDR_OFFSET_MAX 0x400000 /* 4 MiB */
 160
 161 /* Offsets for secondary header (for scan if primary header is corrupted). */
 162 #define LUKS2_HDR2_OFFSETS { 0x04000, 0x008000, 0x010000, 0x020000, \
 163                              0x40000, 0x080000, 0x100000, 0x200000, LUKS2_HDR_OFFSET_MAX }
 164
 165 int LUKS2_hdr_version_unlocked(struct crypt_device *cd,
 166         const char *backup_file);
 167
 168 int LUKS2_hdr_read(struct crypt_device *cd, struct luks2_hdr *hdr, int repair);
 169 int LUKS2_hdr_write(struct crypt_device *cd, struct luks2_hdr *hdr);
 170 int LUKS2_hdr_write_force(struct crypt_device *cd, struct luks2_hdr *hdr);
 171 int LUKS2_hdr_rollback(struct crypt_device *cd, struct luks2_hdr *hdr);
 172 int LUKS2_hdr_dump(struct crypt_device *cd, struct luks2_hdr *hdr);
 173 int LUKS2_hdr_dump_json(struct crypt_device *cd, struct luks2_hdr *hdr, const char **json);
 174
 175 int LUKS2_hdr_uuid(struct crypt_device *cd,
 176         struct luks2_hdr *hdr,
 177         const char *uuid);
 178
 179 int LUKS2_hdr_labels(struct crypt_device *cd,
 180         struct luks2_hdr *hdr,
 181         const char *label,
 182         const char *subsystem,
 183         int commit);
 184
 185 void LUKS2_hdr_free(struct crypt_device *cd, struct luks2_hdr *hdr);
 186
 187 int LUKS2_hdr_backup(struct crypt_device *cd,
 188                      struct luks2_hdr *hdr,
 189                      const char *backup_file);
 190 int LUKS2_hdr_restore(struct crypt_device *cd,
 191                       struct luks2_hdr *hdr,
 192                       const char *backup_file);
 193
 194 uint64_t LUKS2_hdr_and_areas_size(struct luks2_hdr *hdr);
 195 uint64_t LUKS2_keyslots_size(struct luks2_hdr *hdr);
 196 uint64_t LUKS2_metadata_size(struct luks2_hdr *hdr);
 197
 198 int LUKS2_keyslot_cipher_incompatible(struct crypt_device *cd, const char *cipher_spec);
 199
 200 /*
 201  * Generic LUKS2 keyslot
 202  */
 203 int LUKS2_keyslot_open(struct crypt_device *cd,
 204         int keyslot,
 205         int segment,
 206         const char *password,
 207         size_t password_len,
 208         struct volume_key **vk);
 209
 210 int LUKS2_keyslot_open_all_segments(struct crypt_device *cd,
 211         int keyslot_old,
 212         int keyslot_new,
 213         const char *password,
 214         size_t password_len,
 215         struct volume_key **vks);
 216
 217 int LUKS2_keyslot_store(struct crypt_device *cd,
 218         struct luks2_hdr *hdr,
 219         int keyslot,
 220         const char *password,
 221         size_t password_len,
 222         const struct volume_key *vk,
 223         const struct luks2_keyslot_params *params);
 224
 225 int LUKS2_keyslot_wipe(struct crypt_device *cd,
 226         struct luks2_hdr *hdr,
 227         int keyslot,
 228         int wipe_area_only);
 229
 230 crypt_keyslot_priority LUKS2_keyslot_priority_get(struct luks2_hdr *hdr, int keyslot);
 231
 232 int LUKS2_keyslot_priority_set(struct crypt_device *cd,
 233         struct luks2_hdr *hdr,
 234         int keyslot,
 235         crypt_keyslot_priority priority,
 236         int commit);
 237
 238 int LUKS2_keyslot_swap(struct crypt_device *cd,
 239         struct luks2_hdr *hdr,
 240         int keyslot,
 241         int keyslot2);
 242
 243 /*
 244  * Generic LUKS2 token
 245  */
 246 int LUKS2_token_json_get(struct luks2_hdr *hdr,
 247         int token,
 248         const char **json);
 249
 250 int LUKS2_token_assign(struct crypt_device *cd,
 251         struct luks2_hdr *hdr,
 252         int keyslot,
 253         int token,
 254         int assign,
 255         int commit);
 256
 257 int LUKS2_token_is_assigned(struct luks2_hdr *hdr,
 258         int keyslot,
 259         int token);
 260
 261 int LUKS2_token_assignment_copy(struct crypt_device *cd,
 262                         struct luks2_hdr *hdr,
 263                         int keyslot_from,
 264                         int keyslot_to,
 265                         int commit);
 266
 267 int LUKS2_token_create(struct crypt_device *cd,
 268         struct luks2_hdr *hdr,
 269         int token,
 270         const char *json,
 271         int commit);
 272
 273 crypt_token_info LUKS2_token_status(struct crypt_device *cd,
 274         struct luks2_hdr *hdr,
 275         int token,
 276         const char **type);
 277
 278 int LUKS2_token_open_and_activate(struct crypt_device *cd,
 279         struct luks2_hdr *hdr,
 280         int token,
 281         const char *name,
 282         const char *type,
 283         const char *pin,
 284         size_t pin_size,
 285         uint32_t flags,
 286         void *usrptr);
 287
 288 int LUKS2_token_unlock_key(struct crypt_device *cd,
 289         struct luks2_hdr *hdr,
 290         int token,
 291         const char *type,
 292         const char *pin,
 293         size_t pin_size,
 294         int segment,
 295         void *usrptr,
 296         struct volume_key **vk);
 297
 298 int LUKS2_token_keyring_get(struct luks2_hdr *hdr,
 299         int token,
 300         struct crypt_token_params_luks2_keyring *keyring_params);
 301
 302 int LUKS2_token_keyring_json(char *buffer, size_t buffer_size,
 303         const struct crypt_token_params_luks2_keyring *keyring_params);
 304
 305 int LUKS2_token_unlock_passphrase(struct crypt_device *cd,
 306         struct luks2_hdr *hdr,
 307         int token,
 308         const char *type,
 309         const char *pin,
 310         size_t pin_size,
 311         void *usrptr,
 312         char **passphrase,
 313         size_t *passphrase_size);
 314
 315 void crypt_token_unload_external_all(struct crypt_device *cd);
 316
 317 /*
 318  * Generic LUKS2 digest
 319  */
 320 int LUKS2_digest_any_matching(struct crypt_device *cd,
 321                 struct luks2_hdr *hdr,
 322                 const struct volume_key *vk);
 323
 324 int LUKS2_digest_verify_by_segment(struct crypt_device *cd,
 325         struct luks2_hdr *hdr,
 326         int segment,
 327         const struct volume_key *vk);
 328
 329 int LUKS2_digest_verify(struct crypt_device *cd,
 330         struct luks2_hdr *hdr,
 331         const struct volume_key *vk,
 332         int keyslot);
 333
 334 int LUKS2_digest_assign(struct crypt_device *cd,
 335         struct luks2_hdr *hdr,
 336         int keyslot,
 337         int digest,
 338         int assign,
 339         int commit);
 340
 341 int LUKS2_digest_segment_assign(struct crypt_device *cd,
 342         struct luks2_hdr *hdr,
 343         int segment,
 344         int digest,
 345         int assign,
 346         int commit);
 347
 348 int LUKS2_digest_by_keyslot(struct luks2_hdr *hdr, int keyslot);
 349
 350 int LUKS2_digest_by_segment(struct luks2_hdr *hdr, int segment);
 351
 352 int LUKS2_digest_create(struct crypt_device *cd,
 353         const char *type,
 354         struct luks2_hdr *hdr,
 355         const struct volume_key *vk);
 356
 357 /*
 358  * LUKS2 generic
 359  */
 360 int LUKS2_activate(struct crypt_device *cd,
 361         const char *name,
 362         struct volume_key *vk,
 363         uint32_t flags);
 364
 365 int LUKS2_activate_multi(struct crypt_device *cd,
 366         const char *name,
 367         struct volume_key *vks,
 368         uint64_t device_size,
 369         uint32_t flags);
 370
 371 int LUKS2_deactivate(struct crypt_device *cd,
 372         const char *name,
 373         struct luks2_hdr *hdr,
 374         struct crypt_dm_active_device *dmd,
 375         uint32_t flags);
 376
 377 int LUKS2_generate_hdr(
 378         struct crypt_device *cd,
 379         struct luks2_hdr *hdr,
 380         const struct volume_key *vk,
 381         const char *cipherName,
 382         const char *cipherMode,
 383         const char *integrity,
 384         const char *uuid,
 385         unsigned int sector_size,
 386         uint64_t data_offset,
 387         uint64_t align_offset,
 388         uint64_t required_alignment,
 389         uint64_t metadata_size,
 390         uint64_t keyslots_size);
 391
 392 int LUKS2_check_metadata_area_size(uint64_t metadata_size);
 393 int LUKS2_check_keyslots_area_size(uint64_t keyslots_size);
 394
 395 int LUKS2_wipe_header_areas(struct crypt_device *cd,
 396         struct luks2_hdr *hdr, bool detached_header);
 397
 398 uint64_t LUKS2_get_data_offset(struct luks2_hdr *hdr);
 399 int LUKS2_get_data_size(struct luks2_hdr *hdr, uint64_t *size, bool *dynamic);
 400 uint32_t LUKS2_get_sector_size(struct luks2_hdr *hdr);
 401 const char *LUKS2_get_cipher(struct luks2_hdr *hdr, int segment);
 402 const char *LUKS2_get_integrity(struct luks2_hdr *hdr, int segment);
 403 int LUKS2_keyslot_params_default(struct crypt_device *cd, struct luks2_hdr *hdr,
 404          struct luks2_keyslot_params *params);
 405 int LUKS2_get_volume_key_size(struct luks2_hdr *hdr, int segment);
 406 int LUKS2_get_keyslot_stored_key_size(struct luks2_hdr *hdr, int keyslot);
 407 const char *LUKS2_get_keyslot_cipher(struct luks2_hdr *hdr, int keyslot, size_t *key_size);
 408 int LUKS2_keyslot_find_empty(struct crypt_device *cd, struct luks2_hdr *hdr, size_t keylength);
 409 int LUKS2_keyslot_active_count(struct luks2_hdr *hdr, int segment);
 410 crypt_keyslot_info LUKS2_keyslot_info(struct luks2_hdr *hdr, int keyslot);
 411 int LUKS2_keyslot_area(struct luks2_hdr *hdr,
 412         int keyslot,
 413         uint64_t *offset,
 414         uint64_t *length);
 415 int LUKS2_keyslot_pbkdf(struct luks2_hdr *hdr, int keyslot, struct crypt_pbkdf_type *pbkdf);
 416
 417 /*
 418  * Permanent activation flags stored in header
 419  */
 420 int LUKS2_config_get_flags(struct crypt_device *cd, struct luks2_hdr *hdr, uint32_t *flags);
 421 int LUKS2_config_set_flags(struct crypt_device *cd, struct luks2_hdr *hdr, uint32_t flags);
 422
 423 /*
 424  * Requirements for device activation or header modification
 425  */
 426 int LUKS2_config_get_requirements(struct crypt_device *cd, struct luks2_hdr *hdr, uint32_t *reqs);
 427 int LUKS2_config_set_requirements(struct crypt_device *cd, struct luks2_hdr *hdr, uint32_t reqs, bool commit);
 428 int LUKS2_config_set_requirement_version(struct crypt_device *cd, struct luks2_hdr *hdr, uint32_t req_id, uint8_t req_version, bool commit);
 429
 430 int LUKS2_config_get_reencrypt_version(struct luks2_hdr *hdr, uint8_t *version);
 431
 432 bool LUKS2_reencrypt_requirement_candidate(struct luks2_hdr *hdr);
 433
 434 int LUKS2_unmet_requirements(struct crypt_device *cd, struct luks2_hdr *hdr, uint32_t reqs_mask, int quiet);
 435
 436 int LUKS2_key_description_by_segment(struct crypt_device *cd,
 437                 struct luks2_hdr *hdr, struct volume_key *vk, int segment);
 438 int LUKS2_volume_key_load_in_keyring_by_keyslot(struct crypt_device *cd,
 439                 struct luks2_hdr *hdr, struct volume_key *vk, int keyslot);
 440 int LUKS2_volume_key_load_in_keyring_by_digest(struct crypt_device *cd,
 441                 struct volume_key *vk, int digest);
 442
 443 int LUKS2_luks1_to_luks2(struct crypt_device *cd,
 444                          struct luks_phdr *hdr1,
 445                          struct luks2_hdr *hdr2);
 446 int LUKS2_luks2_to_luks1(struct crypt_device *cd,
 447                          struct luks2_hdr *hdr2,
 448                          struct luks_phdr *hdr1);
 449
 450 /*
 451  * LUKS2 reencryption
 452  */
 453 int LUKS2_reencrypt_locked_recovery_by_passphrase(struct crypt_device *cd,
 454         int keyslot_old,
 455         int keyslot_new,
 456         const char *passphrase,
 457         size_t passphrase_size,
 458         struct volume_key **vks);
 459
 460 void LUKS2_reencrypt_free(struct crypt_device *cd,
 461         struct luks2_reencrypt *rh);
 462
 463 crypt_reencrypt_info LUKS2_reencrypt_status(struct luks2_hdr *hdr);
 464
 465 crypt_reencrypt_info LUKS2_reencrypt_get_params(struct luks2_hdr *hdr,
 466         struct crypt_params_reencrypt *params);
 467
 468 int LUKS2_reencrypt_lock(struct crypt_device *cd,
 469         struct crypt_lock_handle **reencrypt_lock);
 470
 471 int LUKS2_reencrypt_lock_by_dm_uuid(struct crypt_device *cd,
 472         const char *dm_uuid,
 473         struct crypt_lock_handle **reencrypt_lock);
 474
 475 void LUKS2_reencrypt_unlock(struct crypt_device *cd,
 476         struct crypt_lock_handle *reencrypt_lock);
 477
 478 int LUKS2_reencrypt_check_device_size(struct crypt_device *cd,
 479         struct luks2_hdr *hdr,
 480         uint64_t check_size,
 481         uint64_t *dev_size,
 482         bool activation,
 483         bool dynamic);
 484
 485 int LUKS2_reencrypt_digest_verify(struct crypt_device *cd,
 486         struct luks2_hdr *hdr,
 487         struct volume_key *vks);
 488
 489 int LUKS2_reencrypt_max_hotzone_size(struct crypt_device *cd,
 490         struct luks2_hdr *hdr,
 491         const struct reenc_protection *rp,
 492         int reencrypt_keyslot,
 493         uint64_t *r_length);
 494
 495 void LUKS2_reencrypt_protection_erase(struct reenc_protection *rp);
 496
 497 #endif