ERiC API-Referenz 43.3.2.0
Lade ...
Suche ...
Keine Treffer
Funktionen
otto.h-Dateireferenz

Deklaration der Otto-Funktionen. Mehr ...

#include "otto_statuscode.h"
#include "otto_types.h"
#include <stdint.h>
+ Include-Abhängigkeitsdiagramm für otto.h:

gehe zum Quellcode dieser Datei

Funktionen

OttoStatusCode OttoInstanzErzeugen (const byteChar *logPfad, OttoLogCallback logCallback, void *logCallbackBenutzerdaten, OttoInstanzHandle *instanz)
 Erstellt und initialisiert eine neue Otto-Instanz.
 
OttoStatusCode OttoInstanzFreigeben (OttoInstanzHandle instanz)
 Gibt eine Otto-Instanz frei.
 
OttoStatusCode OttoZertifikatOeffnen (OttoInstanzHandle instanz, const byteChar *zertifikatsPfad, const byteChar *zertifikatsPasswort, OttoZertifikatHandle *zertifikat)
 Erstellt ein Otto-Zertifikatsobjekt für ein Sicherheitstoken.
 
OttoStatusCode OttoZertifikatOeffnenAusBytes (OttoInstanzHandle instanz, const byteChar *pkcs12Container, uint32_t containerGroesse, const byteChar *zertifikatsPasswort, OttoZertifikatHandle *zertifikat)
 Erstellt ein Otto-Zertifikatsobjekt für ein PKCS#12-Sicherheitstoken, das im Hauptspeicher übergeben wird.
 
OttoStatusCode OttoZertifikatSchliessen (OttoZertifikatHandle zertifikat)
 Schließt das Otto-Zertifikatsobjekt zu einem Sicherheitstoken. Anschließend darf das Zertifikatsobjekt nicht mehr verwendet werden.
 
OttoStatusCode OttoRueckgabepufferErzeugen (OttoInstanzHandle instanz, OttoRueckgabepufferHandle *rueckgabepuffer)
 Erzeugt einen Rückgabepuffer und gibt ein Handle darauf zurück.
 
uint64_t OttoRueckgabepufferGroesse (OttoRueckgabepufferHandle rueckgabepuffer)
 Gibt die Anzahl der im Rückgabepuffer enthaltenen Bytes zurück. Das abschließende Null-Byte wird nicht mitgezählt.
 
const byteChar * OttoRueckgabepufferInhalt (OttoRueckgabepufferHandle rueckgabepuffer)
 Gibt den Inhalt eines Rückgabepuffers zurück.
 
OttoStatusCode OttoRueckgabepufferFreigeben (OttoRueckgabepufferHandle rueckgabepuffer)
 Gibt einen Rückgabepuffer frei.
 
OttoStatusCode OttoPruefsummeErzeugen (OttoInstanzHandle instanz, OttoPruefsummeHandle *pruefsumme)
 Erzeugt ein Objekt zur Berechnung einer Datenprüfsumme, die Otto zu Beginn einer Übermittlung an den OTTER-Server senden muss.
 
OttoStatusCode OttoPruefsummeAktualisieren (OttoPruefsummeHandle pruefsumme, const byteChar *datenBlock, uint64_t datenBlockGroesse)
 Aktualisiert die Prüfsumme über Daten. Eine Prüfsumme, die bereits signiert wurde, kann nicht mehr aktualisiert werden.
 
OttoStatusCode OttoPruefsummeSignieren (OttoPruefsummeHandle pruefsumme, OttoZertifikatHandle zertifikat, OttoRueckgabepufferHandle rueckgabepuffer)
 Erstellt eine Signatur über eine Prüfsumme.
 
OttoStatusCode OttoPruefsummeFreigeben (OttoPruefsummeHandle pruefsumme)
 Gibt ein Prüfsummenobjekt frei.
 
OttoStatusCode OttoVersandBeginnen (OttoInstanzHandle instanz, const byteChar *signiertePruefsumme, const byteChar *herstellerId, OttoVersandHandle *versand)
 Initialisiert einen Datenversand an den OTTER-Server.
 
OttoStatusCode OttoVersandFortsetzen (OttoVersandHandle versand, const byteChar *datenBlock, uint64_t datenBlockGroesse)
 Versendet einen Datenblock an den OTTER-Server.
 
OttoStatusCode OttoVersandAbschliessen (OttoVersandHandle versand, OttoRueckgabepufferHandle objektId)
 Schließt einen Versand ab und gibt die Objekt-ID zurück.
 
OttoStatusCode OttoVersandBeenden (OttoVersandHandle versand)
 Gibt ein Versandobjekt frei.
 
OttoStatusCode OttoEmpfangBeginnen (OttoInstanzHandle instanz, const byteChar *objektId, OttoZertifikatHandle zertifikat, const byteChar *herstellerId, OttoEmpfangHandle *empfang)
 Initialisiert eine Datenabholung vom OTTER-Server.
 
OttoStatusCode OttoEmpfangBeginnenAbholzertifikat (OttoInstanzHandle instanz, const byteChar *objektId, OttoZertifikatHandle zertifikat, const byteChar *herstellerId, const byteChar *abholzertifikat, OttoEmpfangHandle *empfang)
 Initialisiert eine Datenabholung vom OTTER-Server mit Angabe eines Abholzertifikats.
 
OttoStatusCode OttoEmpfangFortsetzen (OttoEmpfangHandle empfang, OttoRueckgabepufferHandle datenBlock)
 Empfängt einen Datenblock vom OTTER-Server.
 
OttoStatusCode OttoEmpfangBeenden (OttoEmpfangHandle empfang)
 Gibt das Empfangsobjekt wieder frei.
 
OttoStatusCode OttoDatenAbholen (OttoInstanzHandle instanz, const byteChar *objektId, uint32_t objektGroesse, const byteChar *zertifikatsPfad, const byteChar *zertifikatsPasswort, const byteChar *herstellerId, const byteChar *abholzertifikat, OttoRueckgabepufferHandle abholDaten)
 Holt das Datenobjekt zu einer Objekt-ID von OTTER mit einem einzigen Funktionsaufruf vollständig ab.
 
const char * OttoHoleFehlertext (OttoStatusCode statuscode)
 Die Funktion liefert die Klartextfehlermeldung zu einem Otto-Statuscode - definiert in otto_statuscode.h.
 
OttoStatusCode OttoProxyKonfigurationSetzen (OttoInstanzHandle instanz, const OttoProxyKonfiguration *proxyKonfiguration)
 Konfiguriert eine Otto-Instanz für einen Proxy.
 
OttoStatusCode OttoEinstellungSetzen (OttoInstanzHandle instanz, const char *einstellungName, const char *einstellungWert)
 Setzt den Wert einer Otto-Einstellung für die angegebene Instanz.
 
OttoStatusCode OttoEinstellungLesen (OttoInstanzHandle instanz, const char *einstellungName, OttoRueckgabepufferHandle einstellungWert)
 Liest den aktuellen Wert einer Otto-Einstellung in der angegebenen Instanz aus.
 
OttoStatusCode OttoVersion (OttoRueckgabepufferHandle rueckgabepuffer)
 Gibt die Version der Otto-Bibliothek zurück.
 

Ausführliche Beschreibung

Deklaration der Otto-Funktionen.

Definiert in Datei otto.h.

Dokumentation der Funktionen

◆ OttoDatenAbholen()

OttoStatusCode OttoDatenAbholen ( OttoInstanzHandle instanz,
const byteChar * objektId,
uint32_t objektGroesse,
const byteChar * zertifikatsPfad,
const byteChar * zertifikatsPasswort,
const byteChar * herstellerId,
const byteChar * abholzertifikat,
OttoRueckgabepufferHandle abholDaten )

Holt das Datenobjekt zu einer Objekt-ID von OTTER mit einem einzigen Funktionsaufruf vollständig ab.

Diese Funktion ist eine bequemere Alternative zu der blockweisen Datenabholung über die OttoEmpfang-Funktionen. Intern bündelt sie die Aufrufe der OttoEmpfangs-Funktionen, wie sie sonst von der Anwendung selbst durchgeführt werden müßten.

Der Nachteil dieser Funktion gegenüber den OttoEmpfang-Funktionen besteht darin, dass die abgeholten Daten alle im Hauptspeicher von Otto gehalten werden. Sie eignet sich daher nicht für die Abholung sehr großer Datenobjekte oder wenn nur sehr wenig Hauptspeicher zur Verfügung steht.

Zu beachten
Wurde eine Otto-Instanz vor dem Aufruf dieser Funktion mit OttoProxyKonfigurationSetzen() für einen Proxy konfiguriert, wird die Abholung über den Proxy durchgeführt.
Parameter
[in]instanzHandle der Otto-Instanz, auf der diese Funktion ausgeführt werden soll.
[in]objektIdID des Datenobjekts, das vom OTTER-Server abgeholt werden soll.
[in]objektGroesse

Die erwartete Größe des Datenobjekts, das vom OTTER-Server abgeholt werden soll, in Bytes. Diesen Wert findet die Anwendung zusammen mit der Objekt-ID im Rückgabe-XML zu einer PostfachAnfrage.

Wenn die Größe zu gering angegeben wird, geht dies zwar zu Lasten der Geschwindigkeit und des Hauptspeicherbedarfs, weil dann der Rückgabepuffer von Otto intern sukzessive vergrößert werden muß, aber es führt nicht zu einem Fehler.

[in]zertifikatsPfadPfad 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. 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".

    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.

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 ERiC-Entwicklerhandbuch.pdf, Kapitel "Übergabe von Pfaden an ERiC API-Funktionen".

Parameter
[in]zertifikatsPasswortDas 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.
[in]herstellerIdHersteller-ID des Softwareproduktes
[in]abholzertifikat

Base64-kodierter Teil eines X.509-v3-Zertifikats im PEM-Format. Die Angabe eines Abholzertifikats ist optional und nur erlaubt, wenn im Parameter zertifikatsPfad kein clientseitig erzeugtes Zertifikat (CEZ) angegeben wurde.

Wird ein Abholzertifikat übergeben, so werden die Abholdaten vom Server auf den öffentlichen Schlüssel des Zertifikats umgeschlüsselt. Diese Daten werden vom Otto nicht entschlüsselt und OttoDatenAbholen() gibt lediglich die verschlüsselten Daten zurück.

Wenn eine nicht bei ELSTER registrierte Signaturkarte zur Authentifizierung verwendet wird, muss dieser Parameter gesetzt werden, ansonsten kann hier NULL übergeben werden.

[out]abholDatenRückgabepuffer mit den abgeholten Daten. Der Inhalt des Rückgabepuffers darf nicht als null-terminierte Zeichenkette interpretiert werden, da die abgeholten Daten weitere Null-Bytes enthalten können.
Rückgabe

◆ OttoEinstellungLesen()

OttoStatusCode OttoEinstellungLesen ( OttoInstanzHandle instanz,
const char * einstellungName,
OttoRueckgabepufferHandle einstellungWert )

Liest den aktuellen Wert einer Otto-Einstellung in der angegebenen Instanz aus.

Parameter
[in]instanzDie Otto-Instanz, deren Einstellung ausgelesen werden soll.
[in]einstellungNameName der Einstellung, deren Wert ausgelesen werden soll.
[out]einstellungWertDer ausgelesene Wert der Einstellung
Rückgabe
Siehe auch

◆ OttoEinstellungSetzen()

OttoStatusCode OttoEinstellungSetzen ( OttoInstanzHandle instanz,
const char * einstellungName,
const char * einstellungWert )

Setzt den Wert einer Otto-Einstellung für die angegebene Instanz.

Die Einstellungen gelten immer nur für die übergebene Otto-Instanz.

Die Änderungen von Werten ist nicht immer unmittelbar wirksam.

Parameter
[in]instanzDie Otto-Instanz, für die eine Einstellung gesetzt werden soll.
[in]einstellungNameName der Einstellung, deren Wert gesetzt werden soll.
[in]einstellungWertWert, auf den die Einstellung gesetzt werden soll.
Rückgabe
Siehe auch

◆ OttoEmpfangBeenden()

OttoStatusCode OttoEmpfangBeenden ( OttoEmpfangHandle empfang)

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, können die bis dahin empfangenen Daten unvollständig sein.

Parameter
[in]empfangEin mit OttoEmpfangBeginnen() erzeugtes Handle
Rückgabe

◆ OttoEmpfangBeginnen()

OttoStatusCode OttoEmpfangBeginnen ( OttoInstanzHandle instanz,
const byteChar * objektId,
OttoZertifikatHandle zertifikat,
const byteChar * herstellerId,
OttoEmpfangHandle * empfang )

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.

Zu beachten
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.
Parameter
[in]instanzHandle der Otto-Instanz, auf der diese Funktion ausgeführt werden soll.
[in]objektIdID des Objekts, das vom OTTER-Server abgeholt werden soll.
[in]zertifikatHandle auf ein Zertifikatsobjekt
[in]herstellerIdHersteller-ID des Softwareproduktes
[out]empfangHandle auf das Empfangsobjekt. Im Fehlerfall wird kein Empfangobjekt erzeugt.
Rückgabe
Siehe auch

◆ OttoEmpfangBeginnenAbholzertifikat()

OttoStatusCode OttoEmpfangBeginnenAbholzertifikat ( OttoInstanzHandle instanz,
const byteChar * objektId,
OttoZertifikatHandle zertifikat,
const byteChar * herstellerId,
const byteChar * abholzertifikat,
OttoEmpfangHandle * empfang )

Initialisiert eine Datenabholung vom OTTER-Server mit Angabe eines Abholzertifikats.

Die Angabe eines Abholzertifikats ist erforderlich, wenn eine nicht bei ELSTER registrierte Signaturkarte zur Authentifizierung verwendet wird.

Die Funktion darf nicht verwendet werden, wenn zur Authentifizierung ein clientseitig erzeugtes Zertifikat (CEZ) verwendet wird. (Parameter zertifikat)

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.

Ein wichtiger Unterschied zu OttoEmpfangBeginnen() besteht darin, dass der OTTER-Server die Daten auf den in abholzertifikat enthaltenen öffentlichen Schlüssel umschlüsselt. Die Daten werden vom Otto nicht entschlüsselt und OttoEmpfangFortsetzen() gibt lediglich die verschlüsselten Daten zurück.

Zu beachten
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.
Parameter
[in]instanzHandle der Otto-Instanz, auf der diese Funktion ausgeführt werden soll.
[in]objektIdID des Objekts, das vom OTTER-Server abgeholt werden soll.
[in]zertifikatHandle auf ein Zertifikatsobjekt Es darf hier kein clientseitig erzeugtes Zertifikat (CEZ) angegeben werden.
[in]herstellerIdHersteller-ID des Softwareproduktes
[in]abholzertifikatBase64-kodierter Teil eines X.509-v3-Zertifikats im PEM-Format
[out]empfangHandle auf das Empfangsobjekt. Im Fehlerfall wird kein Empfangobjekt erzeugt.
Rückgabe
Siehe auch

◆ OttoEmpfangFortsetzen()

OttoStatusCode OttoEmpfangFortsetzen ( OttoEmpfangHandle empfang,
OttoRueckgabepufferHandle datenBlock )

Empfängt einen Datenblock vom OTTER-Server.

Otto empfängt Daten vom OTTER-Server und gibt sie blockweise an den Aufrufer zurück. Wird 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.

Parameter
[in]empfangEin mit OttoEmpfangBeginnen() erzeugtes Handle.
[out]datenBlock

Rückgabepuffer mit allen oder einem Teil der empfangenen Daten. Falls leer, ist der Empfang beendet.

Der Inhalt des Rückgabepuffers darf nicht als null-terminierte Zeichenkette interpretiert werden, da die empfangenen Daten weitere Null-Bytes enthalten können.

Rückgabe
Siehe auch

◆ OttoHoleFehlertext()

const char * OttoHoleFehlertext ( OttoStatusCode statuscode)

Die Funktion liefert die Klartextfehlermeldung zu einem Otto-Statuscode - definiert in otto_statuscode.h.

Parameter
[in]statuscodeStatuscode
Rückgabe
  • Zeiger auf einen statischen Puffer mit der Klartextmeldung zu einem Statuscode als null-terminierte, UTF-8-kodierte Zeichenkette.
  • NULL, falls kein Text ermittelt werden konnte.

◆ OttoInstanzErzeugen()

OttoStatusCode OttoInstanzErzeugen ( const byteChar * logPfad,
OttoLogCallback logCallback,
void * logCallbackBenutzerdaten,
OttoInstanzHandle * instanz )

Erstellt und initialisiert eine neue Otto-Instanz.

Otto-Instanzen sind nicht an ihre Ersteller-Threads gebunden. Sie dürfen zwar 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 können.

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.

Parameter
[in]logPfadOptionaler Pfad zur Log-Datei otto.log. Ist der Wert gleich NULL, wird das betriebssystemspezifische Verzeichnis für temporäre Dateien verwendet.
[in]logCallbackCallback-Funktion, die gegebenenfalls von Otto bei der Protokollierung von Meldungen aufgerufen wird. Siehe OttoLogCallback Der Parameter darf NULL sein.
[in]logCallbackBenutzerdaten

Beliebiger Zeiger auf Daten, den Otto beim Aufruf eines logCallback an den Callback weiterreicht.

Über diesen Weg kann sich eine Anwendung eigene Daten an ihre Log-Callback-Funktion übergeben lassen. Der Parameter darf NULL sein.

[out]instanzHandle der erzeugten Otto-Instanz
Zu beachten

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)".

Rückgabe
Siehe auch

◆ OttoInstanzFreigeben()

OttoStatusCode OttoInstanzFreigeben ( OttoInstanzHandle instanz)

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.

Parameter
[in]instanzHandle der Otto-Instanz, die freigegeben werden soll.
Rückgabe
Siehe auch

◆ OttoProxyKonfigurationSetzen()

OttoStatusCode OttoProxyKonfigurationSetzen ( OttoInstanzHandle instanz,
const OttoProxyKonfiguration * proxyKonfiguration )

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.

Parameter
[in]instanzDie Otto-Instanz, für die die Konfiguration gelten soll.
[in]proxyKonfigurationDie Proxy-Konfiguration, die von der Otto-Instanz verwendet werden soll. Wenn hier NULL übergeben wird, verwendet die Otto-Instanz keinen Proxy.
Rückgabe
Siehe auch

◆ OttoPruefsummeAktualisieren()

OttoStatusCode OttoPruefsummeAktualisieren ( OttoPruefsummeHandle pruefsumme,
const byteChar * datenBlock,
uint64_t datenBlockGroesse )

Aktualisiert die Prüfsumme über Daten. Eine Prüfsumme, die bereits signiert wurde, kann nicht mehr aktualisiert werden.

Parameter
[in,out]pruefsummeHandle der Prüfsumme, die aktualisiert werden soll.
[in]datenBlockZeiger auf die Daten, über die die Prüfsumme aktualisiert werden soll.
[in]datenBlockGroesseGröße der Daten, über die die Prüfsumme aktualisiert werden soll, in Bytes.
Rückgabe
Siehe auch

◆ OttoPruefsummeErzeugen()

OttoStatusCode OttoPruefsummeErzeugen ( OttoInstanzHandle instanz,
OttoPruefsummeHandle * pruefsumme )

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.

Parameter
[in]instanzHandle der Otto-Instanz, für die das Prüfsummenobjekt erzeugt werden soll.
[out]pruefsummeHandle des erzeugten Prüfsummenobjekts
Rückgabe
Siehe auch

◆ OttoPruefsummeFreigeben()

OttoStatusCode OttoPruefsummeFreigeben ( OttoPruefsummeHandle pruefsumme)

Gibt ein Prüfsummenobjekt frei.

Das Prüfsummenobjekt darf danach nicht wieder verwendet werden.

Parameter
[in]pruefsummeHandle des Prüfsummenobjekts, das freigegeben werden soll.
Rückgabe
Siehe auch

◆ OttoPruefsummeSignieren()

OttoStatusCode OttoPruefsummeSignieren ( OttoPruefsummeHandle pruefsumme,
OttoZertifikatHandle zertifikat,
OttoRueckgabepufferHandle rueckgabepuffer )

Erstellt eine Signatur über eine Prüfsumme.

Die Signierung der Prüfsumme ist nur dann möglich, wenn diese über die Mindestdatenmenge für eine Übermittlung an den OTTER-Server berechnet wurde. (20 MiB) Eine Prüfsumme kann nur einmalig signiert werden. Danach muß das Prüfsummenobjekt freigegeben werden.

Parameter
[in]pruefsummeHandle der Prüfsumme, die signiert werden soll.
[in]zertifikatHandle des Sicherheitstoken, mit dem die Prüfsumme signiert werden soll.
[out]rueckgabepufferHandle des Rückgabepuffers, in den die signierte Prüfsumme geschrieben werden soll. Die signierte Prüfsumme wird als base64-codierte Zeichenfolge übergeben.
Rückgabe
Siehe auch

◆ OttoRueckgabepufferErzeugen()

OttoStatusCode OttoRueckgabepufferErzeugen ( OttoInstanzHandle instanz,
OttoRueckgabepufferHandle * rueckgabepuffer )

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.

Parameter
[in]instanzHandle der Otto-Instanz, auf der diese Funktion ausgeführt werden soll.
[out]rueckgabepufferZeiger auf das Handle des erzeugten Rückgabepuffers
Rückgabe
Siehe auch

◆ OttoRueckgabepufferFreigeben()

OttoStatusCode OttoRueckgabepufferFreigeben ( OttoRueckgabepufferHandle rueckgabepuffer)

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 NULL zu setzen.

Parameter
[in]rueckgabepufferHandle auf den Rückgabepuffer, der freigegeben werden soll. Dieser Rückgabepuffer darf nicht bereits freigegeben worden sein.
Rückgabe
Siehe auch

◆ OttoRueckgabepufferGroesse()

uint64_t OttoRueckgabepufferGroesse ( OttoRueckgabepufferHandle rueckgabepuffer)

Gibt die Anzahl der im Rückgabepuffer enthaltenen Bytes zurück. Das abschließende Null-Byte wird nicht mitgezählt.

Parameter
[in]rueckgabepufferDas Handle des Rückgabepuffers
Rückgabe
  • Anzahl der im Rückgabepuffer enthaltenen Bytes, wenn ein gültiges Handle übergeben wird.
  • 0 sonst
Siehe auch

◆ OttoRueckgabepufferInhalt()

const byteChar * OttoRueckgabepufferInhalt ( OttoRueckgabepufferHandle rueckgabepuffer)

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. Der Array wird immer von einem Null-Byte abgeschlossen. Wenn der Rückgabepuffer keine weiteren Null-Bytes enthält, kann folglich der Rückgabepufferinhalt bequem als null-terminierte Zeichenkette interpretiert werden.

Parameter
[in]rueckgabepufferDas Handle des Rückgabepuffers, dessen Inhalt zurückgegeben werden soll.
Rückgabe
  • Zeiger auf den Rückgabepufferinhalt, wenn ein gültiges Handle übergeben wird.
  • NULL sonst
Siehe auch

◆ OttoVersandAbschliessen()

OttoStatusCode OttoVersandAbschliessen ( OttoVersandHandle versand,
OttoRueckgabepufferHandle objektId )

Schließt einen Versand ab und gibt die Objekt-ID zurück.

Mit dieser Funktion wird das Ende der Daten gekennzeichnet und der Datenversand abgeschlossen.

Im Erfolgsfall wird die vom OTTER-Server vergebene Objekt-ID zurückgegeben, über die die versendeten Daten bei OTTER referenziert werden.

Parameter
[in]versandEin mit OttoVersandBeginnen() erzeugtes Handle
[out]objektIdHandle des Rückgabepuffers, in den die Objekt-ID geschrieben werden soll.
Rückgabe

◆ OttoVersandBeenden()

OttoStatusCode OttoVersandBeenden ( OttoVersandHandle versand)

Gibt ein Versandobjekt frei.

Das Versandobjekt darf danach nicht wieder verwendet werden.

Parameter
[in]versandHandle des Versandobjekts, das freigegeben werden soll.
Rückgabe
Siehe auch

◆ OttoVersandBeginnen()

OttoStatusCode OttoVersandBeginnen ( OttoInstanzHandle instanz,
const byteChar * signiertePruefsumme,
const byteChar * herstellerId,
OttoVersandHandle * versand )

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, ist OttoVersandAbschliessen() aufzurufen, womit der Versand abgeschlossen wird. Zum Freigeben des Versandobjekts ist OttoVersandBeenden() aufzurufen.

Bevor der Versand begonnen werden kann, muss eine Prüfsumme über alle zu versendenen Daten gebildet (siehe OttoPruefsummeErzeugen()) und mit OttoPruefsummeSignieren() signiert werden.

Zu beachten
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.
Parameter
[in]instanzHandle der Otto-Instanz, auf der diese Funktion ausgeführt werden soll.
[in]signiertePruefsumme

Signierte Prüfsumme über die Gesamtheit der Daten, die in diesem Versand versendet werden sollen.

Die signierte Prüfsumme wird als base64-codierte, nullterminierte Zeichenfolge erwartet, wie sie von OttoPruefsummeSignieren() zurückgeliefert wird.

[in]herstellerIdHersteller-ID des Softwareproduktes
[out]versandHandle auf das Versandobjekt. Im Fehlerfall wird kein Versandobjekt erzeugt.
Rückgabe
Siehe auch

◆ OttoVersandFortsetzen()

OttoStatusCode OttoVersandFortsetzen ( OttoVersandHandle versand,
const byteChar * datenBlock,
uint64_t datenBlockGroesse )

Versendet einen Datenblock an den OTTER-Server.

Otto liest den übergebenen Datenblock ein und versendet ihn an den OTTER-Server. Wenn OTTO_OK zurückgegeben wird, kann diese Funktion erneut mit einem weiteren Datenblock aufgerufen werden. Dies ist zu wiederholen, bis Otto alle zu diesem Versand gehörigen Daten erhalten hat. Falls nicht OTTO_OK zurückgegeben wird, ist der Versand fehlgeschlagen.

Ist das Ende der Daten erreicht, muss OttoVersandAbschliessen() aufgerufen werden.

Parameter
[in]versandEin mit OttoVersandBeginnen() erzeugtes Handle
[in]datenBlockZeiger auf die zu versendenen Daten. Falls NULL wird der Aufruf ignoriert.
[in]datenBlockGroesseGröße des Arrays datenBlock in Bytes. Falls 0 wird der Aufruf ignoriert.
Rückgabe
Siehe auch

◆ OttoVersion()

OttoStatusCode OttoVersion ( OttoRueckgabepufferHandle rueckgabepuffer)

Gibt die Version der Otto-Bibliothek zurück.

Zu beachten
Die Version der Otto-Bibliothek ist nicht zwingend gleich der Version des ERiC-Auslieferungspaketes, sondern kann davon abweichen.
Rückgabe

◆ OttoZertifikatOeffnen()

OttoStatusCode OttoZertifikatOeffnen ( OttoInstanzHandle instanz,
const byteChar * zertifikatsPfad,
const byteChar * zertifikatsPasswort,
OttoZertifikatHandle * zertifikat )

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 anderer 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.

Parameter
[in]instanzHandle der Otto-Instanz, die das Zertifikatsobjekt verwenden soll.
[in]zertifikatsPfadPfad zum Sicherheitstoken, folgende Angaben sind möglich:
  1. Clientseitig erzeugtes Zertifikat:
    Pfad 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".

    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 beim Aufruf von OttoPruefsummeSignieren(), OttoEmpfangBeginnen() und OttoEmpfangBeginnenAbholzertifikat().

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 ERiC-Entwicklerhandbuch.pdf, Kapitel "Übergabe von Pfaden an ERiC API-Funktionen".

Parameter
[in]zertifikatsPasswortDas 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.
[out]zertifikatHandle auf das erstellte Zertifikatsobjekt
Rückgabe
Siehe auch

◆ OttoZertifikatOeffnenAusBytes()

OttoStatusCode OttoZertifikatOeffnenAusBytes ( OttoInstanzHandle instanz,
const byteChar * pkcs12Container,
uint32_t containerGroesse,
const byteChar * zertifikatsPasswort,
OttoZertifikatHandle * zertifikat )

Erstellt ein Otto-Zertifikatsobjekt für ein PKCS#12-Sicherheitstoken, das im Hauptspeicher übergeben wird.

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 anderer Otto-Instanzen verwendet werden. Soll ein PKCS#12-Container von mehreren Otto-Instanzen verwendet werden, so sind hierfür mehrere Zertifikatsobjekte zu erstellen: für jede Instanz eines.

Parameter
[in]instanzHandle der Otto-Instanz, die das Zertifikatsobjekt verwenden soll.
[in]pkcs12ContainerAdresse des PKCS#12-Containers im Hauptspeicher. Es werden nur passwortgeschützte PKCS#12-Container akzeptiert.
[in]containerGroesseGröße des PKCS#12-Containers in Bytes
[in]zertifikatsPasswortDas Passwort oder die PIN des PKCS#12-Containers. Dieser Parameter darf nicht NULL sein.
[out]zertifikatHandle auf das erstellte Zertifikatsobjekt
Rückgabe
Siehe auch

◆ OttoZertifikatSchliessen()

OttoStatusCode OttoZertifikatSchliessen ( OttoZertifikatHandle zertifikat)

Schließt das Otto-Zertifikatsobjekt zu einem Sicherheitstoken. Anschließend darf das Zertifikatsobjekt nicht mehr verwendet werden.

Parameter
[in]zertifikatHandle auf das Zertifikatsobjekt, das geschlossen werden soll.
Rückgabe
Siehe auch