|
- /* Copyright (c) 2015, Google Inc.
- *
- * Permission to use, copy, modify, and/or distribute this software for any
- * purpose with or without fee is hereby granted, provided that the above
- * copyright notice and this permission notice appear in all copies.
- *
- * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
- * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
- * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
- * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
- * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
- * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
- * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
-
- #ifndef OPENSSL_HEADER_CRYPTO_TEST_FILE_TEST_H
- #define OPENSSL_HEADER_CRYPTO_TEST_FILE_TEST_H
-
- #include <openssl/base.h>
-
- #include <stdint.h>
-
- OPENSSL_MSVC_PRAGMA(warning(push))
- OPENSSL_MSVC_PRAGMA(warning(disable : 4702))
-
- #include <functional>
- #include <map>
- #include <memory>
- #include <set>
- #include <string>
- #include <vector>
-
- OPENSSL_MSVC_PRAGMA(warning(pop))
-
- // File-based test framework.
- //
- // This module provides a file-based test framework. The file format is based on
- // that of OpenSSL upstream's evp_test and BoringSSL's aead_test. NIST CAVP test
- // vector files are also supported. Each input file is a sequence of attributes,
- // instructions and blank lines.
- //
- // Each attribute has the form:
- //
- // Name = Value
- //
- // Instructions are enclosed in square brackets and may appear without a value:
- //
- // [Name = Value]
- //
- // or
- //
- // [Name]
- //
- // Commas in instruction lines are treated as separate instructions. Thus this:
- //
- // [Name1,Name2]
- //
- // is the same as:
- //
- // [Name1]
- // [Name2]
- //
- // Either '=' or ':' may be used to delimit the name from the value. Both the
- // name and value have leading and trailing spaces stripped.
- //
- // Each file contains a number of instruction blocks and test cases.
- //
- // An instruction block is a sequence of instructions followed by a blank line.
- // Instructions apply to all test cases following its appearance, until the next
- // instruction block. Instructions are unordered.
- //
- // A test is a sequence of one or more attributes followed by a blank line. For
- // tests that process multiple kinds of test cases, the first attribute is
- // parsed out as the test's type and parameter. Otherwise, attributes are
- // unordered. The first attribute is also included in the set of attributes, so
- // tests which do not dispatch may ignore this mechanism.
- //
- // Additional blank lines and lines beginning with # are ignored.
- //
- // Functions in this module freely output to |stderr| on failure. Tests should
- // also do so, and it is recommended they include the corresponding test's line
- // number in any output. |PrintLine| does this automatically.
- //
- // Each attribute in a test and all instructions applying to it must be
- // consumed. When a test completes, if any attributes or insturctions haven't
- // been processed, the framework reports an error.
-
- class FileTest;
- typedef bool (*FileTestFunc)(FileTest *t, void *arg);
-
- class FileTest {
- public:
- enum ReadResult {
- kReadSuccess,
- kReadEOF,
- kReadError,
- };
-
- class LineReader {
- public:
- virtual ~LineReader() {}
- virtual ReadResult ReadLine(char *out, size_t len) = 0;
- };
-
- struct Options {
- // path is the path to the input file.
- const char *path = nullptr;
- // callback is called for each test. It should get the parameters from this
- // object and signal any errors by returning false.
- FileTestFunc callback = nullptr;
- // arg is an opaque pointer that is passed to |callback|.
- void *arg = nullptr;
- // silent suppressed the "PASS" string that is otherwise printed after
- // successful runs.
- bool silent = false;
- // comment_callback is called after each comment in the input is parsed.
- std::function<void(const std::string&)> comment_callback;
- // is_kas_test is true if a NIST “KAS” test is being parsed. These tests
- // are inconsistent with the other NIST files to such a degree that they
- // need their own boolean.
- bool is_kas_test = false;
- };
-
- explicit FileTest(std::unique_ptr<LineReader> reader,
- std::function<void(const std::string &)> comment_callback,
- bool is_kas_test);
- ~FileTest();
-
- // ReadNext reads the next test from the file. It returns |kReadSuccess| if
- // successfully reading a test and |kReadEOF| at the end of the file. On
- // error or if the previous test had unconsumed attributes, it returns
- // |kReadError|.
- ReadResult ReadNext();
-
- // PrintLine is a variant of printf which prepends the line number and appends
- // a trailing newline.
- void PrintLine(const char *format, ...) OPENSSL_PRINTF_FORMAT_FUNC(2, 3);
-
- unsigned start_line() const { return start_line_; }
-
- // GetType returns the name of the first attribute of the current test.
- const std::string &GetType();
- // GetParameter returns the value of the first attribute of the current test.
- const std::string &GetParameter();
-
- // HasAttribute returns true if the current test has an attribute named |key|.
- bool HasAttribute(const std::string &key);
-
- // GetAttribute looks up the attribute with key |key|. It sets |*out_value| to
- // the value and returns true if it exists and returns false with an error to
- // |stderr| otherwise.
- bool GetAttribute(std::string *out_value, const std::string &key);
-
- // GetAttributeOrDie looks up the attribute with key |key| and aborts if it is
- // missing. It should only be used after a |HasAttribute| call.
- const std::string &GetAttributeOrDie(const std::string &key);
-
- // IgnoreAttribute marks the attribute with key |key| as used.
- void IgnoreAttribute(const std::string &key) { HasAttribute(key); }
-
- // GetBytes looks up the attribute with key |key| and decodes it as a byte
- // string. On success, it writes the result to |*out| and returns
- // true. Otherwise it returns false with an error to |stderr|. The value may
- // be either a hexadecimal string or a quoted ASCII string. It returns true on
- // success and returns false with an error to |stderr| on failure.
- bool GetBytes(std::vector<uint8_t> *out, const std::string &key);
-
- // ExpectBytesEqual returns true if |expected| and |actual| are equal.
- // Otherwise, it returns false and prints a message to |stderr|.
- bool ExpectBytesEqual(const uint8_t *expected, size_t expected_len,
- const uint8_t *actual, size_t actual_len);
-
- // AtNewInstructionBlock returns true if the current test was immediately
- // preceded by an instruction block.
- bool IsAtNewInstructionBlock() const;
-
- // HasInstruction returns true if the current test has an instruction.
- bool HasInstruction(const std::string &key);
-
- // IgnoreInstruction marks the instruction with key |key| as used.
- void IgnoreInstruction(const std::string &key) { HasInstruction(key); }
-
- // GetInstruction looks up the instruction with key |key|. It sets
- // |*out_value| to the value (empty string if the instruction has no value)
- // and returns true if it exists and returns false with an error to |stderr|
- // otherwise.
- bool GetInstruction(std::string *out_value, const std::string &key);
-
- // GetInstructionOrDie looks up the instruction with key |key| and aborts if
- // it is missing. It should only be used after a |HasInstruction| call.
- const std::string &GetInstructionOrDie(const std::string &key);
-
- // GetInstructionBytes behaves like GetBytes, but looks up the corresponding
- // instruction.
- bool GetInstructionBytes(std::vector<uint8_t> *out, const std::string &key);
-
- // CurrentTestToString returns the file content parsed for the current test.
- // If the current test was preceded by an instruction block, the return test
- // case is preceded by the instruction block and a single blank line. All
- // other blank or comment lines are omitted.
- const std::string &CurrentTestToString() const;
-
- // InjectInstruction adds a key value pair to the most recently parsed set of
- // instructions.
- void InjectInstruction(const std::string &key, const std::string &value);
-
- // SkipCurrent passes the current test case. Unused attributes are ignored.
- void SkipCurrent();
-
- private:
- void ClearTest();
- void ClearInstructions();
- void OnKeyUsed(const std::string &key);
- void OnInstructionUsed(const std::string &key);
- bool ConvertToBytes(std::vector<uint8_t> *out, const std::string &value);
-
- std::unique_ptr<LineReader> reader_;
- // line_ is the number of lines read.
- unsigned line_ = 0;
-
- // start_line_ is the line number of the first attribute of the test.
- unsigned start_line_ = 0;
- // type_ is the name of the first attribute of the test.
- std::string type_;
- // parameter_ is the value of the first attribute.
- std::string parameter_;
- // attributes_ contains all attributes in the test, including the first.
- std::map<std::string, std::string> attributes_;
- // instructions_ contains all instructions in scope for the test.
- std::map<std::string, std::string> instructions_;
-
- // unused_attributes_ is the set of attributes that have not been queried.
- std::set<std::string> unused_attributes_;
-
- // unused_instructions_ is the set of instructions that have not been queried.
- std::set<std::string> unused_instructions_;
-
- std::string current_test_;
-
- bool is_at_new_instruction_block_ = false;
- bool seen_non_comment_ = false;
- bool is_kas_test_ = false;
-
- // comment_callback_, if set, is a callback function that is called with the
- // contents of each comment as they are parsed.
- std::function<void(const std::string&)> comment_callback_;
-
- FileTest(const FileTest &) = delete;
- FileTest &operator=(const FileTest &) = delete;
- };
-
- // FileTestMain runs a file-based test out of |path| and returns an exit code
- // suitable to return out of |main|. |run_test| should return true on pass and
- // false on failure. FileTestMain also implements common handling of the 'Error'
- // attribute. A test with that attribute is expected to fail. The value of the
- // attribute is the reason string of the expected OpenSSL error code.
- //
- // Tests are guaranteed to run serially and may affect global state if need be.
- // It is legal to use "tests" which, for example, import a private key into a
- // list of keys. This may be used to initialize a shared set of keys for many
- // tests. However, if one test fails, the framework will continue to run
- // subsequent tests.
- int FileTestMain(FileTestFunc run_test, void *arg, const char *path);
-
- // FileTestMain accepts a larger number of options via a struct.
- int FileTestMain(const FileTest::Options &opts);
-
- // FileTestGTest behaves like FileTestMain, but for GTest. |path| must be the
- // name of a test file embedded in the test binary.
- void FileTestGTest(const char *path, std::function<void(FileTest *)> run_test);
-
- #endif // OPENSSL_HEADER_CRYPTO_TEST_FILE_TEST_H
|