added S-box database

plugins/hawkeye/include/hawkeye/plugin_hawkeye.h

@@ -35,13 +35,16 @@ namespace hal
     class PLUGIN_API HawkeyePlugin : public BasePluginInterface
     {
     public:
+        /** constructor (= default) */
+        HawkeyePlugin() = default;
+
+        /** destructor (= default) */
+        ~HawkeyePlugin() = default;
+
         /*
          * interface implementations
          */
 
-        HawkeyePlugin();
-        ~HawkeyePlugin() = default;
-
         /**
          * Get the name of the plugin.
          *

plugins/hawkeye/include/hawkeye/sbox_database.h

@@ -0,0 +1,128 @@
+// MIT License
+//
+// Copyright (c) 2019 Ruhr University Bochum, Chair for Embedded Security. All Rights reserved.
+// Copyright (c) 2019 Marc Fyrbiak, Sebastian Wallat, Max Hoffmann ("ORIGINAL AUTHORS"). All rights reserved.
+// Copyright (c) 2021 Max Planck Institute for Security and Privacy. All Rights reserved.
+// Copyright (c) 2021 Jörn Langheinrich, Julian Speith, Nils Albartus, René Walendy, Simon Klix ("ORIGINAL AUTHORS"). All Rights reserved.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#pragma once
+
+#include "hal_core/defines.h"
+#include "hal_core/utilities/result.h"
+
+#include <map>
+
+namespace hal
+{
+    namespace hawkeye
+    {
+        /**
+         * Database of known S-boxes.
+         */
+        class SBoxDatabase
+        {
+        public:
+            /**
+             * Constructs an empty S-box database.
+             */
+            SBoxDatabase() = default;
+
+            /**
+             * Constructs an S-box database from the given S-boxes.
+             * 
+             * @param[in] sboxes - A map from S-box name to the respective S-box.
+             */
+            SBoxDatabase(const std::map<std::string, std::vector<u8>>& sboxes);
+
+            /**
+             * Destructs the S-box database.
+             */
+            ~SBoxDatabase() = default;
+
+            /**
+             * Constructs an S-box database from file.
+             * 
+             * @param[in] file_path - The path from which to load the S-box database file.
+             * @returns The S-box database on success, an error otherwise.
+             */
+            static Result<SBoxDatabase> from_file(const std::filesystem::path& file_path);
+
+            /**
+             * Compute the linear representative of the given S-box.
+             * 
+             * @param[in] sbox - The S-box.
+             * @returns The linear representative.
+             */
+            static std::vector<u8> compute_linear_representative(const std::vector<u8>& sbox);
+
+            /**
+             * Add an S-box to the database.
+             * 
+             * @param[in] name - The name of the S-box.
+             * @param[in] sbox - The S-box.
+             * @returns Ok() on success, an error otherwise.
+             */
+            Result<std::monostate> add(const std::string& name, const std::vector<u8>& sbox);
+
+            /**
+             * Add multiple S-boxes to the database.
+             * 
+             * @param[in] sboxes - A map from S-box name to the respective S-box.
+             * @returns Ok() on success, an error otherwise.
+             */
+            Result<std::monostate> add(const std::map<std::string, std::vector<u8>>& sboxes);
+
+            /**
+             * Load S-boxes to the database from a file.
+             * 
+             * @param[in] file_path - The path from which to load the S-box database file.
+             * @param[in] overwrite - Set `true` to overwrite existing database, `false` otherwise. Defaults to `true`.
+             * @returns Ok() on success, an error otherwise.
+             */
+            Result<std::monostate> load(const std::filesystem::path& file_path, bool overwrite = true);
+
+            /**
+             * Store the S-box database to a database file.
+             * 
+             * @param[in] file_path - The path to where to store the S-box database file.
+             * @returns Ok() on success, an error otherwise.
+             */
+            Result<std::monostate> store(const std::filesystem::path& file_path) const;
+
+            /**
+             * Attempt to look up an S-box in the database.
+             * 
+             * @param[in] sbox - The S-box to look for.
+             * @returns Ok() and the S-box name on success, an error otherwise.
+             */
+            Result<std::string> lookup(const std::vector<u8>& sbox) const;
+
+            /**
+             * Print the database.
+             */
+            void print() const;
+
+        private:
+            std::map<u32, std::map<std::vector<u8>, std::vector<std::pair<std::string, u8>>>> m_data;
+        };
+    }    // namespace hawkeye
+
+}    // namespace hal

plugins/hawkeye/python/python_bindings.cpp

@@ -1,6 +1,7 @@
 #include "hal_core/python_bindings/python_bindings.h"
 
 #include "hawkeye/plugin_hawkeye.h"
+#include "hawkeye/sbox_database.h"
 #include "pybind11/operators.h"
 #include "pybind11/pybind11.h"
 #include "pybind11/stl.h"
@@ -64,6 +65,173 @@ namespace hal
             :rtype: str
         )");
 
+        py::class_<hawkeye::SBoxDatabase, RawPtrWrapper<hawkeye::SBoxDatabase>> py_hawkeye_sbox_database(m, "SBoxDatabase", R"(
+            Database of known S-boxes.
+        )");
+
+        py_hawkeye_sbox_database.def(py::init<>(), R"(
+            Constructs an empty S-box database.
+        )");
+
+        py_hawkeye_sbox_database.def(py::init<const std::map<std::string, std::vector<u8>>&>(), py::arg("sboxes"), R"(
+            Constructs an S-box database from the given S-boxes.
+
+            :param dict[str,list[int]] sboxes: A dict from S-box name to the respective S-box.
+        )");
+
+        py_hawkeye_sbox_database.def_static(
+            "from_file",
+            [](const std::filesystem::path& file_path) -> std::optional<hawkeye::SBoxDatabase> {
+                auto res = hawkeye::SBoxDatabase::from_file(file_path);
+                if (res.is_ok())
+                {
+                    return res.get();
+                }
+                else
+                {
+                    log_error("python_context", "{}", res.get_error().get());
+                    return std::nullopt;
+                }
+            },
+            py::arg("file_path"),
+            R"(
+            Constructs an S-box database from file.
+
+            :param pathlib.Path file_path: The path from which to load the S-box database file.
+            :returns: The S-box database on success, an error otherwise.
+            :rtype: hawkeye.SBoxDatabase or None
+        )");
+
+        py_hawkeye_sbox_database.def_static("compute_linear_representative", &hawkeye::SBoxDatabase::compute_linear_representative, py::arg("sbox"), R"(
+            Compute the linear representative of the given S-box.
+
+            :param list[int] sbox: The S-box.
+            :returns: The linear representative.
+            :rtype: list[int]
+        )");
+
+        py_hawkeye_sbox_database.def(
+            "add",
+            [](hawkeye::SBoxDatabase& self, const std::string& name, const std::vector<u8>& sbox) -> bool {
+                auto res = self.add(name, sbox);
+                if (res.is_ok())
+                {
+                    return true;
+                }
+                else
+                {
+                    log_error("python_context", "{}", res.get_error().get());
+                    return false;
+                }
+            },
+            py::arg("name"),
+            py::arg("sbox"),
+            R"(
+            Add multiple S-boxes to the database.
+
+            :param str name: The name of the S-box.
+            :patam list[int] sbox: The S-box.
+            :returns: ``True`` on success, ``False`` otherwise.
+            :rtype: bool
+        )");
+
+        py_hawkeye_sbox_database.def(
+            "add",
+            [](hawkeye::SBoxDatabase& self, const std::map<std::string, std::vector<u8>>& sboxes) -> bool {
+                auto res = self.add(sboxes);
+                if (res.is_ok())
+                {
+                    return true;
+                }
+                else
+                {
+                    log_error("python_context", "{}", res.get_error().get());
+                    return false;
+                }
+            },
+            py::arg("sboxes"),
+            R"(
+            Add multiple S-boxes to the database.
+
+            :param dict[str,list[int]] sboxes: A dict from S-box name to the respective S-box.
+            :returns: ``True`` on success, ``False`` otherwise.
+            :rtype: bool
+        )");
+
+        py_hawkeye_sbox_database.def(
+            "load",
+            [](hawkeye::SBoxDatabase& self, const std::filesystem::path& file_path, bool overwrite = true) -> bool {
+                auto res = self.load(file_path, overwrite);
+                if (res.is_ok())
+                {
+                    return true;
+                }
+                else
+                {
+                    log_error("python_context", "{}", res.get_error().get());
+                    return false;
+                }
+            },
+            py::arg("file_path"),
+            py::arg("overwrite") = true,
+            R"(
+            Load S-boxes to the database from a file.
+
+            :param pathlib.Path file_path: The path from which to load the S-box database file.
+            :returns: ``True`` on success, ``False`` otherwise.
+            :rtype: bool
+        )");
+
+        py_hawkeye_sbox_database.def(
+            "store",
+            [](const hawkeye::SBoxDatabase& self, const std::filesystem::path& file_path) -> bool {
+                auto res = self.store(file_path);
+                if (res.is_ok())
+                {
+                    return true;
+                }
+                else
+                {
+                    log_error("python_context", "{}", res.get_error().get());
+                    return false;
+                }
+            },
+            py::arg("file_path"),
+            R"(
+            Store the S-box database to a database file.
+
+            :param pathlib.Path file_path: The path to where to store the S-box database file.
+            :returns: ``True`` on success, ``False`` otherwise.
+            :rtype: bool
+        )");
+
+        py_hawkeye_sbox_database.def(
+            "lookup",
+            [](const hawkeye::SBoxDatabase& self, const std::vector<u8>& sbox) -> std::optional<std::string> {
+                auto res = self.lookup(sbox);
+                if (res.is_ok())
+                {
+                    return res.get();
+                }
+                else
+                {
+                    log_error("python_context", "{}", res.get_error().get());
+                    return std::nullopt;
+                }
+            },
+            py::arg("sbox"),
+            R"(
+            Attempt to look up an S-box in the database.
+
+            :param list[int] sbox: The S-box to look for.
+            :returns: The S-box name on success, ``None`` otherwise.
+            :rtype: str or None
+        )");
+
+        py_hawkeye_sbox_database.def("print", &hawkeye::SBoxDatabase::print, R"(
+            Print the database.
+        )");
+
 #ifndef PYBIND11_MODULE
         return m.ptr();
 #endif    // PYBIND11_MODULE

plugins/hawkeye/src/plugin_hawkeye.cpp

@@ -28,8 +28,4 @@ namespace hal
         retval.insert("graph_algorithm");
         return retval;
     }
-
-    HawkeyePlugin::HawkeyePlugin()
-    {
-    }
 }    // namespace hal