/usr/include/libcryptsetup.h is in libcryptsetup-dev 2:2.0.2-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 | /*
* libcryptsetup - cryptsetup library
*
* Copyright (C) 2004, Jana Saout <jana@saout.de>
* Copyright (C) 2004-2007, Clemens Fruhwirth <clemens@endorphin.org>
* Copyright (C) 2009-2018, Red Hat, Inc. All rights reserved.
* Copyright (C) 2009-2018, Milan Broz
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
/**
* @file libcryptsetup.h
* @brief Public cryptsetup API
*
* For more verbose examples of LUKS related use cases,
* please read @ref index "examples".
*/
#ifndef _LIBCRYPTSETUP_H
#define _LIBCRYPTSETUP_H
#ifdef __cplusplus
extern "C" {
#endif
#include <stddef.h>
#include <stdint.h>
/**
* @defgroup crypt-init Cryptsetup device context initialization
* Set of functions for creating and destroying @e crypt_device context
* @addtogroup crypt-init
* @{
*/
struct crypt_device; /* crypt device handle */
/**
* Initialize crypt device handle and check if the provided device exists.
*
* @param cd Returns pointer to crypt device handle
* @param device Path to the backing device.
* If @e device is not a block device but a path to some file,
* the function will try to create a loopdevice and attach
* the file to the loopdevice with AUTOCLEAR flag set.
* If @e device is @e NULL function it will initialize dm backend only.
*
* @return @e 0 on success or negative errno value otherwise.
*
* @note Note that logging is not initialized here, possible messages use
* default log function.
*/
int crypt_init(struct crypt_device **cd, const char *device);
/**
* Initialize crypt device handle from provided active device name,
* and, optionally, from separate metadata (header) device
* and check if provided device exists.
*
* @return @e 0 on success or negative errno value otherwise.
*
* @param cd returns crypt device handle for active device
* @param name name of active crypt device
* @param header_device optional device containing on-disk header
* (@e NULL if it the same as underlying device on there is no on-disk header)
*
* @post In case @e device points to active LUKS device but header load fails,
* context device type is set to @e NULL and @e 0 is returned as if it were successful.
* Context with @e NULL device type can only be deactivated by crypt_deactivate
*
* @note @link crypt_init_by_name @endlink is equivalent to calling
* crypt_init_by_name_and_header(cd, name, NULL);
*/
int crypt_init_by_name_and_header(struct crypt_device **cd,
const char *name,
const char *header_device);
/**
* This is equivalent to call
* @ref crypt_init_by_name_and_header "crypt_init_by_name_and_header(cd, name, NULL)"
*
* @sa crypt_init_by_name_and_header
*/
int crypt_init_by_name(struct crypt_device **cd, const char *name);
/**
* Release crypt device context and used memory.
*
* @param cd crypt device handle
*/
void crypt_free(struct crypt_device *cd);
/**
* Set confirmation callback (yes/no).
*
* If code need confirmation (like resetting uuid or restoring LUKS header from file)
* this function is called. If not defined, everything is confirmed.
*
* Callback function @e confirm should return @e 0 if operation is declined,
* other values mean accepted.
*
* @param cd crypt device handle
* @param confirm user defined confirm callback reference
* @param usrptr provided identification in callback
* @param msg Message for user to confirm
*
* @note Current version of cryptsetup API requires confirmation for UUID change and
* LUKS header restore only.
*/
void crypt_set_confirm_callback(struct crypt_device *cd,
int (*confirm)(const char *msg, void *usrptr),
void *usrptr);
/**
* Set data device
* For LUKS it is encrypted data device when LUKS header is separated.
* For VERITY it is data device when hash device is separated.
*
* @param cd crypt device handle
* @param device path to device
*
*/
int crypt_set_data_device(struct crypt_device *cd, const char *device);
/** @} */
/**
* @defgroup crypt-log Cryptsetup logging
* Set of functions and defines used in cryptsetup for
* logging purposes
* @addtogroup crypt-log
* @{
*/
/** normal log level */
#define CRYPT_LOG_NORMAL 0
/** error log level */
#define CRYPT_LOG_ERROR 1
/** verbose log level */
#define CRYPT_LOG_VERBOSE 2
/** debug log level - always on stdout */
#define CRYPT_LOG_DEBUG -1
/**
* Set log function.
*
* @param cd crypt device handle (can be @e NULL to set default log function)
* @param log user defined log function reference
* @param usrptr provided identification in callback
* @param level log level below (debug messages can uses other levels)
* @param msg log message
*/
void crypt_set_log_callback(struct crypt_device *cd,
void (*log)(int level, const char *msg, void *usrptr),
void *usrptr);
/**
* Defines log function or use the default one otherwise.
*
* @see crypt_set_log_callback
*
* @param cd crypt device handle
* @param level log level
* @param msg log message
*/
void crypt_log(struct crypt_device *cd, int level, const char *msg);
/** @} */
/**
* @defgroup crypt-set Cryptsetup settings (RNG, PBKDF, locking)
* @addtogroup crypt-set
* @{
*/
/** CRYPT_RNG_URANDOM - use /dev/urandom */
#define CRYPT_RNG_URANDOM 0
/** CRYPT_RNG_RANDOM - use /dev/random (waits if no entropy in system) */
#define CRYPT_RNG_RANDOM 1
/**
* Set which RNG (random number generator) is used for generating long term key
*
* @param cd crypt device handle
* @param rng_type kernel random number generator to use
*
*/
void crypt_set_rng_type(struct crypt_device *cd, int rng_type);
/**
* Get which RNG (random number generator) is used for generating long term key.
*
* @param cd crypt device handle
* @return RNG type on success or negative errno value otherwise.
*
*/
int crypt_get_rng_type(struct crypt_device *cd);
/**
* PBKDF parameters.
*/
struct crypt_pbkdf_type {
const char *type; /**< PBKDF algorithm */
const char *hash; /**< Hash algorithm */
uint32_t time_ms; /**< Requested time cost [milliseconds] */
uint32_t iterations; /**< Iterations, 0 or benchmarked value. */
uint32_t max_memory_kb; /**< Requested or benchmarked memory cost [kilobytes] */
uint32_t parallel_threads;/**< Requested parallel cost [threads] */
uint32_t flags; /**< CRYPT_PBKDF* flags */
};
/** Iteration time set by crypt_set_iteration_time(), for compatibility only. */
#define CRYPT_PBKDF_ITER_TIME_SET (1 << 0)
/** Never run benchmarks, use pre-set value or defaults. */
#define CRYPT_PBKDF_NO_BENCHMARK (1 << 1)
/** PBKDF2 according to RFC2898, LUKS1 legacy */
#define CRYPT_KDF_PBKDF2 "pbkdf2"
/** Argon2i according to RFC */
#define CRYPT_KDF_ARGON2I "argon2i"
/** Argon2id according to RFC */
#define CRYPT_KDF_ARGON2ID "argon2id"
/**
* Set default PBKDF (Password-Based Key Derivation Algorithm) for next keyslot
* about to get created with any crypt_keyslot_add_*() call.
*
* @param cd crypt device handle
* @param pbkdf PBKDF parameters
*
* @return 0 on success or negative errno value otherwise.
*
* @note For LUKS1, only PBKDF2 is supported, other settings will be rejected.
* @note For non-LUKS context types the call succeeds, but PBKDF is not used.
*/
int crypt_set_pbkdf_type(struct crypt_device *cd,
const struct crypt_pbkdf_type *pbkdf);
/**
* Get current default PBKDF (Password-Based Key Derivation Algorithm) for keyslots.
* Works only with LUKS device handles (both versions).
*
* @param cd crypt device handle
*
* @return struct on success or NULL value otherwise.
*
*/
const struct crypt_pbkdf_type *crypt_get_pbkdf_type(struct crypt_device *cd);
/**
* Set how long should cryptsetup iterate in PBKDF2 function.
* Default value heads towards the iterations which takes around 1 second.
* \b Deprecated, only for backward compatibility.
* Use @link crypt_set_pbkdf_type @endlink.
*
* @param cd crypt device handle
* @param iteration_time_ms the time in ms
*
* @note If the time value is not acceptable for active PBKDF, value is quietly ignored.
*/
void crypt_set_iteration_time(struct crypt_device *cd, uint64_t iteration_time_ms);
/**
* Helper to lock/unlock memory to avoid swap sensitive data to disk.
*
* @param cd crypt device handle, can be @e NULL
* @param lock 0 to unlock otherwise lock memory
*
* @returns Value indicating whether the memory is locked (function can be called multiple times).
*
* @note Only root can do this.
* @note It locks/unlocks all process memory, not only crypt context.
*/
int crypt_memory_lock(struct crypt_device *cd, int lock);
/**
* Set global lock protection for on-disk metadata (file-based locking).
*
* @param cd crypt device handle, can be @e NULL
* @param enable 0 to disable locking otherwise enable it (default)
*
* @returns @e 0 on success or negative errno value otherwise.
*
* @note Locking applied only for some metadata formats (LUKS2).
* @note The switch is global on the library level.
* In current version locking can be only switched off and cannot be switched on later.
*/
int crypt_metadata_locking(struct crypt_device *cd, int enable);
/** @} */
/**
* @defgroup crypt-type Cryptsetup on-disk format types
* Set of functions, \#defines and structs related
* to on-disk format types
* @addtogroup crypt-type
* @{
*/
/** plain crypt device, no on-disk header */
#define CRYPT_PLAIN "PLAIN"
/** LUKS version 1 header on-disk */
#define CRYPT_LUKS1 "LUKS1"
/** LUKS version 2 header on-disk */
#define CRYPT_LUKS2 "LUKS2"
/** loop-AES compatibility mode */
#define CRYPT_LOOPAES "LOOPAES"
/** dm-verity mode */
#define CRYPT_VERITY "VERITY"
/** TCRYPT (TrueCrypt-compatible and VeraCrypt-compatible) mode */
#define CRYPT_TCRYPT "TCRYPT"
/** INTEGRITY dm-integrity device */
#define CRYPT_INTEGRITY "INTEGRITY"
/** LUKS any version */
#define CRYPT_LUKS NULL
/**
* Get device type
*
* @param cd crypt device handle
* @return string according to device type or @e NULL if not known.
*/
const char *crypt_get_type(struct crypt_device *cd);
/**
*
* Structure used as parameter for PLAIN device type.
*
* @see crypt_format
*/
struct crypt_params_plain {
const char *hash; /**< password hash function */
uint64_t offset; /**< offset in sectors */
uint64_t skip; /**< IV offset / initialization sector */
uint64_t size; /**< size of mapped device or @e 0 for autodetection */
uint32_t sector_size; /**< sector size in bytes (@e 0 means 512 for compatibility) */
};
/**
* Structure used as parameter for LUKS device type.
*
* @see crypt_format, crypt_load
*
* @note during crypt_format @e data_device attribute determines
* if the LUKS header is separated from encrypted payload device
*
*/
struct crypt_params_luks1 {
const char *hash; /**< hash used in LUKS header */
size_t data_alignment; /**< data alignment in sectors, data offset is multiple of this */
const char *data_device; /**< detached encrypted data device or @e NULL */
};
/**
*
* Structure used as parameter for loop-AES device type.
*
* @see crypt_format
*
*/
struct crypt_params_loopaes {
const char *hash; /**< key hash function */
uint64_t offset; /**< offset in sectors */
uint64_t skip; /**< IV offset / initialization sector */
};
/**
*
* Structure used as parameter for dm-verity device type.
*
* @see crypt_format, crypt_load
*
*/
struct crypt_params_verity {
const char *hash_name; /**< hash function */
const char *data_device; /**< data_device (CRYPT_VERITY_CREATE_HASH) */
const char *hash_device; /**< hash_device (output only) */
const char *fec_device; /**< fec_device (output only) */
const char *salt; /**< salt */
uint32_t salt_size; /**< salt size (in bytes) */
uint32_t hash_type; /**< in-kernel hashing type */
uint32_t data_block_size; /**< data block size (in bytes) */
uint32_t hash_block_size; /**< hash block size (in bytes) */
uint64_t data_size; /**< data area size (in data blocks) */
uint64_t hash_area_offset; /**< hash/header offset (in bytes) */
uint64_t fec_area_offset; /**< FEC/header offset (in bytes) */
uint32_t fec_roots; /**< Reed-Solomon FEC roots */
uint32_t flags; /**< CRYPT_VERITY* flags */
};
/** No on-disk header (only hashes) */
#define CRYPT_VERITY_NO_HEADER (1 << 0)
/** Verity hash in userspace before activation */
#define CRYPT_VERITY_CHECK_HASH (1 << 1)
/** Create hash - format hash device */
#define CRYPT_VERITY_CREATE_HASH (1 << 2)
/**
*
* Structure used as parameter for TCRYPT device type.
*
* @see crypt_load
*
*/
struct crypt_params_tcrypt {
const char *passphrase; /**< passphrase to unlock header (input only) */
size_t passphrase_size; /**< passphrase size (input only, max length is 64) */
const char **keyfiles; /**< keyfile paths to unlock header (input only) */
unsigned int keyfiles_count;/**< keyfiles count (input only) */
const char *hash_name; /**< hash function for PBKDF */
const char *cipher; /**< cipher chain c1[-c2[-c3]] */
const char *mode; /**< cipher block mode */
size_t key_size; /**< key size in bytes (the whole chain) */
uint32_t flags; /**< CRYPT_TCRYPT* flags */
uint32_t veracrypt_pim; /**< VeraCrypt Personal Iteration Multiplier */
};
/** Include legacy modes when scanning for header */
#define CRYPT_TCRYPT_LEGACY_MODES (1 << 0)
/** Try to load hidden header (describing hidden device) */
#define CRYPT_TCRYPT_HIDDEN_HEADER (1 << 1)
/** Try to load backup header */
#define CRYPT_TCRYPT_BACKUP_HEADER (1 << 2)
/** Device contains encrypted system (with boot loader) */
#define CRYPT_TCRYPT_SYSTEM_HEADER (1 << 3)
/** Include VeraCrypt modes when scanning for header,
* all other TCRYPT flags applies as well.
* VeraCrypt device is reported as TCRYPT type.
*/
#define CRYPT_TCRYPT_VERA_MODES (1 << 4)
/**
*
* Structure used as parameter for dm-integrity device type.
*
* @see crypt_format, crypt_load
*
*/
struct crypt_params_integrity {
uint64_t journal_size; /**< size of journal in bytes */
unsigned int journal_watermark; /**< journal flush watermark in percents */
unsigned int journal_commit_time; /**< journal commit time in ms */
uint32_t interleave_sectors; /**< number of interleave sectors (power of two) */
uint32_t tag_size; /**< tag size per-sector in bytes */
uint32_t sector_size; /**< sector size in bytes */
uint32_t buffer_sectors; /**< number of sectors in one buffer */
const char *integrity; /**< integrity algorithm, NULL for LUKS2 */
uint32_t integrity_key_size; /**< integrity key size in bytes, info only, 0 for LUKS2 */
const char *journal_integrity; /**< journal integrity algorithm */
const char *journal_integrity_key; /**< journal integrity key, only for crypt_load */
uint32_t journal_integrity_key_size; /**< journal integrity key size in bytes, only for crypt_load */
const char *journal_crypt; /**< journal encryption algorithm */
const char *journal_crypt_key; /**< journal crypt key, only for crypt_load */
uint32_t journal_crypt_key_size; /**< journal crypt key size in bytes, only for crypt_load */
};
/**
* Structure used as parameter for LUKS2 device type.
*
* @see crypt_format, crypt_load
*
* @note during crypt_format @e data_device attribute determines
* if the LUKS2 header is separated from encrypted payload device
*
*/
struct crypt_params_luks2 {
const struct crypt_pbkdf_type *pbkdf; /**< PBKDF (and hash) parameters or @e NULL*/
const char *integrity; /**< integrity algorithm or @e NULL */
const struct crypt_params_integrity *integrity_params; /**< Data integrity parameters or @e NULL*/
size_t data_alignment; /**< data alignment in sectors, data offset is multiple of this */
const char *data_device; /**< detached encrypted data device or @e NULL */
uint32_t sector_size; /**< encryption sector size */
const char *label; /**< header label or @e NULL*/
const char *subsystem; /**< header subsystem label or @e NULL*/
};
/** @} */
/**
* @defgroup crypt-actions Cryptsetup device context actions
* Set of functions for formatting and manipulating with specific crypt_type
* @addtogroup crypt-actions
* @{
*/
/**
* Create (format) new crypt device (and possible header on-disk) but do not activate it.
*
* @pre @e cd contains initialized and not formatted device context (device type must @b not be set)
*
* @param cd crypt device handle
* @param type type of device (optional params struct must be of this type)
* @param cipher (e.g. "aes")
* @param cipher_mode including IV specification (e.g. "xts-plain")
* @param uuid requested UUID or @e NULL if it should be generated
* @param volume_key pre-generated volume key or @e NULL if it should be generated (only for LUKS)
* @param volume_key_size size of volume key in bytes.
* @param params crypt type specific parameters (see @link crypt-type @endlink)
*
* @returns @e 0 on success or negative errno value otherwise.
*
* @note Note that crypt_format does not create LUKS keyslot (any version). To create keyslot
* call any crypt_keyslot_add_* function.
* @note For VERITY @link crypt-type @endlink, only uuid parameter is used, other parameters
* are ignored and verity specific attributes are set through mandatory params option.
*/
int crypt_format(struct crypt_device *cd,
const char *type,
const char *cipher,
const char *cipher_mode,
const char *uuid,
const char *volume_key,
size_t volume_key_size,
void *params);
/**
* Convert to new type for already existing device.
*
* @param cd crypt device handle
* @param type type of device (optional params struct must be of this type)
* @param params crypt type specific parameters (see @link crypt-type @endlink)
*
* @returns 0 on success or negative errno value otherwise.
*
* @note Currently, only LUKS1->LUKS2 and LUKS2->LUKS1 conversions are supported.
* Not all LUKS2 devices may be converted back to LUKS1. To make such a conversion
* posible all active LUKS2 keyslots must be in LUKS1 compatible mode (i.e. pbkdf
* type must be PBKDF2) and device cannot be formated with any authenticated
* encryption mode.
*
* @note Device must be offline for conversion. UUID change is not possible for active
* devices.
*/
int crypt_convert(struct crypt_device *cd,
const char *type,
void *params);
/**
* Set new UUID for already existing device.
*
* @param cd crypt device handle
* @param uuid requested UUID or @e NULL if it should be generated
*
* @returns 0 on success or negative errno value otherwise.
*
* @note Currently, only LUKS device type are supported
*/
int crypt_set_uuid(struct crypt_device *cd,
const char *uuid);
/**
* Set new labels (label and subsystem) for already existing device.
*
* @param cd crypt device handle
* @param label requested label or @e NULL
* @param subsystem requested subsystem label or @e NULL
*
* @returns 0 on success or negative errno value otherwise.
*
* @note Currently, only LUKS2 device type is supported
*/
int crypt_set_label(struct crypt_device *cd,
const char *label,
const char *subsystem);
/**
* Enable or disable loading of volume keys via kernel keyring. When set to
* 'enabled' library loads key in kernel keyring first and pass the key
* description to dm-crypt instead of binary key copy. If set to 'disabled'
* library fallbacks to old method of loading volume key directly in
* dm-crypt target.
*
* @param cd crypt device handle, can be @e NULL
* @param enable 0 to disable loading of volume keys via kernel keyring
* (classical method) otherwise enable it (default)
*
* @returns @e 0 on success or negative errno value otherwise.
*
* @note Currently loading of volume keys via kernel keyring is supported
* (and enabled by default) only for LUKS2 devices.
* @note The switch is global on the library level.
*/
int crypt_volume_key_keyring(struct crypt_device *cd, int enable);
/**
* Load crypt device parameters from on-disk header.
*
* @param cd crypt device handle
* @param requested_type @link crypt-type @endlink or @e NULL for all known
* @param params crypt type specific parameters (see @link crypt-type @endlink)
*
* @returns 0 on success or negative errno value otherwise.
*
* @post In case LUKS header is read successfully but payload device is too small
* error is returned and device type in context is set to @e NULL
*
* @note Note that in current version load works only for LUKS and VERITY device type.
*
*/
int crypt_load(struct crypt_device *cd,
const char *requested_type,
void *params);
/**
* Try to repair crypt device LUKS1 on-disk header if invalid.
*
* @param cd crypt device handle
* @param requested_type @link crypt-type @endlink or @e NULL for all known
* @param params crypt type specific parameters (see @link crypt-type @endlink)
*
* @returns 0 on success or negative errno value otherwise.
*
* @note Does not support LUKS2 devices explicitly. LUKS2 header is auto-repaired
* (if exactly one header checksum does not match) automatically on
* crypt_load().
*/
int crypt_repair(struct crypt_device *cd,
const char *requested_type,
void *params);
/**
* Resize crypt device.
*
* @param cd - crypt device handle
* @param name - name of device to resize
* @param new_size - new device size in sectors or @e 0 to use all of the underlying device size
*
* @return @e 0 on success or negative errno value otherwise.
*
* @note Most notably it returns -EPERM when device was activated with volume key
* in kernel keyring and current device handle (context) doesn't have verified key
* loaded in kernel. To load volume key for already active device use any of
* @link crypt_activate_by_passphrase @endlink, @link crypt_activate_by_keyfile @endlink,
* @link crypt_activate_by_keyfile_offset @endlink, @link crypt_activate_by_volume_key @endlink,
* @link crypt_activate_by_keyring @endlink or @link crypt_activate_by_token @endlink with flag
* @e CRYPT_ACTIVATE_KEYRING_KEY raised and @e name parameter set to @e NULL.
*/
int crypt_resize(struct crypt_device *cd,
const char *name,
uint64_t new_size);
/**
* Suspend crypt device.
*
* @param cd crypt device handle, can be @e NULL
* @param name name of device to suspend
*
* @return 0 on success or negative errno value otherwise.
*
* @note Only LUKS device type is supported
*
*/
int crypt_suspend(struct crypt_device *cd,
const char *name);
/**
* Resume crypt device using passphrase.
*
*
* @param cd crypt device handle
* @param name name of device to resume
* @param keyslot requested keyslot or CRYPT_ANY_SLOT
* @param passphrase passphrase used to unlock volume key
* @param passphrase_size size of @e passphrase (binary data)
*
* @return unlocked key slot number or negative errno otherwise.
*
* @note Only LUKS device type is supported
*/
int crypt_resume_by_passphrase(struct crypt_device *cd,
const char *name,
int keyslot,
const char *passphrase,
size_t passphrase_size);
/**
* Resume crypt device using key file.
*
* @param cd crypt device handle
* @param name name of device to resume
* @param keyslot requested keyslot or CRYPT_ANY_SLOT
* @param keyfile key file used to unlock volume key
* @param keyfile_size number of bytes to read from keyfile, 0 is unlimited
* @param keyfile_offset number of bytes to skip at start of keyfile
*
* @return unlocked key slot number or negative errno otherwise.
*/
int crypt_resume_by_keyfile_device_offset(struct crypt_device *cd,
const char *name,
int keyslot,
const char *keyfile,
size_t keyfile_size,
uint64_t keyfile_offset);
/**
* Backward compatible crypt_resume_by_keyfile_device_offset() (with size_t offset).
*/
int crypt_resume_by_keyfile_offset(struct crypt_device *cd,
const char *name,
int keyslot,
const char *keyfile,
size_t keyfile_size,
size_t keyfile_offset);
/**
* Backward compatible crypt_resume_by_keyfile_device_offset() (without offset).
*/
int crypt_resume_by_keyfile(struct crypt_device *cd,
const char *name,
int keyslot,
const char *keyfile,
size_t keyfile_size);
/** @} */
/**
* @defgroup crypt-keyslot LUKS keyslots
* @addtogroup crypt-keyslot
* @{
*/
/** iterate through all keyslots and find first one that fits */
#define CRYPT_ANY_SLOT -1
/**
* Add key slot using provided passphrase.
*
* @pre @e cd contains initialized and formatted LUKS device context
*
* @param cd crypt device handle
* @param keyslot requested keyslot or @e CRYPT_ANY_SLOT
* @param passphrase passphrase used to unlock volume key
* @param passphrase_size size of passphrase (binary data)
* @param new_passphrase passphrase for new keyslot
* @param new_passphrase_size size of @e new_passphrase (binary data)
*
* @return allocated key slot number or negative errno otherwise.
*/
int crypt_keyslot_add_by_passphrase(struct crypt_device *cd,
int keyslot,
const char *passphrase,
size_t passphrase_size,
const char *new_passphrase,
size_t new_passphrase_size);
/**
* Change defined key slot using provided passphrase.
*
* @pre @e cd contains initialized and formatted LUKS device context
*
* @param cd crypt device handle
* @param keyslot_old old keyslot or @e CRYPT_ANY_SLOT
* @param keyslot_new new keyslot (can be the same as old)
* @param passphrase passphrase used to unlock volume key
* @param passphrase_size size of passphrase (binary data)
* @param new_passphrase passphrase for new keyslot
* @param new_passphrase_size size of @e new_passphrase (binary data)
*
* @return allocated key slot number or negative errno otherwise.
*
* @note This function is just internal implementation of luksChange
* command to avoid reading of volume key outside libcryptsetup boundary
* in FIPS mode.
*/
int crypt_keyslot_change_by_passphrase(struct crypt_device *cd,
int keyslot_old,
int keyslot_new,
const char *passphrase,
size_t passphrase_size,
const char *new_passphrase,
size_t new_passphrase_size);
/**
* Add key slot using provided key file path.
*
* @pre @e cd contains initialized and formatted LUKS device context
*
* @param cd crypt device handle
* @param keyslot requested keyslot or @e CRYPT_ANY_SLOT
* @param keyfile key file used to unlock volume key
* @param keyfile_size number of bytes to read from keyfile, @e 0 is unlimited
* @param keyfile_offset number of bytes to skip at start of keyfile
* @param new_keyfile keyfile for new keyslot
* @param new_keyfile_size number of bytes to read from @e new_keyfile, @e 0 is unlimited
* @param new_keyfile_offset number of bytes to skip at start of new_keyfile
*
* @return allocated key slot number or negative errno otherwise.
*/
int crypt_keyslot_add_by_keyfile_device_offset(struct crypt_device *cd,
int keyslot,
const char *keyfile,
size_t keyfile_size,
uint64_t keyfile_offset,
const char *new_keyfile,
size_t new_keyfile_size,
uint64_t new_keyfile_offset);
/**
* Backward compatible crypt_keyslot_add_by_keyfile_device_offset() (with size_t offset).
*/
int crypt_keyslot_add_by_keyfile_offset(struct crypt_device *cd,
int keyslot,
const char *keyfile,
size_t keyfile_size,
size_t keyfile_offset,
const char *new_keyfile,
size_t new_keyfile_size,
size_t new_keyfile_offset);
/**
* Backward compatible crypt_keyslot_add_by_keyfile_device_offset() (without offset).
*/
int crypt_keyslot_add_by_keyfile(struct crypt_device *cd,
int keyslot,
const char *keyfile,
size_t keyfile_size,
const char *new_keyfile,
size_t new_keyfile_size);
/**
* Add key slot using provided volume key.
*
* @pre @e cd contains initialized and formatted LUKS device context
*
* @param cd crypt device handle
* @param keyslot requested keyslot or CRYPT_ANY_SLOT
* @param volume_key provided volume key or @e NULL if used after crypt_format
* @param volume_key_size size of volume_key
* @param passphrase passphrase for new keyslot
* @param passphrase_size size of passphrase
*
* @return allocated key slot number or negative errno otherwise.
*/
int crypt_keyslot_add_by_volume_key(struct crypt_device *cd,
int keyslot,
const char *volume_key,
size_t volume_key_size,
const char *passphrase,
size_t passphrase_size);
/** create keyslot with volume key not associated with current dm-crypt segment */
#define CRYPT_VOLUME_KEY_NO_SEGMENT (1 << 0)
/**
* Add key slot using provided key.
*
* @pre @e cd contains initialized and formatted LUKS2 device context
*
* @param cd crypt device handle
* @param keyslot requested keyslot or CRYPT_ANY_SLOT
* @param volume_key provided volume key or @e NULL (see note below)
* @param volume_key_size size of volume_key
* @param passphrase passphrase for new keyslot
* @param passphrase_size size of passphrase
* @param flags key flags to set
*
* @return allocated key slot number or negative errno otherwise.
*
* @note in case volume_key is @e NULL following first matching rule will apply:
* a) if cd is device handle used in crypt_format() by current process, the volume
* key generated (passed) to crypt_format() will be stored in keyslot.
* b) if CRYPT_VOLUME_KEY_NO_SEGMENT flag is raised the new volume_key will be
* generated and stored in keyslot.
*/
int crypt_keyslot_add_by_key(struct crypt_device *cd,
int keyslot,
const char *volume_key,
size_t volume_key_size,
const char *passphrase,
size_t passphrase_size,
uint32_t flags);
/**
* Destroy (and disable) key slot.
*
* @pre @e cd contains initialized and formatted LUKS device context
*
* @param cd crypt device handle
* @param keyslot requested key slot to destroy
*
* @return @e 0 on success or negative errno value otherwise.
*
* @note Note that there is no passphrase verification used.
*/
int crypt_keyslot_destroy(struct crypt_device *cd, int keyslot);
/** @} */
/**
* @defgroup crypt-aflags Device runtime attributes
* Activation flags
* @addtogroup crypt-aflags
* @{
*/
/** device is read only */
#define CRYPT_ACTIVATE_READONLY (1 << 0)
/** only reported for device without uuid */
#define CRYPT_ACTIVATE_NO_UUID (1 << 1)
/** activate even if cannot grant exclusive access (DANGEROUS) */
#define CRYPT_ACTIVATE_SHARED (1 << 2)
/** enable discards aka TRIM */
#define CRYPT_ACTIVATE_ALLOW_DISCARDS (1 << 3)
/** skip global udev rules in activation ("private device"), input only */
#define CRYPT_ACTIVATE_PRIVATE (1 << 4)
/** corruption detected (verity), output only */
#define CRYPT_ACTIVATE_CORRUPTED (1 << 5)
/** use same_cpu_crypt option for dm-crypt */
#define CRYPT_ACTIVATE_SAME_CPU_CRYPT (1 << 6)
/** use submit_from_crypt_cpus for dm-crypt */
#define CRYPT_ACTIVATE_SUBMIT_FROM_CRYPT_CPUS (1 << 7)
/** dm-verity: ignore_corruption flag - ignore corruption, log it only */
#define CRYPT_ACTIVATE_IGNORE_CORRUPTION (1 << 8)
/** dm-verity: restart_on_corruption flag - restart kernel on corruption */
#define CRYPT_ACTIVATE_RESTART_ON_CORRUPTION (1 << 9)
/** dm-verity: ignore_zero_blocks - do not verify zero blocks */
#define CRYPT_ACTIVATE_IGNORE_ZERO_BLOCKS (1 << 10)
/** key loaded in kernel keyring instead directly in dm-crypt */
#define CRYPT_ACTIVATE_KEYRING_KEY (1 << 11)
/** dm-integrity: direct writes, do not use journal */
#define CRYPT_ACTIVATE_NO_JOURNAL (1 << 12)
/** dm-integrity: recovery mode - no journal, no integrity checks */
#define CRYPT_ACTIVATE_RECOVERY (1 << 13)
/** ignore persistently stored flags */
#define CRYPT_ACTIVATE_IGNORE_PERSISTENT (1 << 14)
/**
* Active device runtime attributes
*/
struct crypt_active_device {
uint64_t offset; /**< offset in sectors */
uint64_t iv_offset; /**< IV initialization sector */
uint64_t size; /**< active device size */
uint32_t flags; /**< activation flags */
};
/**
* Receive runtime attributes of active crypt device.
*
* @param cd crypt device handle (can be @e NULL)
* @param name name of active device
* @param cad preallocated active device attributes to fill
*
* @return @e 0 on success or negative errno value otherwise
*
*/
int crypt_get_active_device(struct crypt_device *cd,
const char *name,
struct crypt_active_device *cad);
/** @} */
/**
* @defgroup crypt-pflags LUKS2 Device persistent flags and requirements
* @addtogroup crypt-pflags
* @{
*/
/**
* LUKS2 header requirements
*/
/** Unfinished offline reencryption */
#define CRYPT_REQUIREMENT_OFFLINE_REENCRYPT (1 << 0)
/** unknown requirement in header (output only) */
#define CRYPT_REQUIREMENT_UNKNOWN (1 << 31)
/**
* Persistent flags type
*/
typedef enum {
CRYPT_FLAGS_ACTIVATION, /**< activation flags, @see aflags */
CRYPT_FLAGS_REQUIREMENTS /**< requirements flags */
} crypt_flags_type;
/**
* Set persistent flags.
*
* @param cd crypt device handle (can be @e NULL)
* @param type type to set (CRYPT_FLAGS_ACTIVATION or CRYPT_FLAGS_REQUIREMENTS)
* @param flags flags to set
*
* @return @e 0 on success or negative errno value otherwise
*
* @note Valid only for LUKS2.
*
* @note Not all activation flags can be stored. Only ALLOW_DISCARD,
* SAME_CPU_CRYPT, SUBMIT_FROM_CRYPT_CPU and NO_JOURNAL can be
* stored persistently.
*
* @note Only requirements flags recognised by current library may be set.
* CRYPT_REQUIREMENT_FLAG is illegal (output only) in set operation.
*/
int crypt_persistent_flags_set(struct crypt_device *cd,
crypt_flags_type type,
uint32_t flags);
/**
* Get persistent flags stored in header.
*
* @param cd crypt device handle (can be @e NULL)
* @param type flags type to retrieve (CRYPT_FLAGS_ACTIVATION or CRYPT_FLAGS_REQUIREMENTS)
* @param flags reference to output variable
*
* @return @e 0 on success or negative errno value otherwise
*/
int crypt_persistent_flags_get(struct crypt_device *cd,
crypt_flags_type type,
uint32_t *flags);
/** @} */
/**
* @defgroup crypt-activation Device activation
* @addtogroup crypt-activation
* @{
*/
/**
* Activate device or check passphrase.
*
* @param cd crypt device handle
* @param name name of device to create, if @e NULL only check passphrase
* @param keyslot requested keyslot to check or @e CRYPT_ANY_SLOT
* @param passphrase passphrase used to unlock volume key
* @param passphrase_size size of @e passphrase
* @param flags activation flags
*
* @return unlocked key slot number or negative errno otherwise.
*/
int crypt_activate_by_passphrase(struct crypt_device *cd,
const char *name,
int keyslot,
const char *passphrase,
size_t passphrase_size,
uint32_t flags);
/**
* Activate device or check using key file.
*
* @param cd crypt device handle
* @param name name of device to create, if @e NULL only check keyfile
* @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
* @param keyfile key file used to unlock volume key
* @param keyfile_size number of bytes to read from keyfile, 0 is unlimited
* @param keyfile_offset number of bytes to skip at start of keyfile
* @param flags activation flags
*
* @return unlocked key slot number or negative errno otherwise.
*/
int crypt_activate_by_keyfile_device_offset(struct crypt_device *cd,
const char *name,
int keyslot,
const char *keyfile,
size_t keyfile_size,
uint64_t keyfile_offset,
uint32_t flags);
/**
* Backward compatible crypt_activate_by_keyfile_device_offset() (with size_t offset).
*/
int crypt_activate_by_keyfile_offset(struct crypt_device *cd,
const char *name,
int keyslot,
const char *keyfile,
size_t keyfile_size,
size_t keyfile_offset,
uint32_t flags);
/**
* Backward compatible crypt_activate_by_keyfile_device_offset() (without offset).
*/
int crypt_activate_by_keyfile(struct crypt_device *cd,
const char *name,
int keyslot,
const char *keyfile,
size_t keyfile_size,
uint32_t flags);
/**
* Activate device using provided volume key.
*
* @param cd crypt device handle
* @param name name of device to create, if @e NULL only check volume key
* @param volume_key provided volume key (or @e NULL to use internal)
* @param volume_key_size size of volume_key
* @param flags activation flags
*
* @return @e 0 on success or negative errno value otherwise.
*
* @note If @e NULL is used for volume_key, device has to be initialized
* by previous operation (like @ref crypt_format
* or @ref crypt_init_by_name)
* @note For VERITY the volume key means root hash required for activation.
* Because kernel dm-verity is always read only, you have to provide
* CRYPT_ACTIVATE_READONLY flag always.
* @note For TCRYPT the volume key should be always NULL and because master
* key from decrypted header is used instead.
*/
int crypt_activate_by_volume_key(struct crypt_device *cd,
const char *name,
const char *volume_key,
size_t volume_key_size,
uint32_t flags);
/**
* Activate device using passphrase stored in kernel keyring.
*
* @param cd crypt device handle
* @param name name of device to create, if @e NULL only check passphrase in keyring
* @param key_description kernel keyring key description library should look
* for passphrase in
* @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
* @param flags activation flags
*
* @return @e unlocked keyslot number on success or negative errno value otherwise.
*
* @note Keyslot passphrase must be stored in 'user' key type
* and the key has to be reachable for process context
* on behalf of which this function is called.
*/
int crypt_activate_by_keyring(struct crypt_device *cd,
const char *name,
const char *key_description,
int keyslot,
uint32_t flags);
/** lazy deactivation - remove once last user releases it */
#define CRYPT_DEACTIVATE_DEFERRED (1 << 0)
/** force deactivation - if the device is busy, it is replaced by error device */
#define CRYPT_DEACTIVATE_FORCE (1 << 1)
/**
* Deactivate crypt device. This function tries to remove active device-mapper
* mapping from kernel. Also, sensitive data like the volume key are removed from
* memory
*
* @param cd crypt device handle, can be @e NULL
* @param name name of device to deactivate
* @param flags deactivation flags
*
* @return @e 0 on success or negative errno value otherwise.
*
*/
int crypt_deactivate_by_name(struct crypt_device *cd,
const char *name,
uint32_t flags);
/**
* Deactivate crypt device. See @ref crypt_deactivate_by_name with empty @e flags.
*/
int crypt_deactivate(struct crypt_device *cd, const char *name);
/** @} */
/**
* @defgroup crypt-key Volume Key manipulation
* @addtogroup crypt-key
* @{
*/
/**
* Get volume key from crypt device.
*
* @param cd crypt device handle
* @param keyslot use this keyslot or @e CRYPT_ANY_SLOT
* @param volume_key buffer for volume key
* @param volume_key_size on input, size of buffer @e volume_key,
* on output size of @e volume_key
* @param passphrase passphrase used to unlock volume key
* @param passphrase_size size of @e passphrase
*
* @return unlocked key slot number or negative errno otherwise.
*
* @note For TCRYPT cipher chain is the volume key concatenated
* for all ciphers in chain.
*/
int crypt_volume_key_get(struct crypt_device *cd,
int keyslot,
char *volume_key,
size_t *volume_key_size,
const char *passphrase,
size_t passphrase_size);
/**
* Verify that provided volume key is valid for crypt device.
*
* @param cd crypt device handle
* @param volume_key provided volume key
* @param volume_key_size size of @e volume_key
*
* @return @e 0 on success or negative errno value otherwise.
*/
int crypt_volume_key_verify(struct crypt_device *cd,
const char *volume_key,
size_t volume_key_size);
/** @} */
/**
* @defgroup crypt-devstat Crypt and Verity device status
* @addtogroup crypt-devstat
* @{
*/
/**
* Device status
*/
typedef enum {
CRYPT_INVALID, /**< device mapping is invalid in this context */
CRYPT_INACTIVE, /**< no such mapped device */
CRYPT_ACTIVE, /**< device is active */
CRYPT_BUSY /**< device is active and has open count > 0 */
} crypt_status_info;
/**
* Get status info about device name.
*
* @param cd crypt device handle, can be @e NULL
* @param name crypt device name
*
* @return value defined by crypt_status_info.
*
*/
crypt_status_info crypt_status(struct crypt_device *cd, const char *name);
/**
* Dump text-formatted information about crypt or verity device to log output.
*
* @param cd crypt device handle
*
* @return @e 0 on success or negative errno value otherwise.
*/
int crypt_dump(struct crypt_device *cd);
/**
* Get cipher used in device.
*
* @param cd crypt device handle
*
* @return used cipher, e.g. "aes" or @e NULL otherwise
*
*/
const char *crypt_get_cipher(struct crypt_device *cd);
/**
* Get cipher mode used in device.
*
* @param cd crypt device handle
*
* @return used cipher mode e.g. "xts-plain" or @e otherwise
*
*/
const char *crypt_get_cipher_mode(struct crypt_device *cd);
/**
* Get device UUID.
*
* @param cd crypt device handle
*
* @return device UUID or @e NULL if not set
*
*/
const char *crypt_get_uuid(struct crypt_device *cd);
/**
* Get path to underlaying device.
*
* @param cd crypt device handle
*
* @return path to underlaying device name
*
*/
const char *crypt_get_device_name(struct crypt_device *cd);
/**
* Get device offset in 512-bytes sectors where real data starts (on underlying device).
*
* @param cd crypt device handle
*
* @return device offset in sectors
*
*/
uint64_t crypt_get_data_offset(struct crypt_device *cd);
/**
* Get IV offset in 512-bytes sectors (skip).
*
* @param cd crypt device handle
*
* @return IV offset
*
*/
uint64_t crypt_get_iv_offset(struct crypt_device *cd);
/**
* Get size (in bytes) of volume key for crypt device.
*
* @param cd crypt device handle
*
* @return volume key size
*
*/
int crypt_get_volume_key_size(struct crypt_device *cd);
/**
* Get size (in bytes) of encryption sector for crypt device.
*
* @param cd crypt device handle
*
* @return sector size
*
*/
int crypt_get_sector_size(struct crypt_device *cd);
/**
* Get device parameters for VERITY device.
*
* @param cd crypt device handle
* @param vp verity device info
*
* @e 0 on success or negative errno value otherwise.
*
*/
int crypt_get_verity_info(struct crypt_device *cd,
struct crypt_params_verity *vp);
/**
* Get device parameters for INTEGRITY device.
*
* @param cd crypt device handle
* @param ip verity device info
*
* @e 0 on success or negative errno value otherwise.
*
*/
int crypt_get_integrity_info(struct crypt_device *cd,
struct crypt_params_integrity *ip);
/** @} */
/**
* @defgroup crypt-benchmark Benchmarking
* Benchmarking of algorithms
* @addtogroup crypt-benchmark
* @{
*/
/**
* Informational benchmark for ciphers.
*
* @param cd crypt device handle
* @param cipher (e.g. "aes")
* @param cipher_mode (e.g. "xts"), IV generator is ignored
* @param volume_key_size size of volume key in bytes
* @param iv_size size of IV in bytes
* @param buffer_size size of encryption buffer in bytes used in test
* @param encryption_mbs measured encryption speed in MiB/s
* @param decryption_mbs measured decryption speed in MiB/s
*
* @return @e 0 on success or negative errno value otherwise.
*
* @note If encryption_buffer_size is too small and encryption time
* cannot be properly measured, -ERANGE is returned.
*/
int crypt_benchmark(struct crypt_device *cd,
const char *cipher,
const char *cipher_mode,
size_t volume_key_size,
size_t iv_size,
size_t buffer_size,
double *encryption_mbs,
double *decryption_mbs);
/**
* Informational benchmark for PBKDF.
*
* @param cd crypt device handle
* @param pbkdf PBKDF parameters
* @param password password for benchmark
* @param password_size size of password
* @param salt salt for benchmark
* @param salt_size size of salt
* @param volume_key_size output volume key size
* @param progress callback function
* @param usrptr provided identification in callback
*
* @return @e 0 on success or negative errno value otherwise.
*/
int crypt_benchmark_pbkdf(struct crypt_device *cd,
struct crypt_pbkdf_type *pbkdf,
const char *password,
size_t password_size,
const char *salt,
size_t salt_size,
size_t volume_key_size,
int (*progress)(uint32_t time_ms, void *usrptr),
void *usrptr);
/** @} */
/**
* @addtogroup crypt-keyslot
* @{
*/
/**
* Crypt keyslot info
*/
typedef enum {
CRYPT_SLOT_INVALID, /**< invalid keyslot */
CRYPT_SLOT_INACTIVE, /**< keyslot is inactive (free) */
CRYPT_SLOT_ACTIVE, /**< keyslot is active (used) */
CRYPT_SLOT_ACTIVE_LAST /**< keylost is active (used)
* and last used at the same time */
} crypt_keyslot_info;
/**
* Get information about particular key slot.
*
* @param cd crypt device handle
* @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
*
* @return value defined by crypt_keyslot_info
*
*/
crypt_keyslot_info crypt_keyslot_status(struct crypt_device *cd, int keyslot);
/**
* Crypt keyslot priority
*/
typedef enum {
CRYPT_SLOT_PRIORITY_INVALID =-1, /**< no such slot */
CRYPT_SLOT_PRIORITY_IGNORE = 0, /**< CRYPT_ANY_SLOT will ignore it for open */
CRYPT_SLOT_PRIORITY_NORMAL = 1, /**< default priority, tried after preferred */
CRYPT_SLOT_PRIORITY_PREFER = 2, /**< will try to open first */
} crypt_keyslot_priority;
/**
* Get keyslot priority (LUKS2)
*
* @param cd crypt device handle
* @param keyslot keyslot number
*
* @return value defined by crypt_keyslot_priority
*/
crypt_keyslot_priority crypt_keyslot_get_priority(struct crypt_device *cd, int keyslot);
/**
* Set keyslot priority (LUKS2)
*
* @param cd crypt device handle
* @param keyslot keyslot number
* @param priority priority defined in crypt_keyslot_priority
*
* @return @e 0 on success or negative errno value otherwise.
*/
int crypt_keyslot_set_priority(struct crypt_device *cd, int keyslot, crypt_keyslot_priority priority);
/**
* Get number of keyslots supported for device type.
*
* @param type crypt device type
*
* @return slot count or negative errno otherwise if device
* doesn't not support keyslots.
*/
int crypt_keyslot_max(const char *type);
/**
* Get keyslot area pointers (relative to metadata device).
*
* @param cd crypt device handle
* @param keyslot keyslot number
* @param offset offset on metadata device (in bytes)
* @param length length of keyslot area (in bytes)
*
* @return @e 0 on success or negative errno value otherwise.
*
*/
int crypt_keyslot_area(struct crypt_device *cd,
int keyslot,
uint64_t *offset,
uint64_t *length);
/**
* Get directory where mapped crypt devices are created
*
* @return the directory path
*/
const char *crypt_get_dir(void);
/** @} */
/**
* @defgroup crypt-backup Device metadata backup
* @addtogroup crypt-backup
* @{
*/
/**
* Backup header and keyslots to file.
*
* @param cd crypt device handle
* @param requested_type @link crypt-type @endlink or @e NULL for all known
* @param backup_file file to backup header to
*
* @return @e 0 on success or negative errno value otherwise.
*
*/
int crypt_header_backup(struct crypt_device *cd,
const char *requested_type,
const char *backup_file);
/**
* Restore header and keyslots from backup file.
*
* @param cd crypt device handle
* @param requested_type @link crypt-type @endlink or @e NULL for all known
* @param backup_file file to restore header from
*
* @return @e 0 on success or negative errno value otherwise.
*
*/
int crypt_header_restore(struct crypt_device *cd,
const char *requested_type,
const char *backup_file);
/** @} */
/**
* @defgroup crypt-dbg Library debug level
* Set library debug level
* @addtogroup crypt-dbg
* @{
*/
/** Debug all */
#define CRYPT_DEBUG_ALL -1
/** Debug none */
#define CRYPT_DEBUG_NONE 0
/**
* Set the debug level for library
*
* @param level debug level
*
*/
void crypt_set_debug_level(int level);
/** @} */
/**
* @defgroup crypt-keyfile Function to read keyfile
* @addtogroup crypt-keyfile
* @{
*/
/**
* Read keyfile
*
* @param cd crypt device handle
* @param keyfile keyfile to read
* @param key buffer for key
* @param key_size_read size of read key
* @param keyfile_offset keyfile offset
* @param keyfile_size_max maximal size of keyfile to read
* @param flags keyfile read flags
*
* @return @e 0 on success or negative errno value otherwise.
*/
int crypt_keyfile_device_read(struct crypt_device *cd,
const char *keyfile,
char **key, size_t *key_size_read,
uint64_t keyfile_offset,
size_t keyfile_size_max,
uint32_t flags);
/**
* Backward compatible crypt_keyfile_device_read() (with size_t offset).
*/
int crypt_keyfile_read(struct crypt_device *cd,
const char *keyfile,
char **key, size_t *key_size_read,
size_t keyfile_offset,
size_t keyfile_size_max,
uint32_t flags);
/** Read key only to the first end of line (\\n). */
#define CRYPT_KEYFILE_STOP_EOL (1 << 0)
/** @} */
/**
* @defgroup crypt-wipe Function to wipe device
* @addtogroup crypt-wipe
* @{
*/
/**
* Wipe pattern
*/
typedef enum {
CRYPT_WIPE_ZERO, /**< Fill with zeroes */
CRYPT_WIPE_RANDOM, /**< Use RNG to fill data */
CRYPT_WIPE_ENCRYPTED_ZERO, /**< Add encryption and fill with zeroes as plaintext */
CRYPT_WIPE_SPECIAL, /**< Compatibility only, do not use (Gutmann method) */
} crypt_wipe_pattern;
/**
* Wipe/Fill (part of) a device with the selected pattern.
*
* @param cd crypt device handle
* @param dev_path path to device to wipe or @e NULL if data device should be used
* @param pattern selected wipe pattern
* @param offset offset on device (in bytes)
* @param length length of area to be wiped (in bytes)
* @param wipe_block_size used block for wiping (one step) (in bytes)
* @param flags wipe flags
* @param progress callback function called after each @e wipe_block_size or @e NULL
* @param usrptr provided identification in callback
*
* @return @e 0 on success or negative errno value otherwise.
*
* @note A @e progress callback can interrupt wipe process by returning non-zero code.
*
* @note If the error values is -EIO or -EINTR, some part of the device could
* be overwritten. Other error codes (-EINVAL, -ENOMEM) means that no IO was performed.
*/
int crypt_wipe(struct crypt_device *cd,
const char *dev_path, /* if null, use data device */
crypt_wipe_pattern pattern,
uint64_t offset,
uint64_t length,
size_t wipe_block_size,
uint32_t flags,
int (*progress)(uint64_t size, uint64_t offset, void *usrptr),
void *usrptr
);
/** Use direct-io */
#define CRYPT_WIPE_NO_DIRECT_IO (1 << 0)
/** @} */
/**
* @defgroup crypt-tokens LUKS2 token wrapper access
*
* Utilities for handling tokens LUKS2
* Token is a device or a method how to read password for particular keyslot
* automatically. It can be chunk of data stored on hardware token or
* just a metadata how to generate the password.
*
* @addtogroup crypt-tokens
* @{
*/
/** Iterate through all tokens */
#define CRYPT_ANY_TOKEN -1
/**
* Get content of a token definition in JSON format.
*
* @param cd crypt device handle
* @param token token id
* @param json buffer with JSON
*
* @return allocated token id or negative errno otherwise.
*/
int crypt_token_json_get(struct crypt_device *cd,
int token,
const char **json);
/**
* Store content of a token definition in JSON format.
*
* @param cd crypt device handle
* @param token token id or @e CRYPT_ANY_TOKEN to allocate new one
* @param json buffer with JSON or @e NULL to remove token
*
* @return allocated token id or negative errno otherwise.
*
* @note The buffer must be in proper JSON format and must contain at least
* string "type" with slot type and an array of string names "keyslots".
* Keyslots array contains assignments to particular slots and can be empty.
*/
int crypt_token_json_set(struct crypt_device *cd,
int token,
const char *json);
/**
* Token info
*/
typedef enum {
CRYPT_TOKEN_INVALID, /**< token is invalid */
CRYPT_TOKEN_INACTIVE, /**< token is empty (free) */
CRYPT_TOKEN_INTERNAL, /**< active internal token with driver */
CRYPT_TOKEN_INTERNAL_UNKNOWN, /**< active internal token (reserved name) with missing token driver */
CRYPT_TOKEN_EXTERNAL, /**< active external (user defined) token with driver */
CRYPT_TOKEN_EXTERNAL_UNKNOWN, /**< active external (user defined) token with missing token driver */
} crypt_token_info;
/**
* Get info for specific token.
*
* @param cd crypt device handle
* @param token existing token id
* @param type pointer for returned type string
*
* @return token status info. For any returned status (besides CRYPT_TOKEN_INVALID
* and CRYPT_TOKEN_INACTIVE) and if type parameter is not NULL it will
* contain address of type string.
*
* @note if required, create a copy of string referenced in *type before calling next
* libcryptsetup API function. The reference may become invalid.
*/
crypt_token_info crypt_token_status(struct crypt_device *cd, int token, const char **type);
/**
* LUKS2 keyring token parameters.
*
* @see crypt_token_builtin_set
*
*/
struct crypt_token_params_luks2_keyring {
const char *key_description; /**< Reference in keyring */
};
/**
* Create a new luks2 keyring token.
*
* @param cd crypt device handle
* @param token token id or @e CRYPT_ANY_TOKEN to allocate new one
* @param params luks2 keyring token params
*
* @return allocated token id or negative errno otherwise.
*
*/
int crypt_token_luks2_keyring_set(struct crypt_device *cd,
int token,
const struct crypt_token_params_luks2_keyring *params);
/**
* Get LUKS2 keyring token params
*
* @param cd crypt device handle
* @param token existing luks2 keyring token id
* @param params returned luks2 keyring token params
*
* @return allocated token id or negative errno otherwise.
*
* @note do not call free() on params members. Members are valid only
* until next libcryptsetup function is called.
*/
int crypt_token_luks2_keyring_get(struct crypt_device *cd,
int token,
struct crypt_token_params_luks2_keyring *params);
/**
* Assign a token to particular keyslot.
* (There can be more keyslots assigned to one token id.)
*
* @param cd crypt device handle
* @param token token id
* @param keyslot keyslot to be assigned to token (CRYPT_ANY SLOT
* assigns all active keyslots to token)
*
* @return allocated token id or negative errno otherwise.
*/
int crypt_token_assign_keyslot(struct crypt_device *cd,
int token,
int keyslot);
/**
* Unassign a token from particular keyslot.
* (There can be more keyslots assigned to one token id.)
*
* @param cd crypt device handle
* @param token token id
* @param keyslot keyslot to be unassigned from token (CRYPT_ANY SLOT
* unassigns all active keyslots from token)
*
* @return allocated token id or negative errno otherwise.
*/
int crypt_token_unassign_keyslot(struct crypt_device *cd,
int token,
int keyslot);
/**
* Get info about token assignment to particular keyslot.
*
* @param cd crypt device handle
* @param token token id
* @param keyslot keyslot
*
* @return 0 on success (token exists and is assigned to the keyslot),
* -ENOENT if token is not assigned to a keyslot (token, keyslot
* or both may be inactive) or other negative errno otherwise.
*/
int crypt_token_is_assigned(struct crypt_device *cd,
int token,
int keyslot);
/**
* Token handler open function prototype.
* This function retrieves password from a token and return allocated buffer
* containing this password. This buffer has to be deallocated by calling
* free() function and content should be wiped before deallocation.
*
* @param cd crypt device handle
* @param token token id
* @param buffer returned allocated buffer with password
* @param buffer_len length of the buffer
* @param usrptr user data in @link crypt_activate_by_token @endlink
*/
typedef int (*crypt_token_open_func) (
struct crypt_device *cd,
int token,
char **buffer,
size_t *buffer_len,
void *usrptr);
/**
* Token handler buffer free function prototype.
* This function is used by library to free the buffer with keyslot
* passphrase when it's no longer needed. If not defined the library
* overwrites buffer with zeroes and call free().
*
* @param buffer the buffer with keyslot passphrase
* @param buffer_len the buffer length
*/
typedef void (*crypt_token_buffer_free_func) (void *buffer, size_t buffer_len);
/**
* Token handler validate function prototype.
* This fuction validates JSON representation of user defined token for additional data
* specific for its token type. If defined in the handler, it's called
* during @link crypt_activate_by_token @endlink. It may also be called during
* @link crypt_token_json_set @endlink when appropriate token handler was registered before
* with @link crypt_token_register @endlink.
*
* @param cd crypt device handle
* @param json buffer with JSON
*/
typedef int (*crypt_token_validate_func) (struct crypt_device *cd, const char *json);
/**
* Token handler dump function prototype.
* This fuction is supposed to print token implementation specific details. It gets
* called during @link crypt_dump @endlink if token handler was registered before.
*
* @param cd crypt device handle
* @param json buffer with token JSON
*
* @note dump implementations are advised to use @link crypt_log @endlink function
* to dump token details.
*/
typedef void (*crypt_token_dump_func) (struct crypt_device *cd, const char *json);
/**
* Token handler
*/
typedef struct {
const char *name; /**< token handler name */
crypt_token_open_func open; /**< token handler open function */
crypt_token_buffer_free_func buffer_free; /**< token handler buffer_free function (optional) */
crypt_token_validate_func validate; /**< token handler validate function (optional) */
crypt_token_dump_func dump; /**< token handler dump function (optional) */
} crypt_token_handler;
/**
* Register token handler
*
* @param handler token handler to register
*
* @return @e 0 on success or negative errno value otherwise.
*/
int crypt_token_register(const crypt_token_handler *handler);
/**
* Activate device or check key using a token.
*
* @param cd crypt device handle
* @param name name of device to create, if @e NULL only check token
* @param token requested token to check or CRYPT_ANY_TOKEN to check all
* @param usrptr provided identification in callback
* @param flags activation flags
*
* @return unlocked key slot number or negative errno otherwise.
*/
int crypt_activate_by_token(struct crypt_device *cd,
const char *name,
int token,
void *usrptr,
uint32_t flags);
/** @} */
#ifdef __cplusplus
}
#endif
#endif /* _LIBCRYPTSETUP_H */
|