Merge remote-tracking branch 'remotes/mjt/tags/pull-trivial-patches-2016-05-18' into...

[mirror_qemu.git] / include / crypto / afsplit.h

/*
 * QEMU Crypto anti forensic information splitter
 *
 * Copyright (c) 2015-2016 Red Hat, Inc.
 *
 * This library 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 library 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 library; if not, see <http://www.gnu.org/licenses/>.
 *
 */

#ifndef QCRYPTO_AFSPLIT_H__
#define QCRYPTO_AFSPLIT_H__

#include "crypto/hash.h"

/**
 * This module implements the anti-forensic splitter that is specified
 * as part of the LUKS format:
 *
 *   http://clemens.endorphin.org/cryptography
 *   http://clemens.endorphin.org/TKS1-draft.pdf
 *
 * The core idea is to take a short piece of data (key material)
 * and process it to expand it to a much larger piece of data.
 * The expansion process is reversible, to obtain the original
 * short data. The key property of the expansion is that if any
 * byte in the larger data set is changed / missing, it should be
 * impossible to recreate the original short data.
 *
 * <example>
 *    <title>Creating a large split key for storage</title>
 *    <programlisting>
 * size_t nkey = 32;
 * uint32_t stripes = 32768; // To produce a 1 MB split key
 * uint8_t *masterkey = ....a 32-byte AES key...
 * uint8_t *splitkey;
 *
 * splitkey = g_new0(uint8_t, nkey * stripes);
 *
 * if (qcrypto_afsplit_encode(QCRYPTO_HASH_ALG_SHA256,
 *                            nkey, stripes,
 *                            masterkey, splitkey, errp) < 0) {
 *     g_free(splitkey);
 *     g_free(masterkey);
 *     return -1;
 * }
 *
 * ...store splitkey somewhere...
 *
 * g_free(splitkey);
 * g_free(masterkey);
 *    </programlisting>
 * </example>
 *
 * <example>
 *    <title>Retrieving a master key from storage</title>
 *    <programlisting>
 * size_t nkey = 32;
 * uint32_t stripes = 32768; // To produce a 1 MB split key
 * uint8_t *masterkey;
 * uint8_t *splitkey = .... read in 1 MB of data...
 *
 * masterkey = g_new0(uint8_t, nkey);
 *
 * if (qcrypto_afsplit_decode(QCRYPTO_HASH_ALG_SHA256,
 *                            nkey, stripes,
 *                            splitkey, masterkey, errp) < 0) {
 *     g_free(splitkey);
 *     g_free(masterkey);
 *     return -1;
 * }
 *
 * ..decrypt data with masterkey...
 *
 * g_free(splitkey);
 * g_free(masterkey);
 *    </programlisting>
 * </example>
 */

/**
 * qcrypto_afsplit_encode:
 * @hash: the hash algorithm to use for data expansion
 * @blocklen: the size of @in in bytes
 * @stripes: the number of times to expand @in in size
 * @in: the master key to be expanded in size
 * @out: preallocated buffer to hold the split key
 * @errp: pointer to a NULL-initialized error object
 *
 * Split the data in @in, which is @blocklen bytes in
 * size, to form a larger piece of data @out, which is
 * @blocklen * @stripes bytes in size.
 *
 * Returns: 0 on success, -1 on error;
 */
int qcrypto_afsplit_encode(QCryptoHashAlgorithm hash,
                           size_t blocklen,
                           uint32_t stripes,
                           const uint8_t *in,
                           uint8_t *out,
                           Error **errp);

/**
 * qcrypto_afsplit_decode:
 * @hash: the hash algorithm to use for data compression
 * @blocklen: the size of @out in bytes
 * @stripes: the number of times to decrease @in in size
 * @in: the split key to be recombined
 * @out: preallocated buffer to hold the master key
 * @errp: pointer to a NULL-initialized error object
 *
 * Join the data in @in, which is @blocklen * @stripes
 * bytes in size, to form the original small piece of
 * data @out, which is @blocklen bytes in size.
 *
 * Returns: 0 on success, -1 on error;
 */
int qcrypto_afsplit_decode(QCryptoHashAlgorithm hash,
                           size_t blocklen,
                           uint32_t stripes,
                           const uint8_t *in,
                           uint8_t *out,
                           Error **errp);

#endif /* QCRYPTO_AFSPLIT_H__ */