extended README.md to doxygen mainpage and add to doxygen build

gittiver · gittiver · commit fa746dd9258b · 2022-12-31T14:36:37.000+01:00
diff --git 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
@@ -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.
 
-## Protocol Questions
+As all issuer related interactions of the protocol follows a request/response mechanism we are able to map all of them to Http-Requests.
 
-+ 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)
+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
 
-+ [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
++ [ ] 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) 
 
 ### Blinding Notes
 
diff --git 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<unsigned>  denominations;//: [1, 2, 5],
-  BigInt id;//: 23ed956e629ba35f0002eaf833ea436aea7db5c2,
-
-std::vector<WeightedUrl> 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
-  //},
+  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<unsigned>
+      denominations; /// the available denominations of this currency
+  BigInt id;         /// an identity for this currency
+
+  std::vector<WeightedUrl> 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<WeightedUrl> mint_service;
-  std::string protocol_version; //: https://opencoin.org/1.0,
+  std::string protocol_version; // e.g. https://opencoin.org/1.0
   std::vector<WeightedUrl> redeem_service;
   std::vector<WeightedUrl> 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<CDDC *, bool> getCDDC(unsigned int cdd_serial) = 0;
-  virtual tl::expected<CDDC *, bool> 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<CDDC *, bool> 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<MintKeyCert>
   getMKCs(const std::vector<unsigned int> &denominations,
           const std::vector<BigInt> &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<BlindSignature>
   mint(std::string const& transaction_reference,
        const std::vector<Blind> &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<Coin> &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<Model> getModel(const std::string &backend_name);
 
 private:
