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 <stdint.h>
19#include <stdio.h>
20
21#if defined(_MSC_VER)
22#pragma warning(push)
23#pragma warning(disable: 4702)
24#endif
25
26#include <string>
27#include <map>
28#include <set>
29#include <vector>
30
31#if defined(_MSC_VER)
32#pragma warning(pop)
33#endif
34
35// File-based test framework.
36//
37// This module provides a file-based test framework. The file format is based on
38// that of OpenSSL upstream's evp_test and BoringSSL's aead_test. Each input
39// file is a sequence of attributes, blocks, and blank lines.
40//
41// Each attribute has the form:
42//
43//   Name = Value
44//
45// Either '=' or ':' may be used to delimit the name from the value. Both the
46// name and value have leading and trailing spaces stripped.
47//
48// Blocks are delimited by lines beginning with three hyphens, "---". One such
49// line begins a block and another ends it. Blocks are intended as a convenient
50// way to embed PEM data and include their delimiters.
51//
52// Outside a block, lines beginning with # are ignored.
53//
54// A test is a sequence of one or more attributes followed by a block or blank
55// line. Blank lines are otherwise ignored. For tests that process multiple
56// kinds of test cases, the first attribute is parsed out as the test's type and
57// parameter. Otherwise, attributes are unordered. The first attribute is also
58// included in the set of attributes, so tests which do not dispatch may ignore
59// this mechanism.
60//
61// Functions in this module freely output to |stderr| on failure. Tests should
62// also do so, and it is recommended they include the corresponding test's line
63// number in any output. |PrintLine| does this automatically.
64//
65// Each attribute in a test must be consumed. When a test completes, if any
66// attributes haven't been processed, the framework reports an error.
67
68
69class FileTest {
70 public:
71  explicit FileTest(const char *path);
72  ~FileTest();
73
74  // is_open returns true if the file was successfully opened.
75  bool is_open() const { return file_ != nullptr; }
76
77  enum ReadResult {
78    kReadSuccess,
79    kReadEOF,
80    kReadError,
81  };
82
83  // ReadNext reads the next test from the file. It returns |kReadSuccess| if
84  // successfully reading a test and |kReadEOF| at the end of the file. On
85  // error or if the previous test had unconsumed attributes, it returns
86  // |kReadError|.
87  ReadResult ReadNext();
88
89  // PrintLine is a variant of printf which prepends the line number and appends
90  // a trailing newline.
91  void PrintLine(const char *format, ...)
92#ifdef __GNUC__
93      __attribute__((__format__(__printf__, 2, 3)))
94#endif
95  ;
96
97  unsigned start_line() const { return start_line_; }
98
99  // GetType returns the name of the first attribute of the current test.
100  const std::string &GetType();
101  // GetParameter returns the value of the first attribute of the current test.
102  const std::string &GetParameter();
103  // GetBlock returns the optional block of the current test, or the empty
104  // if there was no block.
105  const std::string &GetBlock();
106
107  // HasAttribute returns true if the current test has an attribute named |key|.
108  bool HasAttribute(const std::string &key);
109
110  // GetAttribute looks up the attribute with key |key|. It sets |*out_value| to
111  // the value and returns true if it exists and returns false with an error to
112  // |stderr| otherwise.
113  bool GetAttribute(std::string *out_value, const std::string &key);
114
115  // GetAttributeOrDie looks up the attribute with key |key| and aborts if it is
116  // missing. It only be used after a |HasAttribute| call.
117  const std::string &GetAttributeOrDie(const std::string &key);
118
119  // GetBytes looks up the attribute with key |key| and decodes it as a byte
120  // string. On success, it writes the result to |*out| and returns
121  // true. Otherwise it returns false with an error to |stderr|. The value may
122  // be either a hexadecimal string or a quoted ASCII string. It returns true on
123  // success and returns false with an error to |stderr| on failure.
124  bool GetBytes(std::vector<uint8_t> *out, const std::string &key);
125
126  // ExpectBytesEqual returns true if |expected| and |actual| are equal.
127  // Otherwise, it returns false and prints a message to |stderr|.
128  bool ExpectBytesEqual(const uint8_t *expected, size_t expected_len,
129                        const uint8_t *actual, size_t actual_len);
130
131 private:
132  void ClearTest();
133  void OnKeyUsed(const std::string &key);
134
135  FILE *file_ = nullptr;
136  // line_ is the number of lines read.
137  unsigned line_ = 0;
138
139  // start_line_ is the line number of the first attribute of the test.
140  unsigned start_line_ = 0;
141  // type_ is the name of the first attribute of the test.
142  std::string type_;
143  // parameter_ is the value of the first attribute.
144  std::string parameter_;
145  // attributes_ contains all attributes in the test, including the first.
146  std::map<std::string, std::string> attributes_;
147  // block_, if non-empty, is the test's optional trailing block.
148  std::string block_;
149
150  // unused_attributes_ is the set of attributes that have been queried.
151  std::set<std::string> unused_attributes_;
152  // used_block_ is true if the block has been queried.
153  bool used_block_ = false;
154
155  FileTest(const FileTest&) = delete;
156  FileTest &operator=(const FileTest&) = delete;
157};
158
159// FileTestMain runs a file-based test out of |path| and returns an exit code
160// suitable to return out of |main|. |run_test| should return true on pass and
161// false on failure. FileTestMain also implements common handling of the 'Error'
162// attribute. A test with that attribute is expected to fail. The value of the
163// attribute is the reason string of the expected OpenSSL error code.
164//
165// Tests are guaranteed to run serially and may affect global state if need be.
166// It is legal to use "tests" which, for example, import a private key into a
167// list of keys. This may be used to initialize a shared set of keys for many
168// tests. However, if one test fails, the framework will continue to run
169// subsequent tests.
170int FileTestMain(bool (*run_test)(FileTest *t, void *arg), void *arg,
171                 const char *path);
172
173
174#endif /* OPENSSL_HEADER_CRYPTO_TEST_FILE_TEST_H */
175