diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..dd42935 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,19 @@ +# EditorConfig is awesome: https://EditorConfig.org + +# top-most EditorConfig file +root = true + +# Unix-style newlines with a newline ending every file +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true + +# 4 space indentation +[*.{cpp,h}] +indent_style = space +indent_size = 4 + +# Tab indentation (no size specified) +[Makefile] +indent_style = tab diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..057206f --- /dev/null +++ b/.env.example @@ -0,0 +1,10 @@ +DEVELOPER_ID=_____ # Please replace with your Developer-ID + +#PATH_CERTIFICATE=/path/to/CEZ # Optional [default: "CEZ"] +#PATH_DOWNLOAD=/path/to/download # Optional [default: "."] +#PATH_LOG=/path/to/log # Optional [default: "."] +#PATH_VENDOR=/path/to/vendor # Optional [default: "vendor"] + +# Warning: +# Docker interprets double quotes " literally, use single quotes ' instead. +# You could escape whitespaces with backslashes \ or explicitly escape a double quote with a backslash \" diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5677515 --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +.DS_Store +.vscode +.idea +.env +cotto +otto.log* +*.txt +download diff --git a/CEZ/.gitignore b/CEZ/.gitignore new file mode 100644 index 0000000..8e5c5c2 --- /dev/null +++ b/CEZ/.gitignore @@ -0,0 +1,4 @@ +* +!.gitignore +!.gitkeep +!*.sh diff --git a/CEZ/.gitkeep b/CEZ/.gitkeep new file mode 100644 index 0000000..4e3e58c --- /dev/null +++ b/CEZ/.gitkeep @@ -0,0 +1 @@ +Run `./get-test-cez-certificate.sh` or copy Test-CEZ manually here. diff --git a/CEZ/get-test-cez-certificate.sh b/CEZ/get-test-cez-certificate.sh new file mode 100755 index 0000000..1b9a5a8 --- /dev/null +++ b/CEZ/get-test-cez-certificate.sh @@ -0,0 +1,5 @@ +#!/bin/bash + +curl -sS -O https://download.elster.de/download/schnittstellen/Test_Zertifikate.zip && \ +unzip -j Test_Zertifikate.zip eric-zertifikate-bescheidabholung/PSE/eric_private.p12 eric-zertifikate-bescheidabholung/PSE/eric_public.cer && \ +rm Test_Zertifikate.zip diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..9e35f71 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,9 @@ +# Changelog + +All notable changes to `cotto` will be documented in this file. + +## v1.0.0 - 2024-05-31 +- Initial version +- Utilizes Otto 40.1.8 + +**Full Changelog**: https://github.com/rechtlogisch/cotto/commits/v1.0.0 \ No newline at end of file diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..adfa4a6 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,19 @@ +FROM --platform=linux/amd64 gcc as build +COPY . /app +WORKDIR /app +RUN make + +FROM --platform=linux/amd64 ubuntu as final +WORKDIR /app +RUN mkdir -p /app/vendor +RUN mkdir -p /app/CEZ +COPY --from=build \ + /app/cotto \ + ./ +COPY --from=build \ + /app/vendor/*.so \ + ./vendor/ +COPY --from=build \ + /app/CEZ/*.p12 \ + /app/CEZ/*.cer \ + ./CEZ/ diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..1951139 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,9 @@ +The MIT License (MIT) + +Copyright (c) RL Recht logisch GmbH & Co. KG open-source@rechtlogisch.de + +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. \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..8f11030 --- /dev/null +++ b/Makefile @@ -0,0 +1,49 @@ +.PHONY: all cotto clean + +PATH_VENDOR ?= $(PWD)/vendor +ENV_FILE ?= .env +image := rechtlogisch/cotto + +all: clean cotto + +cotto: + @if [ -z "$(PATH_VENDOR)" ]; then \ + echo "Error: PATH_VENDOR is not set"; \ + exit 1; \ + elif [ ! -d "$(PATH_VENDOR)" ]; then \ + echo "Error: Directory $(PATH_VENDOR) does not exist"; \ + exit 2; \ + fi + + @if [ -z "$$(find $(PATH_VENDOR) -name '*otto.*' -print -quit)" ]; then \ + echo "Error: No file matching *otto.{dll,dylib,so} found in $(PATH_VENDOR)"; \ + exit 3; \ + fi + + g++ -ldl -L"$(PATH_VENDOR)" -Wl,-rpath,"$(PATH_VENDOR)" -lotto -o cotto cotto.cpp + +clean: + rm -f cotto otto.log* + +docker-build: + docker build \ + -t $(image) \ + . + +docker-cmd: + docker run \ + -it --rm \ + --env-file=$(ENV_FILE) \ + --platform=linux/amd64 \ + -v $(PATH_DOWNLOAD):/app/download/ \ + $(image) + +docker-cotto: + docker run \ + -it --rm \ + --env-file=$(ENV_FILE) \ + --platform=linux/amd64 \ + --name=cotto \ + -v $(PATH_DOWNLOAD):/app/download/ \ + $(image) \ + ./cotto $(input) diff --git a/README.md b/README.md new file mode 100644 index 0000000..fe214fb --- /dev/null +++ b/README.md @@ -0,0 +1,93 @@ +![Recht logisch cotto banner image](rechtlogisch-cotto-banner.png) + +# cotto + +> Unofficial C++ Otto download demo + +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 with 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). + +## Usage + +```bash +./cotto + -u objectUuid UUID of object to download (mandatory) + -e extension Set filename extension of downloaded content [default: "txt"] + -p password Password for certificate [default: "123456"] + -f Force file overwriting [default: false] +``` + +Examples: + +```bash +cotto -u 2b884e20-779d-4094-a1de-8304a6fc00c9 # ESB 2014 +cotto -u 131517ff-4516-418a-9167-f7e35fb32864 # ELOProtokoll +``` + +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. + +## 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: `(lib)otto.{so,dylib,dll}`, as Otto supports only client-side generated certificates (German abbreviation: CEZ). + +Hint: Choose the right library for the platform you compile and run on. + +## Compile + +You can compile the code with: + +```bash +make +``` + +Hints: provide `PATH_VENDOR` environment variable to point the path where the ELSTER `otto` library is placed on your system or place the needed libraries in `./vendor/`. + +Follow the steps to run `cotto` locally: + +```bash +git clone git@github.com:rechtlogisch/cotto.git +cd cotto +./CEZ/get-test-cez-certificate.sh +PATH_VENDOR="/path/to/otto-library/" make +DEVELOPER_ID="_____" ./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. + +Hint: The downloaded result will be saved in the same directory as `cotto`, unless you provide a different `PATH_DOWNLOAD`. + +## Environment variables + +All supported environment variables are listed in [`.env.example`](.env.example). Feel free to copy them to `.env`, adjust accordingly and source for usage. + +## Docker + +A simple [Dockerfile](Dockerfile) is included. You can use `make docker-build` and `make docker-cotto` to build and run `cotto` in a container. + +Hint: Set `PATH_DOWNLOAD` and `PATH_LOG` environment variables to expose data outside the container. + +## Changelog + +Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. + +## Contributing + +Please see [CONTRIBUTING](https://github.com/rechtlogisch/.github/blob/main/CONTRIBUTING.md) for details. + +## Security Vulnerabilities + +If you discover any security-related issues, please email open-source@rechtlogisch.de instead of using the issue tracker. + +## Credits + +- [Krzysztof Tomasz Zembrowski](https://github.com/rechtlogisch) +- [All Contributors](../../contributors) + +## License + +The MIT License (MIT). Please see [License File](LICENSE.md) for more information. diff --git a/cotto.cpp b/cotto.cpp new file mode 100644 index 0000000..279b0c2 --- /dev/null +++ b/cotto.cpp @@ -0,0 +1,215 @@ +#include +#include +#include +#include "include/otto.h" + +int error(std::string message, OttoStatusCode code) +{ + std::cerr << "[ERROR] " << message << std::endl; + std::cerr << "[CODE] " << code << std::endl; + return code; +} + +class Cotto { + private: + OttoInstanzHandle instance; + OttoZertifikatHandle certificateHandle; + OttoRueckgabepufferHandle contentHandle; + OttoEmpfangHandle downloadHandle; + const char* pathDownload; + public: + Cotto(const char* pathLog, const char* pathCertificate, const char* certificatePassword) { + // Create instance + const OttoStatusCode statusCodeInstanceCreate = OttoInstanzErzeugen(pathLog, NULL, NULL, &instance); + if (statusCodeInstanceCreate != OTTO_OK) { + error("Could not create an Otto instance. Check otto.log for details.", statusCodeInstanceCreate); + } + + // Open certificate + const OttoStatusCode statusCodeCertificateOpen = OttoZertifikatOeffnen(instance, pathCertificate, certificatePassword, &certificateHandle); + if (statusCodeCertificateOpen != OTTO_OK) { + error("Could not open certificate: " + std::string(pathCertificate), statusCodeCertificateOpen); + } + std::cout << "[INFO] Using certificate path: " << pathCertificate << std::endl; + } + + ~Cotto() { + // End download + if (downloadHandle != NULL) { + const OttoStatusCode statusCodeDownloadEnd = OttoEmpfangBeenden(downloadHandle); + if (statusCodeDownloadEnd != OTTO_OK) { + error("Could not end download.", statusCodeDownloadEnd); + } + } + + // Close certificate + if (certificateHandle != NULL) { + const OttoStatusCode statusCodeCertificateClose = OttoZertifikatSchliessen(certificateHandle); + if (statusCodeCertificateClose != OTTO_OK) { + error("Could not close certificate handle", statusCodeCertificateClose); + } + } + + // Release content buffer + if (contentHandle != NULL) { + const OttoStatusCode statusCodeContentRelease = OttoRueckgabepufferFreigeben(contentHandle); + if (statusCodeContentRelease != OTTO_OK) { + error("Could not release content handle.", statusCodeContentRelease); + } + } + + // Destroy instance + if (instance != NULL) { + const OttoStatusCode statusCodeInstanceDestroy = OttoInstanzFreigeben(instance); + if (statusCodeInstanceDestroy != OTTO_OK) { + error("Could not destroy the Otto instance. Check otto.log for details.", statusCodeInstanceDestroy); + } + } + } + + int workflow(const char* objectUuid, const char* developerId, const char* fileExtension, const char* pathDownload, bool forceOverwrite = false) { + // Start download + const OttoStatusCode statusCodeDownloadStart = OttoEmpfangBeginnen(instance, objectUuid, certificateHandle, developerId, &downloadHandle); + if (statusCodeDownloadStart != OTTO_OK) { + return error("Could not start download. Check otto.log", statusCodeDownloadStart); + } + + // Create content buffer + const OttoStatusCode statusCodeContentHandleCreate = OttoRueckgabepufferErzeugen(instance, &contentHandle); + if (statusCodeContentHandleCreate != OTTO_OK) { + return error("Could not create handle for content.", statusCodeContentHandleCreate); + } + + const std::string filepath = std::string(pathDownload) + "/" + std::string(objectUuid) + "." + std::string(fileExtension); + FILE *file = fopen(filepath.c_str(), "ab"); // Open file for appending in binary mode + if (!file) { + std::cerr << "Failed to open file: " << filepath << std::endl; + return 6; + } + + // Continue download + bool downloadContinue = true; + OttoStatusCode statusCodeDownloadContinue = OTTO_UNBEKANNTER_FEHLER; + while (downloadContinue == true) { + statusCodeDownloadContinue = OttoEmpfangFortsetzen(downloadHandle, contentHandle); + if (statusCodeDownloadContinue != OTTO_OK) { + downloadContinue = false; + break; + } + + uint64_t contentSize = OttoRueckgabepufferGroesse(contentHandle); + if (contentSize <= 0) { + downloadContinue = false; + break; + } + std::cout << "[INFO] Downloaded: " << contentSize << " bytes" << std::endl; + const byteChar* contentBlock = OttoRueckgabepufferInhalt(contentHandle); + size_t contentWrite = fwrite(contentBlock, 1, contentSize, file); + if (contentWrite != contentSize) { + std::cerr << "Failed to write to file: " << filepath << std::endl; + fclose(file); + break; + } + } + + if (fclose(file) != 0) { + std::cerr << "Failed to close file: " << filepath << std::endl; + return 7; + } + + if (statusCodeDownloadContinue != OTTO_OK) { + unlink(filepath.c_str()); + return error("Error occurred while in download loop. Check otto.log for details.", statusCodeDownloadContinue); + } + + std::cout << "[INFO] Downloaded content saved in: " << filepath << std::endl; + return EXIT_SUCCESS; + } +}; + +int main(const int argc, char *argv[]) { + if (argc < 2) { + std::cerr << "Usage:" << std::endl; + std::cerr << "" << argv[0] << std::endl; + std::cerr << " -u objectUuid\t\tUUID of object to download (mandatory)" << std::endl; + std::cerr << " -e extension\t\tSet filename extension of downloaded content [default: \"txt\"]" << std::endl; + std::cerr << " -p password\t\tPassword for certificate [default: \"123456\"]" << std::endl; + std::cerr << " -f\t\t\tForce file overwriting [default: false]" << std::endl; + return 1; + } + + int option; + const char* objectUuid = NULL; + const char* fileExtension = "txt"; + const char* certificatePassword = "123456"; + bool forceOverwrite = false; + while ((option = getopt(argc, argv, "u:e:p:f")) != -1) { + switch (option) { + case 'u': + objectUuid = optarg; + break; + case 'e': + fileExtension = optarg; + break; + case 'p': + certificatePassword = optarg; + break; + case 'f': + forceOverwrite = true; + break; + default: + std::cerr << "Invalid option: -" << static_cast(optopt) << std::endl; + return 2; + } + } + + if (objectUuid == NULL) { + std::cerr << "Object UUID is missing. Please provide it with the -u flag." << std::endl; + return 3; + } + + const char* pathDownload = "."; + const char* envPathDownload = getenv("PATH_DOWNLOAD"); + if (envPathDownload != NULL) { + pathDownload = envPathDownload; + } + + // Check if file already exists + const std::string filepath = std::string(pathDownload) + "/" + std::string(objectUuid) + "." + std::string(fileExtension); + if (access(filepath.c_str(), F_OK) != -1) { + if (forceOverwrite) { + unlink(filepath.c_str()); + } else { + char userChoice; + std::cout << "File: " << filepath << " already exists. Do you want to overwrite it? (y/n)" << std::endl; + std::cin >> userChoice; + if (userChoice != 'y' && userChoice != 'Y') { + std::cerr << "File: " << filepath << " was not overwritten." << std::endl; + return 5; + } else { + unlink(filepath.c_str()); + } + } + } + + const char* developerId = getenv("DEVELOPER_ID"); + if (developerId == NULL || std::string(developerId) == "") { + std::cerr << "DEVELOPER_ID environment variable missing. Please set it accordingly." << std::endl; + return 4; + } + + const char* pathCertificate = "CEZ"; + const char* envPathCertificate = getenv("PATH_CERTIFICATE"); + if (envPathCertificate != NULL) { + pathCertificate = envPathCertificate; + } + + const char* pathLog = "."; + const char* envPathLog = getenv("PATH_LOG"); + if (envPathLog != NULL) { + pathLog = envPathLog; + } + + Cotto cotto(pathLog, pathCertificate, certificatePassword); + return cotto.workflow(objectUuid, developerId, fileExtension, pathDownload, forceOverwrite); +} diff --git a/include/otto.h b/include/otto.h new file mode 100644 index 0000000..7cc9e1a --- /dev/null +++ b/include/otto.h @@ -0,0 +1,585 @@ +#ifndef OTTO_H_ +#define OTTO_H_ + +#include "otto_statuscode.h" +#include "otto_types.h" + +#include + +/** + * @file +* @brief Deklaration der Otto-Funktionen + * + */ + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Erstellt und initialisiert eine neue Otto-Instanz. + * + * Das Erzeugen einer Otto-Instanz ist ressourcen- und zeitintensiv. + * Daher sollten nicht mehr Instanzen erzeugt werden, als gleichzeitig + * benutzt werden sollen. + * + * Speziell braucht nicht für jeden neuen Thread eine neue Instanz erstellt + * zu werden, da die Otto-Instanzen nicht an ihre Ersteller-Threads + * gebunden sind. Otto-Instanzen dürfen _nicht gleichzeitig_ in mehreren + * Threads verwendet werden, aber sie dürfen wechselnd von verschiedenen + * Threads verwendet werden. Das heißt insbesondere, dass sie von neuen + * Threads wiederverwendet werden dürfen. + * + * Otto-Instanzen sind in dem Sinne threadsicher, dass verschiedene + * Otto-Instanzen zeitgleich in verschiedenen Threads verwendet werden können. + * Jedoch darf ein- und dieselbe Otto-Instanz nicht zeitgleich in mehreren + * Threads verwendet werden. + * + * @param[in] logPfad + * Optionaler Pfad zur Log-Datei otto.log. Ist der + * Wert gleich @c NULL, wird das betriebssystemspezifische + * Verzeichnis für temporäre Dateien verwendet. + * + * @param[in] logCallback + * Callback-Funktion, die gegebenenfalls von Otto bei der + * Protokollierung von Meldungen aufgerufen wird. + * Siehe ::OttoLogCallback + * Der Parameter darf @c NULL sein. + * + * @param[in] logCallbackBenutzerdaten + * Beliebiger Zeiger auf Daten, den Otto beim Aufruf eines + * @p logCallback an den Callback weiterreicht. + * Über diesen Weg kann sich eine Anwendung eigene Daten an + * ihre Log-Callback-Funktion übergeben lassen. + * Der Parameter darf @c NULL sein. + * + * @param[out] instanz + * Handle der erzeugten Otto-Instanz + * + * @note Kann kein otto.log angelegt werden, wird eine entsprechende + * Fehlermeldung auf die Konsole (stderr) geschrieben und an den + * Windows-Ereignisdienst bzw. den syslogd-Dienst (Linux, AIX, macOS) + * geschickt. + * Für Linux, AIX und macOS ist zu beachten, dass der syslogd-Dienst + * gegebenenfalls erst noch zu aktivieren und für die Protokollierung + * von Meldungen der Facility "User" zu konfigurieren ist. + * Suchkriterien für Otto-Meldungen in der Windows-Ereignisansicht + * sind "ERiC (Elster Rich Client)" als Quelle und "Anwendung" + * als Protokoll. + * Suchkriterien für ERiC-Meldungen in den Systemlogdateien + * unter Linux, AIX und macOS sind die Facility "User" und + * der Ident "ERiC (Elster Rich Client)". + * + * @see + * - OttoInstanzFreigeben() + * - OttoLogCallback + */ +OttoStatusCode OttoInstanzErzeugen(const byteChar *logPfad, + OttoLogCallback logCallback, + void *logCallbackBenutzerdaten, + OttoInstanzHandle *instanz); + +/** + * @brief Gibt eine Otto-Instanz frei. + * + * Die freigegebene Otto-Instanz sowie alle eventuell noch daran + * gebundenen Objekte dürfen nach der Freigabe nicht mehr verwendet + * werden. + * + * @param[in] instanz + * Handle der Otto-Instanz, die freigegeben werden soll. + * + * @see + * - OttoInstanzErzeugen() + */ +OttoStatusCode OttoInstanzFreigeben(OttoInstanzHandle instanz); + +/** + * @brief Erstellt ein Otto-Zertifikatsobjekt für ein Sicherheitstoken. + * + * Das Zertifikatsobjekt ist an die Otto-Instanz gebunden, für die es erzeugt + * wurde und darf nicht zusammen mit einer anderen Otto-Instanz oder mit + * Objekten anderen Otto-Instanzen verwendet werden. + * Soll ein Sicherheitstoken von mehreren Otto-Instanzen verwendet werden, so + * sind hierfür mehrere Zertifikatsobjekte zu erstellen: für jede Instanz eines. + * + * @param[in] instanz + * Handle der Otto-Instanz, die das Zertifikatsobjekt verwenden soll. + * + * @param[in] zertifikatsPfad + * Pfad zum Sicherheitstoken, folgende Angaben sind möglich: + * 1. Clientseitig erzeugtes Zertifikat:
+ * Pfad zum Verzeichnis, in dem sich die Zertifikats-Datei (.cer) + * und die Datei mit dem privaten Schlüssel (.p12) befinden. + * Diese Sicherheitstokens wurden mit EricMtCreateKey() bzw. EricCreateKey() erzeugt. + * Der Pfad zum Verzeichnis ist bei clientseitig erzeugten + * Zertifikaten relativ zum aktuellen Arbeitsverzeichnis oder absolut + * anzugeben. + * 2. Software-Portalzertifikat:
+ * Pfad zur Software-Zertifikatsdatei (i.d.R. mit der Endung .pfx). + * Der Pfad zur Datei ist bei Software-Zertifikaten relativ zum + * aktuellen Arbeitsverzeichnis oder absolut anzugeben. + * 3. Sicherheitsstick:
+ * Pfad zur Treiberdatei, siehe (*). Bitte beachten, dass der Treiber + * betriebssystemabhängig sein kann. Weitere Informationen in der + * Anleitung zum Sicherheitsstick oder unter + * https://www.sicherheitsstick.de. + * 4. Signaturkarte: (**)
+ * Pfad zur Treiberdatei, welcher einen Zugriff auf die + * Signaturkarte ermöglicht, siehe (*). Weitere Informationen in + * der Anleitung zur Signaturkarte. + * 5. Elektronischer Personalausweis (nPA) oder Aufenthaltstitel (eAT):
+ * Die URL des eID-Clients wie zum Beispiel der AusweisApp 2. + * In den meisten Fällen lautet diese URL: http://127.0.0.1:24727/eID-Client + * Optional kann auf die folgende Weise noch ein Testmerker angehängt werden: + * http://127.0.0.1:24727/eID-Client?testmerker=520000000 + * Zu den verfügbaren Testmerkern siehe ERiC-Entwicklerhandbuch.pdf, + * Kap. "Testunterstützung bei der ERiC-Anbindung". + * \n\b Wichtig: Das Ad-hoc-Zertifikat, das in diesem Fall für den elektronischen + * Personalausweis erzeugt wird, ist nur 24 Stunden gültig. + * + * (*) Wird der Dateipfad eines Treibers angegeben, ist der Suchmechanismus zu + * beachten, mit dem das jeweilige Betriebssystem dynamische Bibliotheken lädt. + * Weitere Informationen sind der Systemdokumentation zu den Betriebssystemfunktionen + * LoadLibrary() (Windows) bzw. dlopen() (Linux, AIX und macOS) zu entnehmen. + * + * (**) Bei Signaturkarten erfolgt eine PIN-Abfrage nicht beim Aufruf von + * OttoZertifikatOeffnen(), sondern erst, wenn beim Versand oder Empfang von Daten + * etwas authentifiziert oder signiert werden muss. + * + * Pfade müssen auf Windows in der für Datei-Funktionen benutzten ANSI-Codepage, + * auf Linux, AIX und Linux Power in der für das Dateisystem benutzten Locale + * und auf macOS in der "decomposed form" von UTF-8 übergeben werden. + * Bitte weitere Betriebssystemspezifika bzgl. nicht erlaubter Zeichen in + * Pfaden und Pfadtrennzeichen beachten. + * Für Details zu Pfaden im ERiC siehe Entwicklerhandbuch Kapitel + * "Übergabe von Pfaden an ERiC API-Funktionen". + * + * @param[in] zertifikatsPasswort + * Das Passwort oder die PIN des Sicherheitstokens. + * Bei Tokens, bei denen das Passwort oder die PIN nicht von der Anwendung + * übergeben, sondern separat über einen Treiber (z. B. von einem Kartenlesegerät) + * abgefragt wird, ist hier NULL zu übergeben. + * + * @param[out] zertifikat + * Handle auf das erstellte Zertifikatsobjekt + * + * @note Aktuell werden von dieser Funktion nur clientseitig erzeugte Zertifikate (CEZs) + * unterstützt. + * + * @see + * - OttoZertifikatSchliessen() + */ +OttoStatusCode OttoZertifikatOeffnen(OttoInstanzHandle instanz, + const byteChar *zertifikatsPfad, + const byteChar *zertifikatsPasswort, + OttoZertifikatHandle *zertifikat); + +/** + * @brief Schließt das Otto-Zertifikatsobjekt zu einem Sicherheitstoken. + * Anschließend darf das Zertifikatsobjekt nicht mehr verwendet werden. + * + * @param[in] zertifikat + * Handle auf das Zertifikatsobjekt, das geschlossen werden soll. + * + * @see + * - OttoZertifikatOeffnen() + */ +OttoStatusCode OttoZertifikatSchliessen(OttoZertifikatHandle zertifikat); + +/** + * @brief Erzeugt einen Rückgabepuffer und gibt ein Handle darauf zurück. + * + * Die von dieser Funktion erzeugten Rückgabepuffer werden verwendet, um + * die Rückgabedaten von Otto-Funktionen (z. B. OttoEmpfangFortsetzen() + * oder OttoVersandBeenden()) aufzunehmen. + * Dazu wird das Rückgabepuffer-Handle für den Schreibvorgang + * an die ausgebende Funktion übergeben. + * + * Zum Auslesen des von den API-Funktionen beschriebenen Puffers wird das + * Rückgabepuffer-Handle an OttoRueckgabepufferInhalt() übergeben. + * Ein einmal erzeugtes Rückgabepuffer-Handle kann für weitere nachfolgende + * Aufrufe von Otto API-Funktionen wiederverwendet werden. Bei einer + * Wiederverwendung eines Handles werden frühere Inhalte überschrieben. + * Nach letztmaliger Verwendung muss jeder Rückgabepuffer mit + * OttoRueckgabepufferFreigeben() freigegeben werden. + * + * Der Rückgabepuffer ist an die Otto-Instanz gebunden, für die er erzeugt + * wurde und kann nicht zusammen mit einer anderen Otto-Instanz oder mit + * Objekten anderen Otto-Instanzen verwendet werden. + * + * @param[in] instanz + * Handle der Otto-Instanz, auf der diese Funktion ausgeführt werden soll. + * + * @param[out] rueckgabepuffer + * Zeiger auf das Handle des erzeugten Rückgabepuffers + * + * @see + * - OttoRueckgabepufferGroesse() + * - OttoRueckgabepufferInhalt() + * - OttoRueckgabepufferFreigeben() + */ +OttoStatusCode OttoRueckgabepufferErzeugen(OttoInstanzHandle instanz, + OttoRueckgabepufferHandle *rueckgabepuffer); + +/** + * @brief Gibt die Anzahl der im Rückgabepuffer + * enthaltenen Bytes zurück. + * + * @param[in] rueckgabepuffer + * Das Handle des Rückgabepuffers + * + * @return + * - Anzahl der im Rückgabepuffer enthaltenen Bytes, + * wenn ein gültiges Handle übergeben wird. + * - 0 sonst + * + * @see + * - OttoRueckgabepufferInhalt() + * - OttoRueckgabepufferErzeugen() + * - OttoRueckgabepufferFreigeben() + */ +uint64_t OttoRueckgabepufferGroesse(OttoRueckgabepufferHandle rueckgabepuffer); + +/** + * @brief Gibt den Inhalt eines Rückgabepuffers zurück. + * + * Der zurückgegebene Zeiger verweist auf ein Byte-Array, das alle in + * den Rückgabepuffer geschriebenen Bytes enthält. + * Dieses Array existiert so lange im Speicher, bis der Rückgabepuffer + * entweder (bei einer Wiederverwendung des Handles) erneut beschrieben + * oder der Puffer explizit freigegeben wird. + * + * @param[in] rueckgabepuffer + * Das Handle des Rückgabepuffers, dessen Inhalt zurückgegeben werden soll. + * + * @return + * - Zeiger auf den Rückgabepufferinhalt, wenn ein gültiges Handle übergeben wird. + * - NULL sonst + * + * @see + * - OttoRueckgabepufferGroesse() + * - OttoRueckgabepufferErzeugen() + * - OttoRueckgabepufferFreigeben() + */ +const byteChar *OttoRueckgabepufferInhalt(OttoRueckgabepufferHandle rueckgabepuffer); + +/** + * @brief Gibt einen Rückgabepuffer frei. + * + * Das Handle des Rückgabepuffers darf danach nicht weiter verwendet werden. + * Es wird daher empfohlen, Handle-Variablen nach der Freigabe explizit auf + * @c NULL zu setzen. + * + * @param[in] rueckgabepuffer + * Handle auf den Rückgabepuffer, der freigegeben werden soll. + * Dieser Rückgabepuffer darf nicht bereits freigegeben worden sein. + * + * @see + * - OttoRueckgabepufferGroesse() + * - OttoRueckgabepufferInhalt() + * - OttoRueckgabepufferErzeugen() + */ +OttoStatusCode OttoRueckgabepufferFreigeben(OttoRueckgabepufferHandle rueckgabepuffer); + +/** + * @brief Erzeugt ein Objekt zur Berechnung einer Datenprüfsumme, die Otto + * zu Beginn einer Übermittlung an den OTTER-Server senden muss. + * + * Das Prüfsummenobjekt ist an die Otto-Instanz gebunden, für die es erzeugt + * wurde und darf nicht zusammen mit einer anderen Otto-Instanz oder mit + * Objekten anderen Otto-Instanzen verwendet werden. + * + * @param[in] instanz + * Handle der Otto-Instanz, für die das Prüfsummenobjekt erzeugt werden soll. + * + * @param[out] pruefsumme + * Handle des erzeugten Prüfsummenobjekts + * + * @see + * - OttoPruefsummeAktualisieren() + * - OttoPruefsummeSignieren() + * - OttoPruefsummeFreigeben() + */ +OttoStatusCode OttoPruefsummeErzeugen(OttoInstanzHandle instanz, OttoPruefsummeHandle *pruefsumme); + +/** + * @brief Aktualisiert die Prüfsumme über Daten. + * + * @param[in,out] pruefsumme + * Handle der Prüfsumme, die aktualisiert werden soll. + * + * @param[in] datenBlock + * Zeiger auf die Daten, über die die Prüfsumme aktualisiert werden soll. + * + * @param[in] datenBlockGroesse + * Größe der Daten, über die die Prüfsumme aktualisiert werden soll, in Bytes. + * + * @see + * - OttoPruefsummeErzeugen() + * - OttoPruefsummeSignieren() + * - OttoPruefsummeFreigeben() + */ +OttoStatusCode OttoPruefsummeAktualisieren(OttoPruefsummeHandle pruefsumme, + const byteChar *datenBlock, + uint64_t datenBlockGroesse); + +/** + * @brief Erstellt eine Signatur über eine Prüfsumme. + * + * @param[in] pruefsumme + * Handle der Prüfsumme, die signiert werden soll. + * + * @param[in] zertifikat + * Handle des Sicherheitstoken, mit dem die Prüfsumme signiert werden soll. + * + * @param[out] rueckgabepuffer + * Handle des Rückgabepuffers, in den die signierte Prüfsumme + * geschrieben werden soll. + * + * @see + * - OttoPruefsummeErzeugen() + * - OttoPruefsummeAktualisieren() + * - OttoPruefsummeFreigeben() + */ +OttoStatusCode OttoPruefsummeSignieren(OttoPruefsummeHandle pruefsumme, + OttoZertifikatHandle zertifikat, + OttoRueckgabepufferHandle rueckgabepuffer); + +/** + * @brief Gibt ein Prüfsummenobjekt frei. + * + * Das Prüfsummenobjekt darf danach nicht wieder verwendet werden. + * + * @param[in] pruefsumme + * Handle des Prüfsummenobjekts, das freigegeben werden soll. + * + * @see + * - OttoPruefsummeErzeugen() + * - OttoPruefsummeAktualisieren() + * - OttoPruefsummeSignieren() + */ +OttoStatusCode OttoPruefsummeFreigeben(OttoPruefsummeHandle pruefsumme); + +/** + * @brief Initialisiert einen Datenversand an den OTTER-Server. + * + * Das zurückgegebene Handle des Versandobjekts wird der Funktion + * OttoVersandFortsetzen() übergeben, um Daten blockweise hochzuladen. + * Sind alle Daten versendet, wird OttoVersandBeenden() aufgerufen, womit + * der Versand abgeschlossen und das Versandobjekt freigegeben wird.
+ * Bevor der Versand begonnen werden kann, muss eine Prüfsumme über alle zu + * versendenen Daten gebildet (siehe OttoPruefsummeErzeugen()) und mit + * OttoPruefsummeSignieren() signiert werden. + * + * @note Wurde Otto vor dem Aufruf dieser Funktion für einen Proxy mit OttoProxyKonfigurationSetzen() + * konfiguriert, wird der Versand über den Proxy durchgeführt. Die Proxy-Konfiguration wird + * intern an dem Versandobjekt gespeichert und spätere Aufrufe von OttoProxyKonfigurationSetzen() + * haben keinen Einfluss auf den bereits begonnenen Versand. + * + * @param[in] instanz + * Handle der Otto-Instanz, auf der diese Funktion ausgeführt werden soll. + * + * @param[in] signiertePruefsumme + * Signierte Prüfsumme über die Gesamtheit der Daten, die in diesem Versand + * versendet werden sollen. + * + * @param[in] herstellerId + * Hersteller-ID des Softwareproduktes + * + * @param[out] versand + * Handle auf das Versandobjekt. Im Fehlerfall wird kein Versandobjekt erzeugt. + * + * @note Diese Funktion ist derzeit noch nicht verwendbar! + * + * @see + * - OttoVersandFortsetzen() + * - OttoVersandBeenden() + * - OttoProxyKonfigurationSetzen() + */ +OttoStatusCode OttoVersandBeginnen(OttoInstanzHandle instanz, + const byteChar *signiertePruefsumme, + const byteChar *herstellerId, + OttoVersandHandle *versand); + +/** + * @brief Versendet einen Datenblock an den OTTER-Server. + * + * Otto liest den übergebenen Datenblock ein und versendet ihn an den OTTER-Server. + * Wenn @c OTTO_OK zurückgegeben wird, kann diese Funktion einem weiteren Datenblock + * erneut aufgerufen werden. Dies ist zu wiederholen, bis Otto alle zu diesem Versand + * gehörigen Daten erhalten hat.
+ * Ist das Ende der Daten erreicht, muss OttoVersandBeenden() aufgerufen werden. + * Falls OttoVersandFortsetzen() nicht @c OTTO_OK zurückgibt, ist der Versand fehlgeschlagen. + * Auch in diesem Fall muss OttoVersandBeenden() aufgerufen werden, um das Versandobjekt + * freizugeben. + * + * @param[in] versand + * Ein mit OttoVersandBeginnen() erzeugtes Handle + * + * @param[in] datenBlock + * Zeiger auf die zu versendenen Daten. Falls @c NULL wird der Aufruf ignoriert. + * + * @param[in] datenBlockGroesse + * Größe des Arrays @p datenBlock in Bytes. Falls 0 wird der Aufruf ignoriert. + * + * @return + * - ::OTTO_OK im Erfolgsfall + * - ::OTTO_TRANSFER_UNAUTHORIZED + * - ::OTTO_TRANSFER_CONNECTSERVER + * + * @note Diese Funktion ist derzeit noch nicht verwendbar! + * + * @see + * - OttoVersandBeenden() + */ +OttoStatusCode OttoVersandFortsetzen(OttoVersandHandle versand, + const byteChar *datenBlock, + uint64_t datenBlockGroesse); + +/** + * @brief Schließt einen Versand ab und gibt das Versandobjekt frei. + * + * Mit dieser Funktion wird das Ende der Daten gekennzeichnet, der Datenversand abgeschlossen + * und das Versandobjekt wieder freigegeben. + * Im Erfolgsfall wird die vom OTTER-Server vergebene Objekt-ID zurückgegeben, über die die + * versendeten Daten bei OTTER referenziert werden. + * In jedem Fall wird ein gültiges Versandobjekt wieder freigegeben. Das Versandobjekt + * darf nach diesem Aufruf nicht mehr verwendet werden. + * + * @param[in] versand + * Ein mit OttoVersandBeginnen() erzeugtes Handle + * + * @param[out] objektId + * Handle des Rückgabepuffers, in den die Objekt-ID geschrieben werden soll. + * + * @return + * - ::OTTO_OK im Erfolgsfall + * - ::OTTO_TRANSFER_UNAUTHORIZED + * - ::OTTO_TRANSFER_CONNECTSERVER + * - ::OTTO_VERSAND_GERINGE_DATENMENGE + * + * @note Diese Funktion ist derzeit noch nicht verwendbar! + */ +OttoStatusCode OttoVersandBeenden(OttoVersandHandle versand, + OttoRueckgabepufferHandle objektId); + +/** + * @brief Initialisiert eine Datenabholung vom OTTER-Server. + * + * Das zurückgegebene Handle des Empfangsobjekts wird der Funktion + * OttoEmpfangFortsetzen() übergeben, um Daten blockweise abzuholen. + * Sind alle Daten abgeholt, wird OttoEmpfangBeenden() aufgerufen, womit + * das Empfangsobjekt wieder freigegeben wird. + * + * @note Wurde eine Otto-Instanz vor dem Aufruf dieser Funktion mit OttoProxyKonfigurationSetzen() + * für einen Proxy konfiguriert, wird der Empfang über den Proxy durchgeführt. + * Die Proxy-Konfiguration wird intern an dem Empfangsobjekt gespeichert und spätere Aufrufe + * von OttoProxyKonfigurationSetzen() haben keinen Einfluss auf den bereits begonnenen Empfang. + * + * @param[in] instanz + * Handle der Otto-Instanz, auf der diese Funktion ausgeführt werden soll. + * + * @param[in] objektId + * ID des Objekts, das vom OTTER-Server abgeholt werden soll. + * + * @param[in] zertifikat + * Handle auf ein Zertifikatsobjekt + * + * @param[in] herstellerId + * Hersteller-ID des Softwareproduktes + * + * @param[out] empfang + * Handle auf das Empfangsobjekt. Im Fehlerfall wird kein Versandobjekt erzeugt. + * + * @see + * - OttoEmpfangFortsetzen() + * - OttoEmpfangBeenden() + * - OttoProxyKonfigurationSetzen() + * + */ +OttoStatusCode OttoEmpfangBeginnen(OttoInstanzHandle instanz, + const byteChar *objektId, + OttoZertifikatHandle zertifikat, + const byteChar *herstellerId, + OttoEmpfangHandle *empfang); + +/** + * @brief Empfängt einen Datenblock vom OTTER-Server + * + * Otto empfängt Daten vom OTTER-Server und gibt sie blockweise an den Aufrufer zurück. + * Wird @c OTTO_OK zurückgegeben, kann diese Funktion erneut aufgerufen werden und weitere + * Datenblöcke empfangen werden. Werden leere Daten zurückgegeben, ist der Empfang beendet + * und alle Daten wurden empfangen. Dann muss OttoEmpfangBeenden() aufgerufen werden. + * + * @param[in] empfang + * Ein mit OttoEmpfangBeginnen() erzeugtes Handle. + * + * @param[out] datenBlock + * Rückgabepuffer mit allen oder einem Teil der empfangenen Daten. Falls leer, ist der Empfang beendet. + * + * @return + * - ::OTTO_OK + * - ::OTTO_TRANSFER_UNAUTHORIZED + * - ::OTTO_TRANSFER_NOT_FOUND + * + * @see + * - OttoEmpfangBeenden() + */ +OttoStatusCode OttoEmpfangFortsetzen(OttoEmpfangHandle empfang, + OttoRueckgabepufferHandle datenBlock); + +/** + * @brief Gibt das Empfangsobjekt wieder frei. + * + * Das Empfangsobjekt darf nach diesem Aufruf nicht mehr verwendet werden. + * Wird diese Funktion aufgerufen, bevor OttoEmpfangFortsetzen() einen leeren Rückgabepuffer + * zurückgegeben hat, muss angenommen werden, dass die bis dahin empfangenen Daten unvollständig sind. + * + * @param[in] empfang + * Ein mit OttoEmpfangBeginnen() erzeugtes Handle + * + * @return + * - ::OTTO_OK + * - ::OTTO_EMPFANG_VORZEITIG_BEENDET + */ +OttoStatusCode OttoEmpfangBeenden(OttoEmpfangHandle empfang); + +/** + * @brief Konfiguriert eine Otto-Instanz für einen Proxy. + * + * Damit eine Otto-Instanz ihre Internetverbindungen über einen, + * Proxy aufbaut muss ihr die Proxy-Konfiguration über diese Methode + * mitgeteilt werden. + * Die Konfiguration gilt dann für alle Verbindungen der Instanz nach + * außen, d.h. für die Verbindungen zu den OTTER-Servern ebenso wie + * für Verbindungen zum ELSTER-eID-Server bei der Verwendung eines + * elektronischen Personalausweises oder Aufenthaltstitels. + * + * @param[in] instanz + * Die Otto-Instanz, für die die Konfiguration gelten soll. + * + * @param[in] proxyKonfiguration + * Die Proxy-Konfiguration, die von der Otto-Instanz verwendet werden soll. + * Wenn hier @c NULL übergeben wird, verwendet die Otto-Instanz keinen Proxy. + * + * @see + * - OttoProxyKonfiguration + */ +OttoStatusCode OttoProxyKonfigurationSetzen(OttoInstanzHandle instanz, + const OttoProxyKonfiguration* proxyKonfiguration); + +/** + * @brief Gibt die Version der Otto-Bibliothek zurück. + * + * @note Die Version der Otto-Bibliothek ist nicht zwingend gleich der Version + * des ERiC-Auslieferungspaketes, sondern kann davon abweichen. + */ +OttoStatusCode OttoVersion(OttoRueckgabepufferHandle rueckgabepuffer); + +#ifdef __cplusplus +} // extern "C" +#endif + + +#endif /* OTTO_H_ */ diff --git a/include/otto_statuscode.h b/include/otto_statuscode.h new file mode 100644 index 0000000..ccbd8bc --- /dev/null +++ b/include/otto_statuscode.h @@ -0,0 +1,302 @@ +#ifndef OTTO_STATUSCODE_H_ +#define OTTO_STATUSCODE_H_ + +/** + * @file + * @brief Auflistung der Otto-Statuscodes + */ +typedef enum { + /** Die Verarbeitung ist ordnungsgemäß abgeschlossen worden. */ + OTTO_OK = 0, + + + // ======== Otto-Fehler 61 040 x xxx ======== + + + // -------- Interne Fehler 61 040 1 xxx -------- + + /** Es trat ein interner Fehler auf, Details stehen im otto.log. */ + OTTO_INTERNER_FEHLER = 610401001, + + /** Es trat ein unerwarteter Fehler auf, Details stehen im otto.log. */ + OTTO_UNBEKANNTER_FEHLER, + + /** Es trat ein Fehler bei der Erzeugung eines Ad-hoc-Zertifikats für den nPA auf, Details stehen ggf. im otto.log. */ + OTTO_NPA_ZERTIFIKATFEHLER, + + // -------- Transferfehler 61 040 3 xxx -------- + + /** Es trat ein Fehler beim Transfer auf, Details stehen ggf. im otto.log. */ + OTTO_TRANSFER_FEHLER = 610403001, + + /** Es trat ein Fehler bei der Initialisierung des Transfers auf. */ + OTTO_TRANSFER_INIT, + + /** Es konnte keine Verbindung zu den Otter-Servern aufgebaut werden. */ + OTTO_TRANSFER_CONNECTSERVER, + + /** Es konnte keine Verbindung zum Proxy aufgebaut werden. */ + OTTO_TRANSFER_CONNECTPROXY, + + /** Bei der Kommunikation mit dem Server kam es zu einer Zeitüberschreitung. */ + OTTO_TRANSFER_TIMEOUT, + + /** Der Proxy erwartet Anmeldedaten oder der Proxy hat die Verbindung abgelehnt. */ + OTTO_TRANSFER_PROXYAUTH, + + /** Der Client darf die Schnittstelle nicht verwenden. */ + OTTO_TRANSFER_UNAUTHORIZED, + + /** Der Otter-Server hat das Objekt nicht gefunden. */ + OTTO_TRANSFER_NOT_FOUND, + + /** Der Otter-Server hat einen unerwarteten Fehler gemeldet. Möglicherweise ist ein Retry sinnvoll. Details stehen im otto.log. */ + OTTO_TRANSFER_SERVER_FEHLER, + + /** Die empfangenen Daten konnten nicht dekodiert werden. */ + OTTO_TRANSFER_DECODING, + + /** Es konnte kein Ad-hoc-Zertifikat für den Personalausweis oder den Aufenthaltstitel erzeugt bzw. gefunden werden, Details stehen ggf. im otto.log. */ + OTTO_TRANSFER_EID_ZERTIFIKATFEHLER, + + /** Der eID-Client ist nicht erreichbar. Wahrscheinlich wurde er nicht gestartet oder die übergebene lokale URL ist nicht korrekt. */ + OTTO_TRANSFER_EID_KEINCLIENT, + + /** Für die Identifikationsnummer des Benutzers existiert kein Konto bei ELSTER. */ + OTTO_TRANSFER_EID_KEINKONTO, + + /** Der eID-Client hat einen Fehler gemeldet. Details zu dem Fehler finden Sie im Log des eID-Clients oder ggf. im otto.log. */ + OTTO_TRANSFER_EID_CLIENTFEHLER, + + /** Der Personalausweis wird von einem anderen Vorgang blockiert. Beenden Sie den anderen Vorgang und versuchen Sie es dann erneut. */ + OTTO_TRANSFER_EID_NPABLOCKIERT, + + // -------- Anwendungsfehler 61 040 5 xxx -------- + + /** Einer der übergebenen Parameter ist ungültig. */ + OTTO_UNGUELTIGER_PARAMETER = 610405001, + + /** Das übergebene Handle ist ungültig. */ + OTTO_UNGUELTIGES_HANDLE, + + /** Die übergebene Otto-Instanz wird gerade (zum Beispiel in einem anderen Thread) verwendet. */ + OTTO_MEHRFACHAUFRUFE_NICHT_UNTERSTUETZT, + + /** Eines der übergebenen Otto-Objekte wurde mit einer anderen Otto-Instanz erstellt. */ + OTTO_INSTANZEN_INKONSISTENT, + + /** Mit dieser Instanz wurden Unterobjekte erzeugt, die noch nicht freigegeben worden sind. */ + OTTO_INSTANZ_UNTEROBJEKTE_NICHT_FREIGEGEBEN, + + /** Die Protokolldatei konnte nicht erzeugt oder geöffnet werden. */ + OTTO_LOG_FEHLER, + + /** Die verwendetet Funktion oder Funktionalität wird nicht, noch nicht oder nicht mehr unterstützt. */ + OTTO_FUNKTION_NICHT_UNTERSTUETZT, + + /** Für das Zertifikat wurde ein falsches Passwort bzw. eine falsche PIN angegeben. */ + OTTO_ZERTIFIKAT_PIN_FALSCH, + + /** Unter dem angegebenen Pfad wurde kein Zertifikat gefunden. */ + OTTO_ZERTIFIKAT_PFAD_FALSCH, + + /** Das Zertifikat wurde nicht erkannt, Details stehen ggf. im otto.log. */ + OTTO_ZERTIFIKAT_NICHT_ERKANNT, + + /** Die Prüfsumme wurde bereits finalisiert */ + OTTO_PRUEFSUMME_FINALISIERT, + + /** Es wurde keine oder eine ungültige Hersteller-ID in den Einstellungen gesetzt. */ + OTTO_UNGUELTIGE_HERSTELLERID, + + /** Der Empfang wurde durch einen API-Aufruf vorzeitig beendet. */ + OTTO_EMPFANG_VORZEITIG_BEENDET, + + /** Die Versanddaten dürfen die Mindestgröße nicht unterschreiten. */ + OTTO_VERSAND_GERINGE_DATENMENGE, + + /** Die eSigner-Bibliothek konnte nicht geladen werden, Details stehen ggf. im otto.log */ + OTTO_ESIGNER_NICHT_GELADEN, + + /** Die eSigner-Bibliothek ist veraltet, Details stehen ggf. im otto.log. */ + OTTO_ESIGNER_VERALTET, + + /** Die eSigner-Bibliothek ist mit der Otto-Bibliothek inkompatibel. */ + OTTO_ESIGNER_INKOMPATIBEL, + + /** Es wurde keine URL oder IP für den Proxy angegeben. */ + OTTO_PROXY_URL, + + /** Es wurde kein oder ein ungültiger Port für den Proxy angegeben. */ + OTTO_PROXY_PORT, + + /** Es wurde kein gültiges Proxy-Authentifizierungschema angegeben. */ + OTTO_PROXY_AUTHSCHEMA, + + + // -------- Anwendungsfehler, die vom eSigner durchgereicht werden 61 040 5 8xx -------- + + /** eSigner: Überlastung */ + OTTO_ESIGNER_BUSY = 610405801, + + /** eSigner: Fehler beim Entschlüsseln */ + OTTO_ESIGNER_DECRYPT, + + /** eSigner: Fehler beim Verschlüsseln */ + OTTO_ESIGNER_ENCRYPT, + + /** eSigner: Fehler beim Encoding */ + OTTO_ESIGNER_ENCODE_ERROR, + + /** eSigner: Parameter Fehler: unbekanntes Encoding */ + OTTO_ESIGNER_ENCODE_UNKNOWN, + + /** eSigner: Eine Laufzeitausnahme ist aufgetreten und abgefangen worden. */ + OTTO_ESIGNER_ESICL_EXCEPTION, + + /** eSigner: Ungültiges Token-Handle */ + OTTO_ESIGNER_INVALID_HANDLE, + + /** eSigner: PKCS11- bzw. PC/SC-Bibliothek fehlt oder ist nicht ausführbar. */ + OTTO_ESIGNER_LOAD_DLL, + + /** eSigner: Zu viele Sessions geöffnet. */ + OTTO_ESIGNER_MAX_SESSION, + + /** eSigner: Der PC/SC-Dienst ist nicht gestartet. */ + OTTO_ESIGNER_NO_SERVICE, + + /** eSigner: Kein Signatur/Verschlüsselungszertifikat bzw. -schlüssel vorhanden. */ + OTTO_ESIGNER_NO_SIG_ENC_KEY, + + /** eSigner: Speicherallokation fehlgeschlagen. */ + OTTO_ESIGNER_OUT_OF_MEM, + + /** eSigner: Fehler beim Zugriff auf Hard-Token-Entschlüsselungsschlüssel */ + OTTO_ESIGNER_P11_ENC_KEY, + + /** eSigner: Die PKCS#11-Engine wird von einer anderen Bibliothek belegt. */ + OTTO_ESIGNER_P11_ENGINE_LOADED, + + /** eSigner: P11 Initialer Token-Zugriff fehlgeschlagen. */ + OTTO_ESIGNER_P11_INIT_FAILED, + + /** eSigner: P11 Verschlüsselungszertifikat fehlt. */ + OTTO_ESIGNER_P11_NO_ENC_CERT, + + /** eSigner: P11 Signaturzertifikat fehlt. */ + OTTO_ESIGNER_P11_NO_SIG_CERT, + /** eSigner: Fehler beim Zugriff auf den Hard-Token-Signaturschlüssel */ + OTTO_ESIGNER_P11_SIG_KEY, + /** eSigner: Leere Slot-Liste, d.h. keine Karte eingesteckt. */ + OTTO_ESIGNER_P11_SLOT_EMPTY, + + /** eSigner: Temporäres PKCS#12-Token konnte nicht erzeugt werden. */ + OTTO_ESIGNER_P12_CREATE, + + /** eSigner: Fehler beim Dekodieren des PKCS#12-Objekts */ + OTTO_ESIGNER_P12_DECODE, + + /** eSigner: Fehler beim Zugriff auf den Soft-PSE-Entschlüsselungsschlüssel */ + OTTO_ESIGNER_P12_ENC_KEY, + + /** eSigner: Fehler beim Zugriff auf den Soft-PSE-Signaturschlüssel */ + OTTO_ESIGNER_P12_SIG_KEY, + + /** eSigner: P12 Verschlüsselungszertifikat fehlt. */ + OTTO_ESIGNER_P12_NO_ENC_CERT, + + /** eSigner: P12 Signaturzertifikat fehlt. */ + OTTO_ESIGNER_P12_NO_SIG_CERT, + + /** eSigner: Fehler beim Lesen des PKCS#12-Objekts */ + OTTO_ESIGNER_P12_READ, + + /** eSigner: Fehler beim Dekodieren des PKCS#7-Objekts */ + OTTO_ESIGNER_P7_DECODE, + + /** eSigner: Fehler beim Lesen des PKCS#7-Objekts */ + OTTO_ESIGNER_P7_READ, + + /** eSigner: Das Entschlüsselungszertifikat ist nicht in der Empfängerliste enthalten. */ + OTTO_ESIGNER_P7_RECIPIENT, + + /** eSigner: Die PIN bzw. das Passwort ist gesperrt. */ + OTTO_ESIGNER_PIN_LOCKED, + + /** eSigner: Die PIN bzw. das Passwort ist falsch. */ + OTTO_ESIGNER_PIN_WRONG, + + /** eSigner: Der Pfad zum Soft-PSE ist falsch oder ungültig. */ + OTTO_ESIGNER_PSE_PATH, + + /** eSigner: Fehler beim Zugriff auf den Stick-Entschlüsselungsschlüssel. */ + OTTO_ESIGNER_SC_ENC_KEY, + + /** eSigner: Initialer Token-Zugriff auf die PC/SC-Schnittstelle fehlgeschlagen. */ + OTTO_ESIGNER_SC_INIT_FAILED, + + /** eSigner: Kein unterstütztes Applet gefunden. */ + OTTO_ESIGNER_SC_NO_APPLET, + + /** eSigner: PC/SC Verschlüsselungszertifikat fehlt. */ + OTTO_ESIGNER_SC_NO_ENC_CERT, + + /** eSigner: PC/SC Signaturzertifikat fehlt. */ + OTTO_ESIGNER_SC_NO_SIG_CERT, + + /** eSigner: Fehler in der Karten-Session. */ + OTTO_ESIGNER_SC_SESSION, + + /** eSigner: Fehler beim Zugriff auf den Stick-Signaturschlüssel */ + OTTO_ESIGNER_SC_SIG_KEY, + + /** eSigner: Es ist keine Karte bzw. kein Stick eingesteckt. */ + OTTO_ESIGNER_SC_SLOT_EMPTY, + + /** eSigner: Der Token-Typ der CA (Certification Authority, Zertifizierungsstelle) stimmt nicht mit dem internen Token-Typ überein. */ + OTTO_ESIGNER_TOKEN_TYPE_MISMATCH, + + /** eSigner: Die Aktion wurde vom Benutzer abgebrochen. */ + OTTO_ESIGNER_USER_CANCEL, + + /** eSigner: Die Zertifikatskette konnte nicht verifiziert werden. */ + OTTO_ESIGNER_VERIFY_CERT_CHAIN, + + /** eSigner: Die Datenstruktur ist nicht initialisiert. */ + OTTO_ESIGNER_DATA_NOT_INITIALIZED, + + /** eSigner: Der Lesepuffer zum Dekodieren der ASN.1-Struktur ist zu klein. */ + OTTO_ESIGNER_ASN1_READ_BUFFER_TOO_SMALL, + + /** eSigner: Die Daten der ASN.1-Struktur sind unvollstaendig. */ + OTTO_ESIGNER_ASN1_READ_DATA_INCOMPLETE, + + // -------- Systemfehler 61 040 7 xxx -------- + + /** Fehler beim Einlesen der otto.ini-default. */ + OTTO_INIDATEI_LESEFEHLER = 610407001, + + /** Das Zertifikat konnte nicht geladen werden. */ + OTTO_ZERTIFIKAT_LESEFEHLER, + + /** Die Zertifikatsdatei oder das Soft-PSE ist defekt. */ + OTTO_ZERTIFIKAT_DEFEKT, + + /** Für das Zertifikat konnte kein Fingerabdruck erstellt werden. */ + OTTO_ZERTIFIKAT_FINGERABDRUCK_FEHLER, + + /** Die Daten konnten mit dem übergebenen Zertifikat nicht signiert werden. */ + OTTO_SIGNIEREN_FEHLGESCHLAGEN, + + /** Die Daten konnten mit dem übergebenen Zertifikat nicht entschlüsselt werden. */ + OTTO_ENTSCHLUESSELN_FEHLGESCHLAGEN, + + /** Die Daten konnten nicht dekomprimiert werden. */ + OTTO_DEKOMPRESSION_FEHLGESCHLAGEN, + + /** Es ist nicht genügend Arbeitsspeicher vorhanden. */ + OTTO_NICHT_GENUEGEND_ARBEITSSPEICHER +} OttoStatusCode; + +#endif /* OTTO_STATUSCODE_H_ */ diff --git a/include/otto_types.h b/include/otto_types.h new file mode 100644 index 0000000..8e7d781 --- /dev/null +++ b/include/otto_types.h @@ -0,0 +1,177 @@ +#ifndef OTTO_TYPES_H_ +#define OTTO_TYPES_H_ + +/** + * @file + * @brief Definition von Datenstrukturen und Datentypen + * + */ + +/** + * @brief Handle auf eine Otto-Instanz + * + * Jede Funktion der Otto-API ist direkt oder indirekt an eine Otto-Instanz gebunden. + * Die Otto-Instanz enthält sämtliche veränderlichen Zustände von Otto. + * \n Es können mehrere Instanzen gleichzeitig existieren. Jede der + * Instanzen ist unabhängig von allen anderen. Verfügen mehrere Threads über + * jeweils ihre eigene Otto-Instanz, können sie diese Instanzen + * parallel verwenden. + * \n Eine Otto-Instanz soll nicht für jede Aufgabe neu erstellt und konfiguriert + * werden. Das Erstellen und Zerstören einer Otto-Instanz ist ressourcen- und zeitintensiv. + * Die Lebenszeit einer Otto-Instanz sollte beispielsweise eher der Lebenszeit + * eines Arbeiter-Threads in einem Pool entsprechen als der Verarbeitungsdauer + * einer einzelnen Aufgabe eines Arbeiter-Threads. + * \n Eine Otto-Instanz kann zwischen Threads ausgetauscht werden. Sie darf aber nicht + * in zwei Threads gleichzeitig verwendet werden. + * + * @see + * - OttoInstanzErzeugen() + * - OttoInstanzFreigeben() + */ +typedef struct OttoInstanz *OttoInstanzHandle; + +/** + * @brief Handle auf ein Sicherheitstoken zur Authentifizierung des + * Daten-Übermittlers oder -Abholers + */ +typedef struct OttoZertifikat *OttoZertifikatHandle; + +/** @brief Handle auf einen Otto-Rückgabepuffer + * + * Ein Otto-Rückgabepuffer dient zur Übergabe von Daten vom Otto an + * die Anwendung. Die Anwendung erstellt dazu einen Otto-Rückgabepuffer + * und übergibt dessen Handle als Parameter einer API-Funktion an den Otto. + * Der Otto befüllt den Otto-Rückgabepuffer dann mit Daten. + * + * @note Eventuell bereits im Otto-Rückgabepuffer befindliche Daten werden beim + * Aufruf von API-Funktionen gelöscht. Ausgenommen davon sind natürlich die + * API-Funktionen mit dem Präfix "OttoRueckgabepuffer", die einen Otto-Rückgabepuffer + * selbst behandeln. + * + * @see + * - OttoRueckgabepufferErzeugen() + * - OttoRueckgabepufferFreigeben() + * - OttoRueckgabepufferInhalt() + * - OttoRueckgabepufferGroesse() + */ +typedef struct OttoRueckgabepuffer *OttoRueckgabepufferHandle; + +/** + * @brief Handle auf eine Otto-Prüfsumme + * + * Um die Datenintegrität sicherzustellen, ist beim Versand von Daten + * an den OTTER-Server eine Prüfsumme über die Daten zu übermitteln.
+ * Diese Prüfsumme ist schon beim Verbindungsaufbau an die Server zu + * übermitteln und kann daher nicht während der Datenübertragung + * implizit gebildet werden, sondern muss vorab explizit berechnet werden. + */ +typedef struct OttoPruefsumme *OttoPruefsummeHandle; + +/** + * @brief Handle auf ein Otto-Versandobjekt + * + * Über ein Versandobjekt können Daten blockweise an die OTTER-Server + * übermittelt werden. + */ +typedef struct OttoVersand *OttoVersandHandle; + +/** + * @brief Handle auf ein Otto-Empfangsobjekt + * + * Über ein Empfangsobjekt können Daten blockweise vom OTTER-Server + * heruntergeladen werden. + */ +typedef struct OttoEmpfang *OttoEmpfangHandle; + +/** + * @brief Aufzählung der Log-Ebenen von Otto + * + * Die Log-Meldungen von Otto sind in Ebenen angeordnet: + * von der höchsten Ebene mit den wichtigsten Fehlermeldungen + * bis hin zu niedrigsten Ebene mit einfachen Meldungen, die + * nur bei der Suche nach Fehlerursachen interessant sind.
+ * Standardmäßig werden nur Meldungen der beiden höchsten Ebenen + * (Fehler und Warnungen) protokolliert.
+ * Sollen auch Meldungen der niedrigeren Ebenen protokolliert werden, + * so kann über die Funktion OttoInstanzErzeugen() ein Callback vom + * Typ ::OttoLogCallback registriert werden, in dem die Meldungen + * nach der Ebene gefiltert werden können. + * + * @see OttoInstanzErzeugen() + */ +typedef enum { + /// Fehler, die zum Abbruch der gewünschten Aktion führen. + OTTOLOG_FEHLERMELDUNGEN = 4, + + /// Hinweise auf Zustände, die zu Fehlern führen können. + OTTOLOG_WARNUNGEN = 3, + + /// Grobe Informationen über den Programmablauf und Werte. + OTTOLOG_INFORMATIONEN = 2, + + /// Feingranulare Informationen über den Programmablauf und Werte. + OTTOLOG_DEBUGMELDUNGEN = 1 +} OttoLogEbene; + +/** + * @brief Funktionstyp für einen Log-Callback, den eine Anwendung beim Erzeugen + * einer Otto-Instanz angeben kann. + * + * @return 0 wenn die Log-Meldung erfolgreich entgegengenommen werden konnte, + * ungleich 0 im Fehlerfall. + * Momentan wird der Rückgabewert vom Otto jedoch ignoriert. + */ +typedef int (*OttoLogCallback)( const char *instanzId, + const char *logZeitpunkt, + OttoLogEbene logEbene, + const char *logNachricht, + void *benutzerdaten ); + +/** + * @brief Der Datentyp byteChar wird immer dann verwendet, wenn an diesem Parameter + * keine UTF-8 codierte Daten erwartet werden. Diese Daten werden ungeprüft verwendet. + */ +typedef char byteChar; + +/** + * @brief Diese Struktur enthält alle Informationen, die Otto benötigt, + * um die Verbindung zum OTTER-Server oder dem ELSTER-eID-Server über + * einen HTTPS-Proxy aufzubauen. + * + * @param version + * Die Version der Struktur. Hier ist aktuell fest der Wert 1 zu setzen. + * + * @param url + * Die URL des Proxies. + * Dieses Element darf nicht NULL sein. + * + * @param benutzerName + * Der Benutzername für eine Proxy-Authentifizierung. + * Dieses Element darf NULL sein. + * + * @param benutzerPasswort + * Das Passwort für eine Proxy-Authentifizierung. + * Dieses Element darf NULL sein. + * + * @param authentifizierungsMethode + * Die Authentifizierungsmethode, mit der der Proxy arbeitet. + * Folgende Methoden werden unterstützt: + * - "Any" + * - "Basic" + * - "Digest" + * - "DigestIE" + * - "NTLM" + * - "SPNEGO" + * Mehrere Werte sind durch Kommas getrennt anzugeben. + * Die Groß-, Kleinschreibung der Werte wird ignoriert. + * Dieses Element darf nicht NULL sein. + */ +typedef struct { + int version; // Aktuell immer auf 1 zu setzen + const byteChar *url; + const byteChar *benutzerName; + const byteChar *benutzerPasswort; + const char *authentifizierungsMethode; +} OttoProxyKonfiguration; + +#endif /* OTTO_TYPES_H_ */ diff --git a/rechtlogisch-cotto-banner.png b/rechtlogisch-cotto-banner.png new file mode 100644 index 0000000..4d90192 Binary files /dev/null and b/rechtlogisch-cotto-banner.png differ diff --git a/vendor/.gitignore b/vendor/.gitignore new file mode 100644 index 0000000..bf27f31 --- /dev/null +++ b/vendor/.gitignore @@ -0,0 +1,3 @@ +* +!.gitignore +!.gitkeep diff --git a/vendor/.gitkeep b/vendor/.gitkeep new file mode 100644 index 0000000..c846774 --- /dev/null +++ b/vendor/.gitkeep @@ -0,0 +1 @@ +Place (lib)otto.{so,dylib,dll} here.