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 69 class 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. 170 int 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
