luksmeta.h 4.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131
  1. /* vim: set tabstop=8 shiftwidth=4 softtabstop=4 expandtab smarttab colorcolumn=80: */
  2. /*
  3. * Copyright (c) 2016 Red Hat, Inc.
  4. * Author: Nathaniel McCallum <npmccallum@redhat.com>
  5. *
  6. * This program is free software: you can redistribute it and/or modify it
  7. * under the terms of the GNU Lesser General Public License as published by
  8. * the Free Software Foundation, either version 2.1 of the License, or
  9. * (at your option) any later version.
  10. *
  11. * This program is distributed in the hope that it will be useful,
  12. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14. * GNU Lesser General Public License for more details.
  15. *
  16. * You should have received a copy of the GNU Lesser General Public License
  17. * along with this program. If not, see <http://www.gnu.org/licenses/>.
  18. */
  19. #pragma once
  20. #include <libcryptsetup.h>
  21. #ifdef __cplusplus
  22. extern "C" {
  23. #endif
  24. typedef uint8_t luksmeta_uuid_t[16];
  25. /**
  26. * Checks for the existence of a valid LUKSMeta header on a LUKSv1 device
  27. *
  28. * @param cd crypt device handle
  29. * @return Zero on success or negative errno value otherwise.
  30. *
  31. * @note This function returns -ENOENT if the device has no luksmeta header.
  32. * @note This function returns -EINVAL if the header or slot data is corrupted.
  33. */
  34. int
  35. luksmeta_test(struct crypt_device *cd);
  36. /**
  37. * Zeroes the entire LUKSMeta storage space.
  38. *
  39. * @param cd crypt device handle
  40. * @return Zero on success or negative errno value otherwise.
  41. */
  42. int
  43. luksmeta_nuke(struct crypt_device *cd);
  44. /**
  45. * Initializes metadata storage on a LUKSv1 device
  46. *
  47. * @param cd crypt device handle
  48. * @return Zero on success or negative errno value otherwise.
  49. *
  50. * @note This function returns -EALREADY if a valid header already exists.
  51. * @note This function returns -ENOSPC if there is insufficient space.
  52. */
  53. int
  54. luksmeta_init(struct crypt_device *cd);
  55. /**
  56. * Gets metadata from the specified slot
  57. *
  58. * If buf is NULL, this function returns the size of the buffer needed and
  59. * the uuid.
  60. *
  61. * @param cd crypt device handle
  62. * @param slot requested metadata slot
  63. * @param uuid the UUID of the metadata (output)
  64. * @param buf output buffer for metadata (output)
  65. * @param size size of buf
  66. * @return The number of bytes in the metadata or negative errno value.
  67. *
  68. * @note This function returns -ENOENT if the device has no luksmeta header.
  69. * @note This function returns -EINVAL if the header or slot data is corrupted.
  70. * @note This function returns -EBADSLT if the specified slot is invalid.
  71. * @note This function returns -ENODATA if the specified slot is empty.
  72. * @note This function returns -E2BIG if the output buffer is too small.
  73. */
  74. int
  75. luksmeta_load(struct crypt_device *cd, int slot,
  76. luksmeta_uuid_t uuid, void *buf, size_t size);
  77. /**
  78. * Sets metadata to the specified slot
  79. *
  80. * The slot parameter may be CRYPT_ANY_SLOT.
  81. *
  82. * @param cd crypt device handle
  83. * @param slot requested metadata slot
  84. * @param uuid UUID of the metadata
  85. * @param buf input buffer for metadata
  86. * @param size size of buf
  87. * @return The slot number to which data was written or negative errno value.
  88. *
  89. * @note This function returns -ENOENT if the device has no luksmeta header.
  90. * @note This function returns -EINVAL if the header is corrupted.
  91. * @note This function returns -EBADSLT if the specified slot is invalid.
  92. * @note This function returns -EKEYREJECTED if the uuid is invalid/reserved.
  93. * @note This function returns -EALREADY if the specified slot is not empty.
  94. * @note This function returns -ENOSPC if there is insufficient space.
  95. */
  96. int
  97. luksmeta_save(struct crypt_device *cd, int slot,
  98. const luksmeta_uuid_t uuid, const void *buf, size_t size);
  99. /**
  100. * Deletes metadata from the specified slot
  101. *
  102. * If uuid is not NULL, this function will confirm that the specified slot
  103. * has a matching UUID before deletion.
  104. *
  105. * @param cd crypt device handle
  106. * @param slot requested metadata slot
  107. * @param uuid expected UUID (optional)
  108. * @return Zero on success or negative errno value otherwise.
  109. *
  110. * @note This function returns -ENOENT if the device has no luksmeta header.
  111. * @note This function returns -EINVAL if the header is corrupted.
  112. * @note This function returns -EBADSLT if the specified slot is invalid.
  113. * @note This function returns -EKEYREJECTED if the uuid doesn't match.
  114. * @note This function returns -EALREADY if the specified slot is empty.
  115. */
  116. int
  117. luksmeta_wipe(struct crypt_device *cd, int slot, const luksmeta_uuid_t uuid);
  118. #ifdef __cplusplus
  119. }
  120. #endif