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