1 /* Copyright (c) 2015, Google Inc.
2 *
3 * Permission to use, copy, modify, and/or distribute this software for any
4 * purpose with or without fee is hereby granted, provided that the above
5 * copyright notice and this permission notice appear in all copies.
6 *
7 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
10 * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
12 * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
13 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
14
15 #ifndef OPENSSL_HEADER_CRYPTO_TEST_FILE_TEST_H
16 #define OPENSSL_HEADER_CRYPTO_TEST_FILE_TEST_H
17
18 #include <openssl/base.h>
19
20 #include <stdint.h>
21 #include <stdio.h>
22
23 OPENSSL_MSVC_PRAGMA(warning(push))
24 OPENSSL_MSVC_PRAGMA(warning(disable: 4702))
25
26 #include <string>
27 #include <map>
28 #include <set>
29 #include <vector>
30
OPENSSL_MSVC_PRAGMA(warning (pop))31 OPENSSL_MSVC_PRAGMA(warning(pop))
32
33 // File-based test framework.
34 //
35 // This module provides a file-based test framework. The file format is based on
36 // that of OpenSSL upstream's evp_test and BoringSSL's aead_test. Each input
37 // file is a sequence of attributes and blank lines.
38 //
39 // Each attribute has the form:
40 //
41 // Name = Value
42 //
43 // Either '=' or ':' may be used to delimit the name from the value. Both the
44 // name and value have leading and trailing spaces stripped.
45 //
46 // Lines beginning with # are ignored.
47 //
48 // A test is a sequence of one or more attributes followed by a blank line.
49 // Blank lines are otherwise ignored. For tests that process multiple kinds of
50 // test cases, the first attribute is parsed out as the test's type and
51 // parameter. Otherwise, attributes are unordered. The first attribute is also
52 // included in the set of attributes, so tests which do not dispatch may ignore
53 // this mechanism.
54 //
55 // Functions in this module freely output to |stderr| on failure. Tests should
56 // also do so, and it is recommended they include the corresponding test's line
57 // number in any output. |PrintLine| does this automatically.
58 //
59 // Each attribute in a test must be consumed. When a test completes, if any
60 // attributes haven't been processed, the framework reports an error.
61
62
63 class FileTest {
64 public:
65 explicit FileTest(const char *path);
66 ~FileTest();
67
68 // is_open returns true if the file was successfully opened.
69 bool is_open() const { return file_ != nullptr; }
70
71 enum ReadResult {
72 kReadSuccess,
73 kReadEOF,
74 kReadError,
75 };
76
77 // ReadNext reads the next test from the file. It returns |kReadSuccess| if
78 // successfully reading a test and |kReadEOF| at the end of the file. On
79 // error or if the previous test had unconsumed attributes, it returns
80 // |kReadError|.
81 ReadResult ReadNext();
82
83 // PrintLine is a variant of printf which prepends the line number and appends
84 // a trailing newline.
85 void PrintLine(const char *format, ...) OPENSSL_PRINTF_FORMAT_FUNC(2, 3);
86
87 unsigned start_line() const { return start_line_; }
88
89 // GetType returns the name of the first attribute of the current test.
90 const std::string &GetType();
91 // GetParameter returns the value of the first attribute of the current test.
92 const std::string &GetParameter();
93
94 // HasAttribute returns true if the current test has an attribute named |key|.
95 bool HasAttribute(const std::string &key);
96
97 // GetAttribute looks up the attribute with key |key|. It sets |*out_value| to
98 // the value and returns true if it exists and returns false with an error to
99 // |stderr| otherwise.
100 bool GetAttribute(std::string *out_value, const std::string &key);
101
102 // GetAttributeOrDie looks up the attribute with key |key| and aborts if it is
103 // missing. It should only be used after a |HasAttribute| call.
104 const std::string &GetAttributeOrDie(const std::string &key);
105
106 // GetBytes looks up the attribute with key |key| and decodes it as a byte
107 // string. On success, it writes the result to |*out| and returns
108 // true. Otherwise it returns false with an error to |stderr|. The value may
109 // be either a hexadecimal string or a quoted ASCII string. It returns true on
110 // success and returns false with an error to |stderr| on failure.
111 bool GetBytes(std::vector<uint8_t> *out, const std::string &key);
112
113 // ExpectBytesEqual returns true if |expected| and |actual| are equal.
114 // Otherwise, it returns false and prints a message to |stderr|.
115 bool ExpectBytesEqual(const uint8_t *expected, size_t expected_len,
116 const uint8_t *actual, size_t actual_len);
117
118 private:
119 void ClearTest();
120 void OnKeyUsed(const std::string &key);
121
122 FILE *file_ = nullptr;
123 // line_ is the number of lines read.
124 unsigned line_ = 0;
125
126 // start_line_ is the line number of the first attribute of the test.
127 unsigned start_line_ = 0;
128 // type_ is the name of the first attribute of the test.
129 std::string type_;
130 // parameter_ is the value of the first attribute.
131 std::string parameter_;
132 // attributes_ contains all attributes in the test, including the first.
133 std::map<std::string, std::string> attributes_;
134
135 // unused_attributes_ is the set of attributes that have been queried.
136 std::set<std::string> unused_attributes_;
137
138 FileTest(const FileTest&) = delete;
139 FileTest &operator=(const FileTest&) = delete;
140 };
141
142 // FileTestMain runs a file-based test out of |path| and returns an exit code
143 // suitable to return out of |main|. |run_test| should return true on pass and
144 // false on failure. FileTestMain also implements common handling of the 'Error'
145 // attribute. A test with that attribute is expected to fail. The value of the
146 // attribute is the reason string of the expected OpenSSL error code.
147 //
148 // Tests are guaranteed to run serially and may affect global state if need be.
149 // It is legal to use "tests" which, for example, import a private key into a
150 // list of keys. This may be used to initialize a shared set of keys for many
151 // tests. However, if one test fails, the framework will continue to run
152 // subsequent tests.
153 int FileTestMain(bool (*run_test)(FileTest *t, void *arg), void *arg,
154 const char *path);
155
156
157 #endif /* OPENSSL_HEADER_CRYPTO_TEST_FILE_TEST_H */
158