3 * Common testing for encryption modes
5 * (c) 2018 Straylight/Edgeware
8 /*----- Licensing notice --------------------------------------------------*
10 * This file is part of Catacomb.
12 * Catacomb is free software: you can redistribute it and/or modify it
13 * under the terms of the GNU Library General Public License as published
14 * by the Free Software Foundation; either version 2 of the License, or
15 * (at your option) any later version.
17 * Catacomb is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * Library General Public License for more details.
22 * You should have received a copy of the GNU Library General Public
23 * License along with Catacomb. If not, write to the Free Software
24 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
28 #ifndef CATACOMB_MODES_TEST_H
29 #define CATACOMB_MODES_TEST_H
35 /*----- Header files ------------------------------------------------------*/
37 #include <mLib/bits.h>
39 /*----- Data structures ---------------------------------------------------*/
41 /* Functions used by `test_encmode' below. */
42 typedef void setupfn(const octet */
*k*/
, size_t /*ksz*/);
43 typedef void resetfn(const octet */
*iv*/
);
44 typedef void encfn(const octet */
*s*/
, octet */
*d*/
, size_t /*sz*/);
46 /*----- Functions provided ------------------------------------------------*/
48 #define TEMF_REFALIGN 1u /* misalignment of pieces affects
49 * the encryption state
52 /* --- @test_encmode@ --- *
54 * Arguments: @const char *name@ = name of the encryption scheme; used to
55 * find the regression-test filename
56 * @size_t ksz@ = key size to use, or zero for `don't care'
57 * @size_t blksz@ = block size
58 * @size_t minsz@ = smallest acceptable buffer size, or 1
59 * @unsigned f@ = various additional flags
60 * @setupfn *setup@ = key-setup function
61 * @resetfn *reset@ = state-reset function
62 * @encfn *enc@ = encryption function
63 * @decfn *dec@ = decryption function
64 * @int argc@ = number of command-line arguments
65 * @char *argv@ = pointer to command-line argument vector
67 * Returns: Zero on success, nonzero to report failure.
69 * Use: Tests an encryption mode which doesn't have any more formal
72 * The @name@ is used firstly in diagnostic output and secondly
73 * to form the default filename to use for regression-test data,
74 * as `.../symm/t/modes/NAME.regress'.
76 * The key size @ksz@ is simply passed on back to the @setup@
77 * function, unless the caller passes in zero, in which case
78 * @test_encmode@ chooses a key size for itself.
80 * The block size @blksz@ is used in failure reports, to draw
81 * attention to the block structure in the various buffers,
82 * which may assist with diagnosis. It's also used to determine
83 * when to apply a consistency check: see below regarding the
84 * @TEMF_REFALIGN@ flag.
86 * The minimum buffer size @minsz@ expresses a limitation on the
87 * provided @enc@ and @dec@ functions, that they don't work on
88 * inputs smaller than @minsz@; accordingly, @test_encmode@ will
89 * not test such small sizes. This should be 1 if the mode has
92 * The flags @f@ influence testing in various ways explained
95 * The caller-provided functions are assumed to act on some
96 * global but hidden state,
98 * * @setup@ is (currently, at least) called only once, with
99 * the key @k@ and its chosen size @ksz@.
101 * * @reset@ is called at the start of each encryption or
102 * decryption operation, to program in the initialization
103 * vector to use. Currently, the same IV is used in all of
104 * the tests, but this might not always be the case.
106 * * @enc@ is called to encrypt a source buffer @s@ and write
107 * the ciphertext to a destination @d@; @sz@ is the common
108 * size of these buffers. @d@ might be null, to discard
109 * output; @s@ might be null, to process all-zero input.
111 * * @dec@ is called to decrypt a source buffer @s@ and write
112 * the recovered plaintext to a destination @d@; @sz@ is the
113 * common size of these buffers.
115 * Finally, @int argc@ and @char *argv@ are the command-line
116 * arguments provided to @main@; @test_encmode@ parses these and
117 * alters its behaviour accordingly.
119 * Currently, @test_encmode@'s tests are built around a single,
120 * fairly large, fixed message. In each test step, the message
121 * is split into a number of fragments which are encrypted and
124 * The following tests are performed.
126 * * The fundamental `round-trip' test, which verifies that
127 * the message can be encrypted and then decrypted
128 * successfully, if the same fragment boundaries are used in
131 * * A `consistency' test. Some modes, such as CFB, OFB, and
132 * counter, are `resumable': encryption operations are
133 * insensitive to the position of fragment boundaries, so a
134 * single message can be broken into fragments without
135 * affecting the result. If @TEMF_REFALIGN@ is clear then
136 * the mode under test is verified to have this property.
137 * If @TEMF_REFALIGN' is set, a weaker property is verified:
138 * that encryption is insensitive to the position of
139 * /block-aligned/ fragment boundaries only.
141 * * A `regression' test, which verifies that the code
142 * produces the same ciphertext as a previous version. By
143 * setting command-line arguments appropriately, a test
144 * program can be told to record ciphertexts in a (binary)
145 * data file. Usually, instead, the program will read the
146 * recorded ciphertexts back and verify that it produces the
147 * same data. For resumable modes, it's only necessary to
148 * record single ciphertext, since all the other ciphertexts
149 * must be equal by consistency; otherwise all non-block-
150 * aligned splits are recorded separately.
153 extern int test_encmode(const char */
*name*/
,
154 size_t /*ksz*/, size_t /*blksz*/,
155 size_t /*minsz */, unsigned /*f*/,
156 setupfn */
*setup*/
, resetfn */
*reset*/
,
157 encfn */
*enc*/
, encfn */
*dec*/
,
158 int /*argc*/, char */
*argv*/
[]);
160 /*----- That's all, folks -------------------------------------------------*/