Merge pull request #1 from rechtlogisch/eric-40.2

upd: ERiC 40.2.10

.env.example

@@ -1,6 +1,6 @@
-DEVELOPER_ID=_____ # Please replace with your Developer-ID
+DEVELOPER_ID=00000 # Please replace with your Developer-ID
 
-#PATH_CERTIFICATE=/path/to/CEZ # Optional [default: "CEZ"]
+#PATH_CERTIFICATE=/path/to/certificate/your.pfx # Optional [default: "certificate/test-softorg-pse.pfx"]
 #PATH_DOWNLOAD=/path/to/download # Optional [default: "."]
 #PATH_LOG=/path/to/log # Optional [default: "."]
 #PATH_VENDOR=/path/to/vendor # Optional [default: "vendor"]

.gitattributes

@@ -1,5 +1,5 @@
 # vendored
-CEZ/** linguist-vendored
+certificate/** linguist-vendored
 include/** linguist-vendored
 vendor/** linguist-vendored
 .env.example linguist-vendored

Dockerfile

@@ -1,19 +1,18 @@
-FROM --platform=linux/amd64 gcc as build
+FROM --platform=linux/amd64 gcc AS build
 COPY . /app
 WORKDIR /app
 RUN make
 
-FROM --platform=linux/amd64 ubuntu as final
+FROM --platform=linux/amd64 ubuntu AS final
 WORKDIR /app
 RUN mkdir -p /app/vendor
-RUN mkdir -p /app/CEZ
+RUN mkdir -p /app/certificate
 COPY --from=build \
     /app/cotto \
     ./
 COPY --from=build \
     /app/vendor/*.so \
     ./vendor/
 COPY --from=build \
-    /app/CEZ/*.p12 \
-    /app/CEZ/*.cer \
-    ./CEZ/
+    /app/certificate/*.pfx \
+    ./certificate/

README.md

@@ -8,7 +8,9 @@ A working example of the Otto library implementation in C++.
 
 Notice: This demo is **not intended for productive usage**!
 
-ELSTER introduced on May 27th, 2024, a new library called Otto, which can be used to download objects from OTTER (Object Storage in ELSTER). The reason why ELSTER introduced the project and library is, that the current solution hit its limits. Otto was introduced together with Datenabholung v30. The currently available way of data retrieval with ERiC will be replaced client-side in ERiC version 41 (end November 2024; only Datenabholung v30 will be available) and server-side with the planned yearly minimal version increase mid-April 2025 (exact date TBA in 2025; only ERiC >= v41 can be used after that date). Therefore, a majority of software developers using currently ERiC Datenabholung will have to implement Otto in production by April 2025.
+ELSTER introduced on May 27th, 2024, a new library called Otto, which can be used to download objects from OTTER (Object Storage in ELSTER). The reason why ELSTER introduced the project and library is, that the current solution hit its limits. Otto was introduced together with a new version of Datenabholung.
+
+The currently available way of data retrieval with ERiC will be replaced client-side in ERiC version 41 (end November 2024; only Datenabholung v31 will be available) and server-side with the planned yearly minimal version increase mid-April 2025 (exact date TBA in 2025; only ERiC >= v41 with Datenabholung v31 can be used after that date). Therefore, a majority of software developers using currently ERiC Datenabholung will have to implement Otto in production by April 2025.
 
 ## Usage
 
@@ -23,17 +25,17 @@ ELSTER introduced on May 27th, 2024, a new library called Otto, which can be use
 Examples:
 
 ```bash
-cotto -u 2b884e20-779d-4094-a1de-8304a6fc00c9 # ESB 2014
-cotto -u 131517ff-4516-418a-9167-f7e35fb32864 # ELOProtokoll
+cotto -u 468a69d4-0151-4681-9e8d-fcd87873d550 # ELOProtokoll / Lohnersatzleistung
+cotto -u e694eca1-7251-4629-a164-4634db811189 -e pdf # DivaBescheidESt
 ```
 
 Notice: The code and scripts have been tested so far only on Linux and macOS. Windows is pending tests.
 
-Hint: Currently, a limited list of object UUIDs is available. You can get a list of them using `PostfachAnfrage` with the Test-CEZ.
+Hint: A list of object UUIDs is available with test certificates. You can get a list of them using `PostfachAnfrage` with the test certificate. The examples above are for `test-softorg-pse.pfx` and might be removed from the test instance after the time specified in the metadata.
 
 ## Vendor
 
-You need the official ELSTER Otto library. Download the ERiC package v40 for your platform from the [ELSTER developer area](https://www.elster.de/elsterweb/entwickler/infoseite/eric), unzip it and place it at a desired path. Feel free to place it in `./vendor/`. Currently, you only need one library called `otto` (platform dependent naming: `(lib)otto.{so,dylib,dll}`), as Otto supports only client-side generated certificates (German abbreviation: CEZ).
+You need the official ELSTER Otto library. Download the ERiC package v40 for your platform from the [ELSTER developer area](https://www.elster.de/elsterweb/entwickler/infoseite/eric), unzip it and place it at a desired path. Feel free to place it in `./vendor/`. You need two libraries: `otto` and `eSigner` (platform dependent naming: `(lib)otto.{so|dylib|dll}` and `(lib)eSigner.{so|dylib|dll}`).
 
 Notice: The ERiC package, especially the included there libraries are subject to a separate license agreement (presented before download in the ELSTER developer area and included in the ERiC package itself).
 
@@ -60,14 +62,14 @@ git clone git@github.com:rechtlogisch/cotto.git
 # Change to directory with source code
 cd cotto
 
-# Retrieve CEZ certificate to "CEZ" subdirectory
-./get-test-cez-certificate.sh
+# Retrieve test certificate to "certificate" subdirectory
+./get-test-certificate.sh
 
 # Compile statically linked to Otto library placed in PATH_VENDOR
 PATH_VENDOR="/path/to/otto-library/" make
 
 # Run `cotto`, provide objectUuid with -u option and your DEVELOPER_ID inline
-DEVELOPER_ID="_____" ./cotto -u 2b884e20-779d-4094-a1de-8304a6fc00c9
+DEVELOPER_ID="00000" ./cotto -u 2b884e20-779d-4094-a1de-8304a6fc00c9
 ```
 
 Notice: You should set your five-digit Developer-ID (German: Hersteller-ID) as the environment variable `DEVELOPER_ID`. You could source it from for example `.env` or pass it inline to `cotto`, as shown in the steps above.

certificate/.gitkeep

@@ -0,0 +1 @@
+Run `./get-test-certificate.sh` or copy your .pfx-file here manually.

cotto.cpp

@@ -3,13 +3,31 @@
 #include <unistd.h>
 #include "include/otto.h"
 
-int error(std::string message, OttoStatusCode code)
+int error(const std::string message, const OttoStatusCode code)
 {
     std::cerr << "[ERROR] " << message << std::endl;
     std::cerr << "[CODE]  " << code << std::endl;
     return code;
 }
 
+int downloadError(const OttoStatusCode code)
+{
+    const char *message;
+
+    switch (code) {
+        case OTTO_TRANSFER_UNAUTHORIZED:
+            message = "The client is not allowed to use the API.";
+            break;
+        case OTTO_TRANSFER_NOT_FOUND:
+            message = "The OTTER server did not find the object";
+            break;
+        default:
+            message = "Error occurred while downloading. Check otto.log for details.";
+            break;
+    } 
+    return error(message, code);
+}
+
 class Cotto {
     private:
         OttoInstanzHandle instance;
@@ -66,7 +84,7 @@ class Cotto {
             }
         }
 
-        int workflow(const char* objectUuid, const char* developerId, const char* fileExtension, const char* pathDownload, bool forceOverwrite = false) {
+        int workflow(const char* objectUuid, const char* developerId, const char* fileExtension, const char* pathDownload) {
             // Start download
             const OttoStatusCode statusCodeDownloadStart = OttoEmpfangBeginnen(instance, objectUuid, certificateHandle, developerId, &downloadHandle);
             if (statusCodeDownloadStart != OTTO_OK) {
@@ -118,7 +136,7 @@ class Cotto {
 
             if (statusCodeDownloadContinue != OTTO_OK) {
                 unlink(filepath.c_str());
-                return error("Error occurred while in download loop. Check otto.log for details.", statusCodeDownloadContinue);  
+                return downloadError(statusCodeDownloadContinue);  
             }
 
             std::cout << "[INFO]  Downloaded content saved in: " << filepath << std::endl;
@@ -197,7 +215,7 @@ int main(const int argc, char *argv[]) {
         return 4;
     }
 
-    const char* pathCertificate = "CEZ";
+    const char* pathCertificate = "certificate/test-softorg-pse.pfx";
     const char* envPathCertificate = getenv("PATH_CERTIFICATE");
     if (envPathCertificate != NULL) {
         pathCertificate = envPathCertificate;
@@ -210,5 +228,5 @@ int main(const int argc, char *argv[]) {
     }
 
     Cotto cotto(pathLog, pathCertificate, certificatePassword);
-    return cotto.workflow(objectUuid, developerId, fileExtension, pathDownload, forceOverwrite);
+    return cotto.workflow(objectUuid, developerId, fileExtension, pathDownload);
 }

get-test-cez-certificate.sh → get-test-certificate.sh

@@ -1,8 +1,8 @@
 #!/bin/bash
 
-TARGET_DIRECTORY="CEZ/"
+TARGET_DIRECTORY="certificate/"
 CERTIFICATE_ARCHIVE_FILENAME="Test_Zertifikate.zip"
 
 curl -sS -o "$TARGET_DIRECTORY$CERTIFICATE_ARCHIVE_FILENAME" https://download.elster.de/download/schnittstellen/"$CERTIFICATE_ARCHIVE_FILENAME" && \
-unzip -j "$TARGET_DIRECTORY$CERTIFICATE_ARCHIVE_FILENAME" -d "$TARGET_DIRECTORY" eric-zertifikate-bescheidabholung/PSE/eric_private.p12 eric-zertifikate-bescheidabholung/PSE/eric_public.cer && \
+unzip -j "$TARGET_DIRECTORY$CERTIFICATE_ARCHIVE_FILENAME" -d "$TARGET_DIRECTORY" test-softorg-pse.pfx && \
 rm "$TARGET_DIRECTORY$CERTIFICATE_ARCHIVE_FILENAME"

include/README.md

@@ -1,3 +1,3 @@
 The header files in this directory originate from ERiC package [ERiC-40.1.8.0-Linux-x86_64.jar](https://www.elster.de/elsterweb/entwickler/infoseite/eric)
 
-They are shared here publically based on the § 4 (1) of the "Softwarehersteller-Lizenzvertrag" (lizenz.pdf) included in the above mentioned ERiC package.
+They are shared here publicly based on the § 4 (1) of the "Softwarehersteller-Lizenzvertrag" (lizenz.pdf) included in the above-mentioned ERiC package.