afsplit.h (4374B)
1 /* 2 * QEMU Crypto anti forensic information splitter 3 * 4 * Copyright (c) 2015-2016 Red Hat, Inc. 5 * 6 * This program is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU General Public License 8 * as published by the Free Software Foundation; either version 2 9 * of the License, or (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 GNU 14 * General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, see <http://www.gnu.org/licenses/>. 18 */ 19 20 #ifndef QCRYPTO_AFSPLIT_H 21 #define QCRYPTO_AFSPLIT_H 22 23 #include "crypto/hash.h" 24 25 /** 26 * This module implements the anti-forensic splitter that is specified 27 * as part of the LUKS format: 28 * 29 * http://clemens.endorphin.org/cryptography 30 * http://clemens.endorphin.org/TKS1-draft.pdf 31 * 32 * The core idea is to take a short piece of data (key material) 33 * and process it to expand it to a much larger piece of data. 34 * The expansion process is reversible, to obtain the original 35 * short data. The key property of the expansion is that if any 36 * byte in the larger data set is changed / missing, it should be 37 * impossible to recreate the original short data. 38 * 39 * <example> 40 * <title>Creating a large split key for storage</title> 41 * <programlisting> 42 * size_t nkey = 32; 43 * uint32_t stripes = 32768; // To produce a 1 MB split key 44 * uint8_t *masterkey = ....a 32-byte AES key... 45 * uint8_t *splitkey; 46 * 47 * splitkey = g_new0(uint8_t, nkey * stripes); 48 * 49 * if (qcrypto_afsplit_encode(QCRYPTO_HASH_ALG_SHA256, 50 * nkey, stripes, 51 * masterkey, splitkey, errp) < 0) { 52 * g_free(splitkey); 53 * g_free(masterkey); 54 * return -1; 55 * } 56 * 57 * ...store splitkey somewhere... 58 * 59 * g_free(splitkey); 60 * g_free(masterkey); 61 * </programlisting> 62 * </example> 63 * 64 * <example> 65 * <title>Retrieving a master key from storage</title> 66 * <programlisting> 67 * size_t nkey = 32; 68 * uint32_t stripes = 32768; // To produce a 1 MB split key 69 * uint8_t *masterkey; 70 * uint8_t *splitkey = .... read in 1 MB of data... 71 * 72 * masterkey = g_new0(uint8_t, nkey); 73 * 74 * if (qcrypto_afsplit_decode(QCRYPTO_HASH_ALG_SHA256, 75 * nkey, stripes, 76 * splitkey, masterkey, errp) < 0) { 77 * g_free(splitkey); 78 * g_free(masterkey); 79 * return -1; 80 * } 81 * 82 * ..decrypt data with masterkey... 83 * 84 * g_free(splitkey); 85 * g_free(masterkey); 86 * </programlisting> 87 * </example> 88 */ 89 90 /** 91 * qcrypto_afsplit_encode: 92 * @hash: the hash algorithm to use for data expansion 93 * @blocklen: the size of @in in bytes 94 * @stripes: the number of times to expand @in in size 95 * @in: the master key to be expanded in size 96 * @out: preallocated buffer to hold the split key 97 * @errp: pointer to a NULL-initialized error object 98 * 99 * Split the data in @in, which is @blocklen bytes in 100 * size, to form a larger piece of data @out, which is 101 * @blocklen * @stripes bytes in size. 102 * 103 * Returns: 0 on success, -1 on error; 104 */ 105 int qcrypto_afsplit_encode(QCryptoHashAlgorithm hash, 106 size_t blocklen, 107 uint32_t stripes, 108 const uint8_t *in, 109 uint8_t *out, 110 Error **errp); 111 112 /** 113 * qcrypto_afsplit_decode: 114 * @hash: the hash algorithm to use for data compression 115 * @blocklen: the size of @out in bytes 116 * @stripes: the number of times to decrease @in in size 117 * @in: the split key to be recombined 118 * @out: preallocated buffer to hold the master key 119 * @errp: pointer to a NULL-initialized error object 120 * 121 * Join the data in @in, which is @blocklen * @stripes 122 * bytes in size, to form the original small piece of 123 * data @out, which is @blocklen bytes in size. 124 * 125 * Returns: 0 on success, -1 on error; 126 */ 127 int qcrypto_afsplit_decode(QCryptoHashAlgorithm hash, 128 size_t blocklen, 129 uint32_t stripes, 130 const uint8_t *in, 131 uint8_t *out, 132 Error **errp); 133 134 #endif /* QCRYPTO_AFSPLIT_H */