From fa746dd9258bf11167561b4f391f64d5e35b1df7 Mon Sep 17 00:00:00 2001 From: Gulliver Date: Sat, 31 Dec 2022 13:49:58 +0100 Subject: [PATCH] extended README.md to doxygen mainpage and add to doxygen build --- CMakeLists.txt | 14 ++++---- README.md | 51 +++++++++++++++++++--------- src/model.hpp | 91 +++++++++++++++++++++++++++++++++++++++----------- 3 files changed, 113 insertions(+), 43 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 5c288e4..89ac8f0 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -14,7 +14,7 @@ else() add_compile_options(-Wall -Wextra -pedantic) endif() -project(oc-mint VERSION 0.0.1 LANGUAGES CXX) +project(oc-issuer VERSION 0.0.2 LANGUAGES CXX) include(FetchContent) @@ -64,10 +64,10 @@ find_package(Doxygen REQUIRED dot OPTIONAL_COMPONENTS mscgen dia) set(DOXYGEN_HAVE_DOT YES) -doxygen_add_docs( - doc - src - COMMENT "Generate documentation" +doxygen_add_docs( doc + README.md + src + COMMENT "Generate documentation" ) # build common library @@ -76,8 +76,8 @@ add_library(oc-mint-lib ${LIB_SOURCES}) target_link_libraries(oc-mint-lib PUBLIC Crow::Crow) target_include_directories(oc-mint-lib PUBLIC ${expected_SOURCE_DIR}/include src) -add_executable(oc-mint src/main.cpp) -target_link_libraries(oc-mint PRIVATE oc-mint-lib INTERFACE tl::expected::expected) +add_executable(${PROJECT_NAME} src/main.cpp) +target_link_libraries(${PROJECT_NAME} PRIVATE oc-mint-lib INTERFACE tl::expected::expected) ## these are unittests that can be run on any platform add_executable(tests test/test_big_int.cpp test/test.cpp) diff --git a/README.md b/README.md index 16ad164..63456cb 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,47 @@ -![build](https://github.com/OpenCoin/oc-mint-cpp/actions/workflows/cmake.yaml/badge.svg) +opencoin-issuer-cpp - a C++ OpenCoin Issuer REST-API implementation {#mainpage} +============================================================= -# oc mint sample +![build](https://github.com/OpenCoin/opencoin-issuer-cpp/actions/workflows/cmake.yaml/badge.svg) +[![Documentation](https://github.com/OpenCoin/opencoin-issuer-cpp/actions/workflows/doxygen-gh-pages.yml/badge.svg)](https://github.com/OpenCoin/opencoin-issuer-cpp/actions/workflows/doxygen-gh-pages.yml) -this is a C++ implementation of the opencoin protocol -as mapping to some kind of REST interface +# opencoin issuer -actually it is a work in progress. +this is a C++ implementation of the [opencoin protocol](https://opencoin.org/0.4/OpenCoin.html) +done as mapping to some kind of REST interface. + +As all issuer related interactions of the protocol follows a request/response mechanism we are able to map all of them to Http-Requests. + +We decided to use POST-Requests in all cases, +as the protocol uses JSON-formatted messages for requests. + +The following table gives an overview of the mapping of requests to URLs: + +| Request | URL | Response | C++ Interface Method | +|:------------------|:-------------|:------------------------------|:---------------------------------------------------| +| RequestCDDCSerial | /cddc/serial | ResponseCDDCSerial | cdd.cdd_serial of Model::getCurrentCDDC() | +| RequestCDDC | /cddc | ResponseCDDC | Model::getCurrentCDDC() | +| RequestMKCs | /mkcs | ResponseMKCs | Model::getMKCs | +| RequestMint | /mint | ResponseMint | Model::mint | +| RequestRenew | /renew | ResponseMint or ResponseDelay | ? | +| RequestResume | /resume | ResponseMint or ResponseDelay | ? | +| RequestRedeem | /redeem | ResponseRedeem | Model::redeem | + +actually the implementation is a work in progress. + +## TODO + +- [ ] select crypto library + + https://en.wikipedia.org/wiki/Comparison_of_cryptography_libraries ++ [ ] blinding utilizing crypto++ ++ [ ] integrate session and login to make transactions account based ++ [ ] bookkeeping for accounts ## Protocol Questions + What is signed as cdd - only the content of the cdd item with curly braces or also the key? + the weighted URL as array has a different js encoding as other elements -+ Clarify PSS usage (see https://crypto.stackexchange.com/questions/12707/usability-of-padding-scheme-in-blinded-rsa-signature) - -## TODO - -+ [x] bigint type for big integers encoded as string -+ [ ] blinding utilizing crypto++ -- [x] complete from_json conversions -- [x] complete tests -- [x] drone config -- [ ] select crypto library - + https://en.wikipedia.org/wiki/Comparison_of_cryptography_libraries ++ Clarify PSS usage (see https://crypto.stackexchange.com/questions/12707/usability-of-padding-scheme-in-blinded-rsa-signature) ### Blinding Notes diff --git a/src/model.hpp b/src/model.hpp index 3d9a2b7..6da0b8b 100644 --- a/src/model.hpp +++ b/src/model.hpp @@ -25,30 +25,36 @@ struct WeightedUrl { crow::json::wvalue to_json() const; }; -/** currency description document */ +/** @brief currency description document + * + * this structure describes a currency based on opencoin protocol. + * It can be converted to json to provide the specified currency + * description document. + */ struct CDD { std::string additional_info; - time_t cdd_expiry_date;//: 2023-07-22T15:45:53.164685 - std::string cdd_location;//: https://opencent.org, - size_t cdd_serial;//: 1, - time_t cdd_signing_date;//: 2022-07-22T15:45:53.164685, - size_t currency_divisor;//: 100, - std::string currency_name;//: OpenCent, - std::vector denominations;//: [1, 2, 5], - BigInt id;//: 23ed956e629ba35f0002eaf833ea436aea7db5c2, + time_t cdd_expiry_date; /// expiry date of this document (e.g. + ///2023-07-22T15:45:53.164685) + std::string cdd_location; /// URL of location of this document (e.g + ///https://opencent.org) + size_t cdd_serial; /// serial number of currency description document + time_t cdd_signing_date; /// date of signing this document (e.g. + ///2022-07-22T15:45:53.164685) + size_t currency_divisor; /// divisor used for coins of this currency + std::string currency_name; /// name of the currency (e.g. OpenCent) + std::vector + denominations; /// the available denominations of this currency + BigInt id; /// an identity for this currency -std::vector info_service; - /* eCipherSuite*/ std::string issuer_cipher_suite; //: RSA-SHA256-PSS-CHAUM82, - PublicKey - issuer_public_master_key; //: { - // modulus: - // daaa63ddda38c189b8c49020c8276adbe0a695685a..., - // public_exponent: 65537, - // type: rsa public key - //}, + std::vector info_service; + /* eCipherSuite*/ + std::string issuer_cipher_suite; /// the cipher suite used for this currencey + /// (currently only RSA-SHA256-PSS-CHAUM82 + /// is supported) + PublicKey issuer_public_master_key; /// the public key of this currency std::vector mint_service; - std::string protocol_version; //: https://opencoin.org/1.0, + std::string protocol_version; // e.g. https://opencoin.org/1.0 std::vector redeem_service; std::vector renew_service; @@ -237,18 +243,63 @@ class Model { public: virtual ~Model(){}; + /** + * return the CurrencyDocumentDescription certifikate for a specific + * serial version number of it. + * [see spec](https://opencoin.org/0.4/schemata.html#cddc) + * @return returns a pointer to the CDDC if successful, false otherwise + */ virtual tl::expected getCDDC(unsigned int cdd_serial) = 0; - virtual tl::expected getCurrentCDDC() = 0; + /** + * return the CurrencyDocumentDescription certifikate + * [see spec](https://opencoin.org/0.4/schemata.html#cddc) + * @return returns a pointer to the CDDC if successful, false otherwise + */virtual tl::expected getCurrentCDDC() = 0; + + /** + * return the MintKey certificates for a given list of denominations + * and mint key ids + * + * @param denominations + * @param mint_key_ids + * + * @return mint key certificates for given denominations and mint_key_ids + */ virtual const std::vector getMKCs(const std::vector &denominations, const std::vector &mint_key_ids) = 0; + + /** + * returns the vector of blind signatures for a given vector of blinds + * + * @param transaction_reference reference to a transaction (send from client) + * @param blinds the vector of blinds to sign + * + * @return + */ virtual std::vector mint(std::string const& transaction_reference, const std::vector &blinds) = 0; + + /** + * redeem valid coins into real money + * + * @param coins the coins to redeem + * + * @return true if successful, false on error + */ virtual bool redeem(const std::vector &coins) = 0; + /** + * factory function returning a concrete backend for Opencoin API handling. + * based on backend_name a concrete backend will be returned + * or in case of error null. + * @param backend_name + * + * @return pointer to backend instance or null on invalid backend name + */ static std::unique_ptr getModel(const std::string &backend_name); private: