luksmeta/luksmeta.h

/* vim: set tabstop=8 shiftwidth=4 softtabstop=4 expandtab smarttab colorcolumn=80: */
/*
 * Copyright (c) 2016 Red Hat, Inc.
 * Author: Nathaniel McCallum <npmccallum@redhat.com>
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 2.1 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 Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

#pragma once

#include <libcryptsetup.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef uint8_t luksmeta_uuid_t[16];

/**
 * Checks for the existence of a valid LUKSMeta header on a LUKSv1 device
 *
 * @param cd crypt device handle
 * @return Zero on success or negative errno value otherwise.
 *
 * @note This function returns -ENOENT if the device has no luksmeta header.
 * @note This function returns -EINVAL if the header or slot data is corrupted.
 */
int
luksmeta_test(struct crypt_device *cd);

/**
 * Zeroes the entire LUKSMeta storage space.
 *
 * @param cd crypt device handle
 * @return Zero on success or negative errno value otherwise.
 */
int
luksmeta_nuke(struct crypt_device *cd);

/**
 * Initializes metadata storage on a LUKSv1 device
 *
 * @param cd crypt device handle
 * @return Zero on success or negative errno value otherwise.
 *
 * @note This function returns -EALREADY if a valid header already exists.
 * @note This function returns -ENOSPC if there is insufficient space.
 */
int
luksmeta_init(struct crypt_device *cd);

/**
 * Gets metadata from the specified slot
 *
 * If buf is NULL, this function returns the size of the buffer needed and
 * the uuid.
 *
 * @param cd crypt device handle
 * @param slot requested metadata slot
 * @param uuid the UUID of the metadata (output)
 * @param buf output buffer for metadata (output)
 * @param size size of buf
 * @return The number of bytes in the metadata or negative errno value.
 *
 * @note This function returns -ENOENT if the device has no luksmeta header.
 * @note This function returns -EINVAL if the header or slot data is corrupted.
 * @note This function returns -EBADSLT if the specified slot is invalid.
 * @note This function returns -ENODATA if the specified slot is empty.
 * @note This function returns -E2BIG if the output buffer is too small.
 */
int
luksmeta_load(struct crypt_device *cd, int slot,
              luksmeta_uuid_t uuid, void *buf, size_t size);

/**
 * Sets metadata to the specified slot
 *
 * The slot parameter may be CRYPT_ANY_SLOT.
 *
 * @param cd crypt device handle
 * @param slot requested metadata slot
 * @param uuid UUID of the metadata
 * @param buf input buffer for metadata
 * @param size size of buf
 * @return The slot number to which data was written or negative errno value.
 *
 * @note This function returns -ENOENT if the device has no luksmeta header.
 * @note This function returns -EINVAL if the header is corrupted.
 * @note This function returns -EBADSLT if the specified slot is invalid.
 * @note This function returns -EKEYREJECTED if the uuid is invalid/reserved.
 * @note This function returns -EALREADY if the specified slot is not empty.
 * @note This function returns -ENOSPC if there is insufficient space.
 */
int
luksmeta_save(struct crypt_device *cd, int slot,
              const luksmeta_uuid_t uuid, const void *buf, size_t size);

/**
 * Deletes metadata from the specified slot
 *
 * If uuid is not NULL, this function will confirm that the specified slot
 * has a matching UUID before deletion.
 *
 * @param cd crypt device handle
 * @param slot requested metadata slot
 * @param uuid expected UUID (optional)
 * @return Zero on success or negative errno value otherwise.
 *
 * @note This function returns -ENOENT if the device has no luksmeta header.
 * @note This function returns -EINVAL if the header is corrupted.
 * @note This function returns -EBADSLT if the specified slot is invalid.
 * @note This function returns -EKEYREJECTED if the uuid doesn't match.
 * @note This function returns -EALREADY if the specified slot is empty.
 */
int
luksmeta_wipe(struct crypt_device *cd, int slot, const luksmeta_uuid_t uuid);

#ifdef __cplusplus
}
#endif