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

Deklaration der ERiC API-Funktionen für die Singlethreading-API. Mehr ...

#include "platform.h"
#include "ericapiExport.h"
#include "eric_types.h"
#include "ericdef.h"
+ Include-Abhängigkeitsdiagramm für ericapi.h:

gehe zum Quellcode dieser Datei

Funktionen

ERICAPI_IMPORT int EricBearbeiteVorgang (const char *datenpuffer, const char *datenartVersion, uint32_t bearbeitungsFlags, const eric_druck_parameter_t *druckParameter, const eric_verschluesselungs_parameter_t *cryptoParameter, EricTransferHandle *transferHandle, EricRueckgabepufferHandle rueckgabeXmlPuffer, EricRueckgabepufferHandle serverantwortXmlPuffer)
 Diese API-Funktion ist die zentrale Schnittstellenfunktion zur Kommunikation mit dem ELSTER-Annahmeserver.
 
ERICAPI_IMPORT int EricBeende (void)
 Beendet den Singlethreading-ERiC.
 
ERICAPI_IMPORT int EricChangePassword (const byteChar *psePath, const byteChar *oldPin, const byteChar *newPin)
 Die PIN für ein clientseitig erzeugtes Zertifikat (CEZ) wird geändert.
 
ERICAPI_IMPORT int EricPruefeBuFaNummer (const byteChar *steuernummer)
 Die Bundesfinanzamtsnummer wird überprüft.
 
ERICAPI_IMPORT int EricCheckXML (const char *xml, const char *datenartVersion, EricRueckgabepufferHandle fehlertextPuffer)
 Das xml wird gegen das Schema der datenartVersion validiert.
 
ERICAPI_IMPORT int EricCloseHandleToCertificate (EricZertifikatHandle hToken)
 Das Zertifikat-Handle hToken wird freigegeben.
 
ERICAPI_IMPORT int EricCreateKey (const byteChar *pin, const byteChar *pfad, const eric_zertifikat_parameter_t *zertifikatInfo)
 Es werden die Kryptomittel für ein clientseitig erzeugtes Zertifikat (CEZ) in einem Verzeichnis des Dateisystems erstellt.
 
ERICAPI_IMPORT int EricCreateTH (const char *xml, const char *verfahren, const char *datenart, const char *vorgang, const char *testmerker, const char *herstellerId, const char *datenLieferant, const char *versionClient, const byteChar *publicKey, EricRueckgabepufferHandle xmlRueckgabePuffer)
 Diese Funktion erzeugt einen TransferHeader.
 
ERICAPI_IMPORT int EricCreateUUID (EricRueckgabepufferHandle uuidRueckgabePuffer)
 Erzeugt einen Version 4 Universally Unique Identifier (UUID) gemäß RFC 4122.
 
ERICAPI_IMPORT int EricDekodiereDaten (EricZertifikatHandle zertifikatHandle, const byteChar *pin, const byteChar *base64Eingabe, EricRueckgabepufferHandle rueckgabePuffer)
 Es werden die mit der Datenabholung abgeholten und verschlüsselten Daten entschlüsselt.
 
ERICAPI_IMPORT int EricEinstellungAlleZuruecksetzen (void)
 Alle Einstellungen werden auf den jeweiligen Standardwert zurückgesetzt.
 
ERICAPI_IMPORT int EricEinstellungLesen (const char *name, EricRueckgabepufferHandle rueckgabePuffer)
 Der Wert der API-Einstellung name wird im rueckgabePuffer zurückgeliefert.
 
ERICAPI_IMPORT int EricEinstellungSetzen (const char *name, const char *wert)
 Die API-Einstellung name wird auf den wert gesetzt.
 
ERICAPI_IMPORT int EricEinstellungZuruecksetzen (const char *name)
 Der Wert der API-Einstellung name wird auf den Standardwert zurückgesetzt.
 
ERICAPI_IMPORT int EricEntladePlugins (void)
 Alle verwendeten Plugin-Bibliotheken werden entladen und deren Speicher wird freigegeben.
 
ERICAPI_IMPORT int EricFormatEWAz (const byteChar *ewAzElster, EricRueckgabepufferHandle ewAzBescheidPuffer)
 Konvertiert ein Einheitswert-Aktenzeichen im ELSTER-Format in ein landesspezifisches Bescheidformat.
 
ERICAPI_IMPORT int EricFormatStNr (const byteChar *eingabeSteuernummer, EricRueckgabepufferHandle rueckgabePuffer)
 Die Steuernummer eingabeSteuernummer wird in das Bescheid-Format des jeweiligen Bundeslandes umgewandelt.
 
ERICAPI_IMPORT int EricGetAuswahlListen (const char *datenartVersion, const char *feldkennung, EricRueckgabepufferHandle rueckgabeXmlPuffer)
 Die Auswahlliste(n) für datenartVersion oder feldkennung wird zurückgeliefert.
 
ERICAPI_IMPORT int EricGetErrormessagesFromXMLAnswer (const char *xml, EricRueckgabepufferHandle transferticketPuffer, EricRueckgabepufferHandle returncodeTHPuffer, EricRueckgabepufferHandle fehlertextTHPuffer, EricRueckgabepufferHandle returncodesUndFehlertexteNDHXmlPuffer)
 Aus dem Antwort-XML des Finanzamtservers wird das Transferticket und Returncodes/Fehlermeldungen zurückgegeben.
 
ERICAPI_IMPORT int EricGetHandleToCertificate (EricZertifikatHandle *hToken, uint32_t *iInfoPinSupport, const byteChar *pathToKeystore)
 Für das übergebene Zertifikat in pathToKeystore wird das Handle hToken und die unterstützten PIN-Werte iInfoPinSupport zurückgeliefert.
 
ERICAPI_IMPORT int EricZertifikatOeffnenAusBytes (EricZertifikatHandle *hToken, const byteChar *pkcs12Container, uint32_t containerGroesse, const byteChar *pkcs12Passwort)
 Für das im Speicher übergebene Zertifikat wird das Handle hToken zurückgeliefert.
 
ERICAPI_IMPORT int EricGetPinStatus (EricZertifikatHandle hToken, uint32_t *pinStatus, uint32_t keyType)
 Der PIN-Status wird für ein passwortgeschütztes Kryptomittel abgefragt und in pinStatus zurückgegeben.
 
ERICAPI_IMPORT int EricGetPublicKey (const eric_verschluesselungs_parameter_t *cryptoParameter, EricRueckgabepufferHandle rueckgabePuffer)
 Es wird der öffentliche Schlüssel als base64-kodierte Zeichenkette für das übergebene Zertifikat-Handle in cryptoParameter zurückgeliefert. Von den beiden öffentlichen Schlüsseln, die in ELSTER-Zertifikaten enthalten sind, wird der Verschlüsselungsschlüssel (Encryption Key) zurückgegeben.
 
ERICAPI_IMPORT int EricHoleFehlerText (int fehlerkode, EricRueckgabepufferHandle rueckgabePuffer)
 Es wird die Klartextfehlermeldung zu dem fehlerkode ermittelt.
 
ERICAPI_IMPORT int EricHoleFinanzaemter (const byteChar *finanzamtLandNummer, EricRueckgabepufferHandle rueckgabeXmlPuffer)
 Es wird die Finanzamtliste für eine bestimmte finanzamtLandNummer zurückgegeben.
 
ERICAPI_IMPORT int EricHoleFinanzamtLandNummern (EricRueckgabepufferHandle rueckgabeXmlPuffer)
 Die Liste aller Finanzamtlandnummern wird zurückgegeben.
 
ERICAPI_IMPORT int EricHoleFinanzamtsdaten (const byteChar bufaNr[5], EricRueckgabepufferHandle rueckgabeXmlPuffer)
 Die finanzamtsdaten werden für eine Bundesfinanzamtsnummer zurückgegeben.
 
ERICAPI_IMPORT int EricHoleTestfinanzaemter (EricRueckgabepufferHandle rueckgabeXmlPuffer)
 Die Testfinanzamtliste wird in rueckgabeXmlPuffer zurückgegeben.
 
ERICAPI_IMPORT int EricHoleZertifikatEigenschaften (EricZertifikatHandle hToken, const byteChar *pin, EricRueckgabepufferHandle rueckgabeXmlPuffer)
 Die Eigenschaften des übergebenen Zertifikats werden im rueckgabeXmlPuffer zurückgegeben.
 
ERICAPI_IMPORT int EricHoleZertifikatFingerabdruck (const eric_verschluesselungs_parameter_t *cryptoParameter, EricRueckgabepufferHandle fingerabdruckPuffer, EricRueckgabepufferHandle signaturPuffer)
 Der Fingerabdruck und dessen Signatur wird für das übergebene Zertifikat zurückgegeben.
 
ERICAPI_IMPORT int EricInitialisiere (const byteChar *pluginPfad, const byteChar *logPfad)
 Initialisiert den Singlethreading-ERiC.
 
ERICAPI_IMPORT int EricMakeElsterStnr (const byteChar *steuernrBescheid, const byteChar landesnr[2+1], const byteChar bundesfinanzamtsnr[4+1], EricRueckgabepufferHandle steuernrPuffer)
 Es wird eine Steuernummer im ELSTER-Steuernummerformat erzeugt.
 
ERICAPI_IMPORT int EricMakeElsterEWAz (const byteChar *ewAzBescheid, const byteChar *landeskuerzel, EricRueckgabepufferHandle ewAzElsterPuffer)
 Konvertiert ein Einheitswert-Aktenzeichen in das ELSTER-Format.
 
ERICAPI_IMPORT int EricPruefeBIC (const byteChar *bic)
 Die bic wird auf Gültigkeit überprüft.
 
ERICAPI_IMPORT int EricPruefeIBAN (const byteChar *iban)
 Die iban wird auf Gültigkeit überprüft.
 
ERICAPI_IMPORT int EricPruefeEWAz (const byteChar *einheitswertAz)
 Überprüft ein Einheitswert-Aktenzeichen im ELSTER-Format auf Gültigkeit.
 
ERICAPI_IMPORT int EricPruefeIdentifikationsMerkmal (const byteChar *steuerId)
 Die steuerId wird auf Gültigkeit überprüft.
 
ERICAPI_IMPORT int EricPruefeSteuernummer (const byteChar *steuernummer)
 Die steuernummer wird einschließlich Bundesfinanzamtsnummer auf formale Richtigkeit geprüft.
 
ERICAPI_IMPORT int EricPruefeWIdNr (const byteChar *wIdNr)
 Die Wirtschafts-Identifikationsnummer (W-IdNr.) wird auf formale Gültigkeit überprüft.
 
ERICAPI_IMPORT int EricPruefeZertifikatPin (const byteChar *pathToKeystore, const byteChar *pin, uint32_t keyType)
 Prüft, ob die pin zum Zertifikat pathToKeystore passt. Nicht anwendbar auf Ad Hoc-Zertifikate (AHZ), die für einen neuen Personalausweis (nPA) ausgestellt sind.
 
ERICAPI_IMPORT int EricRegistriereFortschrittCallback (EricFortschrittCallback funktion, void *benutzerdaten)
 Die funktion wird als Callback-Funktion für EricBearbeiteVorgang() registriert.
 
ERICAPI_IMPORT int EricRegistriereGlobalenFortschrittCallback (EricFortschrittCallback funktion, void *benutzerdaten)
 Die registrierte funktion wird als Callback-Funktion von EricBearbeiteVorgang() aufgerufen und zeigt den Gesamtfortschritt der Verarbeitung an.
 
ERICAPI_IMPORT int EricRegistriereLogCallback (EricLogCallback funktion, uint32_t schreibeEricLogDatei, void *benutzerdaten)
 Die registrierte funktion wird als Callback-Funktion für jede Lognachricht aufgerufen. Die Ausgabe entspricht einer Zeile im eric.log.
 
ERICAPI_IMPORT EricRueckgabepufferHandle EricRueckgabepufferErzeugen (void)
 Diese API-Funktion erzeugt einen Rückgabepuffer und gibt ein Handle darauf zurück.
 
ERICAPI_IMPORT int EricRueckgabepufferFreigeben (EricRueckgabepufferHandle handle)
 Der durch das handle bezeichnete Rückgabepuffer wird freigegeben.
 
ERICAPI_IMPORT const char * EricRueckgabepufferInhalt (EricRueckgabepufferHandle handle)
 Der durch das handle bezeichnete Inhalt des Rückgabepuffers wird zurückgegeben.
 
ERICAPI_IMPORT uint32_t EricRueckgabepufferLaenge (EricRueckgabepufferHandle handle)
 Die Länge des Rückgabepufferinhalts wird zurückgegeben.
 
ERICAPI_IMPORT int EricSystemCheck (void)
 Es werden Plattform-, Betriebssystem- und ERiC-Informationen ausgegeben.
 
ERICAPI_IMPORT int EricVersion (EricRueckgabepufferHandle rueckgabeXmlPuffer)
 Es wird eine Liste sämtlicher Produkt- und Dateiversionen der verwendeten ERiC-Bibliotheken als XML-Daten zurückgegeben.
 

Ausführliche Beschreibung

Deklaration der ERiC API-Funktionen für die Singlethreading-API.

Definiert in Datei ericapi.h.

Dokumentation der Funktionen

◆ EricBearbeiteVorgang()

ERICAPI_IMPORT int EricBearbeiteVorgang ( const char * datenpuffer,
const char * datenartVersion,
uint32_t bearbeitungsFlags,
const eric_druck_parameter_t * druckParameter,
const eric_verschluesselungs_parameter_t * cryptoParameter,
EricTransferHandle * transferHandle,
EricRueckgabepufferHandle rueckgabeXmlPuffer,
EricRueckgabepufferHandle serverantwortXmlPuffer )

Diese API-Funktion ist die zentrale Schnittstellenfunktion zur Kommunikation mit dem ELSTER-Annahmeserver.

Als Austauschformat wird XML verwendet, siehe Kap. "Datenverarbeitung mit ERiC" im ERiC-Entwicklerhandbuch.pdf. Dort sind die Arbeitsabläufe von Einzel- und Sammellieferung beschrieben.

Die Funktion kann Steuerdaten plausibilisieren, an den ELSTER-Annahmeserver übertragen und ausdrucken, sowie Protokolle der Übertragung erzeugen. Die ProcessingFlags im Parameter bearbeitungsFlags definieren, welche der Schritte wie ausgeführt werden.

Je nach Anwendungsfall können die Daten authentifiziert übertragen werden und es kann ein PDF-Druck der Daten erfolgen. In diesen Fällen sind die Parameter cryptoParameter und druckParameter entsprechend zu befüllen. Die möglichen Parameterkombinationen und Druckkennzeichnungen können im ERiC-Entwicklerhandbuch.pdf nachgelesen werden.

Sind für einen Anwendungsfall mehrere voneinander abhängige Aufrufe von EricBearbeiteVorgang() nötig, so ist der Parameter transferHandle zu übergeben. Dies ist derzeit nur für die Datenabholung der Fall.

Es werden an bestimmten Punkten der Verarbeitung benutzerdefinierte Callback Funktionen aufgerufen. Siehe hierzu Fortschrittcallbacks.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Parameter
[in]datenpufferEnthält die zu verarbeitenden XML-Daten.
[in]datenartVersion

Die datenartVersion ist der Datenartversionmatrix.xml zu entnehmen.

Dieser Parameter darf nicht NULL sein und muss zu den XML-Eingangsdaten passen.

Siehe auch ERiC-Entwicklerhandbuch.pdf.

[in]bearbeitungsFlags

Oder-Verknüpfung von Bearbeitungsvorgaben. Anhand dieser Vorgaben werden die übergebenen Daten verarbeitet. Der Parameter darf nicht 0 sein, zu gültigen Werten siehe eric_bearbeitung_flag_t.

Bei welchen Anwendungsfällen welche Flags möglich oder notwendig sind, ist im ERiC-Entwicklerhandbuch.pdf nachzulesen.

[in]druckParameter

Parameter, der für den PDF-Druck benötigt wird, siehe eric_druck_parameter_t.

Bei welchen Anwendungsfällen der Druckparameter möglich oder notwendig ist, ist im ERiC-Entwicklerhandbuch.pdf nachzulesen.

Soll kein PDF-Druck erfolgen, so ist NULL zu übergeben.

[in]cryptoParameter

Enthält die für den authentifizierten Versand benötigten Informationen und darf nur dann übergeben werden, siehe eric_verschluesselungs_parameter_t.

Erfolgt kein authentifizierter Versand, so ist NULL zu übergeben.

[in,out]transferHandle

Bei der Datenabholung ist ein Zeiger auf ein vom Aufrufer verwaltetes und anfangs mit 0 befülltes EricTransferHandle zu übergeben, über das die zusammenhängenden Versandvorgänge einer Datenabholung gebündelt werden (Bündelung der Versandvorgänge "Anforderung", "Abholung" und optional "Quittierung").

Wenn bei der Datenabholung kein Versandflag gesetzt ist (nur Validierung), darf dem transferHandle auch ein Nullzeiger (NULL) übergeben werden.

Bei allen anderen Anwendungsfällen ist immer NULL zu übergeben.

[out]rueckgabeXmlPuffer

Handle auf einen Rückgabepuffer, in den beim Versand Telenummer und Ordnungsbegriff, Hinweise oder Fehler bei der Regelprüfung geschrieben werden.

Siehe Inhalt des Rückgabepuffers und des Serverantwortpuffers und EricRueckgabepufferHandle.

[out]serverantwortXmlPuffer

Handle auf einen Rückgabepuffer, in den beim Versand die Antwort des Empfangsservers geschrieben wird.

Siehe Inhalt des Rückgabepuffers und des Serverantwortpuffers und EricRueckgabepufferHandle.

Rückgabe

Inhalt des Rückgabepuffers und des Serverantwortpuffers

Der Inhalt der Pufferspeicher kann mit EricRueckgabepufferInhalt() abgefragt und ausgewertet werden. rueckgabeXmlPuffer gibt im Erfolgsfall oder bei Plausibilitätsfehler XML-Daten nach Schema Dokumentation\API-Rueckgabe-Schemata\EricBearbeiteVorgang.xsd zurück. serverantwortXmlPuffer gibt bei Sendevorgängen die Antwort des ELSTER- Annahmeservers zurück.

Nach dem Aufruf der Funktion müssen programmatisch folgende Fälle aufgrund des Rückgabewerts unterschieden werden.

Erfolgsfall

Sind alle Bearbeitungsschritte fehlerfrei durchlaufen worden, dann ist der Rückgabewert ERIC_OK und der Text im Pufferspeicher rueckgabeXmlPuffer enthält beim Versand XML-Daten mit generierter Telenummer und bei Neuaufnahmen den Ordnungsbegriff.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricBearbeiteVorgang xmlns="http://www.elster.de/EricXML/1.1/EricBearbeiteVorgang">
<Erfolg>
<Telenummer>N55</Telenummer>
</Erfolg>
</EricBearbeiteVorgang>

Beim Versand befindet sich zusätzlich im Pufferspeicher serverantwortXmlPuffer die Antwort des ELSTER-Annahmeservers. Bei einer Datenabholung kann diese ausgewertet werden. Details hierzu befinden sich im ERiC-Entwicklerhandbuch.pdf

Hinweise

Falls das Bearbeitungsflag ERIC_PRUEFE_HINWEISE angegeben worden ist, kann der Rückgabewert ERIC_GLOBAL_HINWEISE zurückgegeben werden. Der Rückgabepuffer enthält dann die gemeldeten Hinweise.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricBearbeiteVorgang xmlns="http://www.elster.de/EricXML/1.1/EricBearbeiteVorgang">
<Hinweis>
<Nutzdatenticket>1075</Nutzdatenticket>
<Feldidentifikator>100001</Feldidentifikator>
<Mehrfachzeilenindex>1</Mehrfachzeilenindex>
<LfdNrVordruck>1</LfdNrVordruck>
<VordruckZeilennummer>4</VordruckZeilennummer>
<SemantischerIndex>PersonA</SemantischerIndex>
<Untersachbereich>5</Untersachbereich>
<RegelName>testRegelName</RegelName>
<FachlicheHinweisId>9995</FachlicheHinweisId>
<Text>Weitere Angaben können erforderlich sein</Text>
</Hinweis>
</EricBearbeiteVorgang>

Die einzelnen Elemente sind in der Schemadefinition Dokumentation\API-Rueckgabe-Schemata\EricBearbeiteVorgang.xsd dokumentiert. Wenn die Bearbeitungsflags ERIC_PRUEFE_HINWEISE und ERIC_VALIDIERE übergeben worden sind, wurden bei der Plausibilisierung keine Fehler gefunden. Es sind keine Fehler im Rückgabepuffer enthalten.

Plausibilitätsfehler

Bei fehlgeschlagener Plausibilitätsprüfung ist der Rückgabewert ERIC_GLOBAL_PRUEF_FEHLER, und die Fehler werden im Rückgabepuffer als XML-Daten zurückgeliefert.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricBearbeiteVorgang xmlns="http://www.elster.de/EricXML/1.1/EricBearbeiteVorgang">
<FehlerRegelpruefung>
<Nutzdatenticket>1075</Nutzdatenticket>
<Feldidentifikator>100001</Feldidentifikator>
<Mehrfachzeilenindex>1</Mehrfachzeilenindex>
<LfdNrVordruck>1</LfdNrVordruck>
<VordruckZeilennummer>4</VordruckZeilennummer>
<SemantischerIndex>PersonA</SemantischerIndex>
<Untersachbereich>5</Untersachbereich>
<RegelName>testRegelName</RegelName>
<FachlicheFehlerId>9995</FachlicheFehlerId>
<Text>Beim Ankreuzfeld muss der Wert 'X' angegeben werden.</Text>
</FehlerRegelpruefung>
</EricBearbeiteVorgang>

Die einzelnen Elemente sind in der Schemadefinition Dokumentation\API-Rueckgabe-Schemata\EricBearbeiteVorgang.xsd dokumentiert. Wenn die Bearbeitungsflags ERIC_PRUEFE_HINWEISE und ERIC_VALIDIERE übergeben worden sind, kann der Rückgabepuffer auch Hinweise enthalten.

Fehler in der Serverantwort

Ist der Rückgabewert ERIC_TRANSFER_ERR_XML_THEADER oder ERIC_TRANSFER_ERR_XML_NHEADER so enthält der Serverantwortpuffer Fehlermeldungen. Zur Auswertung kann entweder die Serverantwort selbst ausgewertet werden oder es wird EricGetErrormessagesFromXMLAnswer() aufgerufen.

Sonstige Fehler

Bei sonstigen Fehlern ist der Inhalt der Rückgabepuffer undefiniert. Um nähere Informationen über die Fehlerursache herauszufinden, kann EricHoleFehlerText() mit dem Rückgabewert aufgerufen werden.

Fortschrittcallbacks

Während der Verarbeitung eines Anwendungsfalls werden die durch die Funktionen EricRegistriereFortschrittCallback() und EricRegistriereGlobalenFortschrittCallback() registrierten Callbacks aufgerufen.

Siehe auch

◆ EricBeende()

ERICAPI_IMPORT int EricBeende ( void )

Beendet den Singlethreading-ERiC.

Die Verarbeitung mit der ERiC Singlethread-API ist beendet, als letztes muss EricBeende() aufgerufen werden.

Rückgabe
Siehe auch

◆ EricChangePassword()

ERICAPI_IMPORT int EricChangePassword ( const byteChar * psePath,
const byteChar * oldPin,
const byteChar * newPin )

Die PIN für ein clientseitig erzeugtes Zertifikat (CEZ) wird geändert.

Die Funktion ändert die bei der Funktion EricCreateKey() angegebene PIN und entsprechend hierfür die Prüfsumme in der Datei eric.sfv. Falls die Datei eric.sfv nicht vorhanden ist, wird sie, wie bei EricCreateKey(), erstellt. Eine PIN-Änderung von einem Portalzertifikat (POZ) ist nicht möglich.

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]psePathIn dem angegebenen Pfad liegt das Schlüsselpaar eric_private.p12 und eric_public.cer
[in]oldPinBisherige PIN.
[in]newPinNeue PIN. Die Mindestlänge beträgt 4 Stellen. Zulässige Zeichen sind alle ASCII-Zeichen ohne die Steuerzeichen.
Rückgabe
Siehe auch

◆ EricCheckXML()

ERICAPI_IMPORT int EricCheckXML ( const char * xml,
const char * datenartVersion,
EricRueckgabepufferHandle fehlertextPuffer )

Das xml wird gegen das Schema der datenartVersion validiert.

Das verwendete Schema kann nachgeschlagen werden unter Dokumentation\Schnittstellenbeschreibungen\

Nicht unterstützte Datenartversionen:

  • ElsterKMV
  • alle Bilanz Datenartversionen
Parameter
[in]xmlXML-Zeichenfolge
[in]datenartVersion

Die datenartVersion ist der Datenartversionmatrix.xml zu entnehmen. Dieser Parameter darf nicht NULL sein und muss zu den XML-Eingangsdaten passen.

Siehe auch ERiC-Entwicklerhandbuch.pdf.

[out]fehlertextPuffer

Handle auf einen Rückgabepuffer, in den Fehlertexte geschrieben werden.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Rückgabe

◆ EricCloseHandleToCertificate()

ERICAPI_IMPORT int EricCloseHandleToCertificate ( EricZertifikatHandle hToken)

Das Zertifikat-Handle hToken wird freigegeben.

Diese Funktion gibt das übergebene Zertifikat-Handle frei. Zertifikat-Handles sollten möglichst frühzeitig, d.h. wenn sie nicht mehr benötigt werden, mit EricCloseHandleToCertificate() freigegeben werden, spätestens jedoch zum Programmende bzw. vor dem Entladen der ericapi Bibliothek.

Das Ad Hoc-Zertifikat eines neuen Personalausweises sollte immer genau dann freigegeben werden, wenn es nicht mehr benötigt wird, jedoch spätestens vor Ablauf der 24 Stunden, die das Ad Hoc-Zertifikat gültig ist.

Tritt ein Fehler auf, kann die Fehlermeldung mit EricHoleFehlerText() ausgelesen werden.

Parameter
[in]hTokenZertifikat-Handle wie von der Funktion EricGetHandleToCertificate() zurückgeliefert.
Rückgabe
Zu beachten
Die folgenden Rückgabewerte gelten nur bei Verwendung des neuen Personalausweises.
Rückgabe
Siehe auch

◆ EricCreateKey()

ERICAPI_IMPORT int EricCreateKey ( const byteChar * pin,
const byteChar * pfad,
const eric_zertifikat_parameter_t * zertifikatInfo )

Es werden die Kryptomittel für ein clientseitig erzeugtes Zertifikat (CEZ) in einem Verzeichnis des Dateisystems erstellt.

Im angegebenen Verzeichnis pfad sind nach Ausführung der Funktion EricCreateKey() drei Dateien erstellt worden:

  • eric_public.cer:
    Enthält das Zertifikat mit den Daten aus zertifikatInfo und darin den öffentlichen Schlüssel.
  • eric_private.p12:
    Enthält den privaten Schlüssel. Der Zugriff ist über die pin geschützt.
  • eric.sfv:
    Enthält die Prüfsumme der Dateien eric_public.cer und eric_private.p12. Die Integrität dieser beiden Dateien kann damit jederzeit überprüft werden.

Ein CEZ kann unter anderem für die Bescheiddaten-Rückübermittlung verwendet werden. Weitere Informationen zur Datenabholung lesen Sie bitte im ERiC-Entwicklerhandbuch.pdf nach.

Parameter
[in]pin

PIN (Passwort), mit der auf den privaten Schlüssel zugegriffen werden kann.

Die Mindestlänge beträgt 4 Stellen. Zulässige Zeichen sind alle ASCII-Zeichen ohne die Steuerzeichen.

[in]pfad

Pfad (1), in dem die Kryptomittel erzeugt werden sollen. Das durch den angegebenen Pfad bezeichnete Verzeichnis muss im Dateisystem bereits existieren und beschreibbar sein.

Es gibt folgende Möglichkeiten:

  • Absoluter Pfad: Empfehlung.
  • Relativer Pfad: Wird an das Arbeitsverzeichnis angehängt.
  • Leere Zeichenkette: In diesem Fall wird das Arbeitsverzeichnis verwendet.
[in]zertifikatInfoDaten, die zur Identifikation des Schlüsselinhabers im Zertifikat abgelegt werden.

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

Rückgabe
Siehe auch

◆ EricCreateTH()

ERICAPI_IMPORT int EricCreateTH ( const char * xml,
const char * verfahren,
const char * datenart,
const char * vorgang,
const char * testmerker,
const char * herstellerId,
const char * datenLieferant,
const char * versionClient,
const byteChar * publicKey,
EricRueckgabepufferHandle xmlRueckgabePuffer )

Diese Funktion erzeugt einen TransferHeader.

Dieser ist der oberste Header in der Datenstruktur. Er enthält Felder für die Kommunikation zwischen Server und Client. Es wird nur die Kombination NutzdatenHeader-Version "11" und TransferHeader-Version "11" unterstützt.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Parameter
[in]xml

XML-Datensatz, für den der <TransferHeader>-Block erzeugt werden soll.

Es kann entweder ein komplettes Elster-XML oder nur der Datenteil übergeben werden.

ERiC nimmt bei diesem Parameter keine Konvertierung von Sonderzeichen in Entitätenreferenzen vor.

Attribute, die in den Start-Tags der Elemente <Elster> bzw. <DatenTeil> im übergebenen XML-Datensatz definiert werden, werden nicht in das Rückgabe-XML übernommen.

Namespace-Definitionen, die in den Start-Tags der Elemente <Elster> bzw. <DatenTeil> im übergebenen XML-Datensatz definiert werden, führen zu einem ERIC_IO_PARSE_FEHLER.

Im Rückgabe-XML werden im Start-Tag des Elements <Elster> die URI "http://www.elster.de/elsterxml/schema/v11" als Default-Namensraum definiert.

Die dem Element <DatenTeil> untergeordneten Elemente aus dem übergebenen XML-Datensatz werden unverändert übernommen.

Der allgemeine Aufbau des Elster-XMLs wird im ERiC-Entwicklerhandbuch.pdf, Kap. "Datenverarbeitung mit ERiC" beschrieben.

[in]verfahrenName des Verfahrens, z.B: 'ElsterAnmeldung', siehe ERiC-Entwicklerhandbuch.pdf, Tabelle "Eigenschaften der Datenart" im jeweiligen Kapitel zur Datenart.
[in]datenartName der Datenart, z.B.:'LStB' oder 'UStVA', siehe ERiC-Entwicklerhandbuch.pdf, Tabelle "Eigenschaften der Datenart" im jeweiligen Kapitel zur Datenart.
[in]vorgangName der Übertragungsart, z.B. 'send-NoSig', siehe ERiC-Entwicklerhandbuch.pdf, Tabelle "Eigenschaften der Datenart" im jeweiligen Kapitel zur Datenart.
[in]testmerker

Für eine Testübertragung muss der entsprechende Testmerker angegeben werden, siehe ERiC-Entwicklerhandbuch.pdf, Kap. "Test Unterstützung bei der ERiC-Anbindung".

Falls ein Echtfall übertragen werden soll, muss der Wert NULL angegeben werden.

[in]herstellerIdHersteller-ID des Softwareproduktes.
[in]datenLieferant

Der Wert entspricht dem XML-Element <DatenLieferant>, wie es im Schema des Transferheaders der ElsterBasis-XML-Schnittstelle definiert ist.

ERiC konvertiert bei diesem Parameter Sonderzeichen in Entitätenreferenzen.

[in]versionClient

Angabe von Versionsinformation, die in der Serverantwort auch zurückgegeben wird und ausgewertet werden kann. Der Wert NULL entspricht "keine Angabe von Versionsinformation", d.h. es wird kein XML-Element <VersionClient> im <TransferHeader>-Block erzeugt.

ERiC konvertiert bei diesem Parameter Sonderzeichen in Entitätenreferenzen.

[in]publicKey

Öffentlicher Schlüssel für die Transportverschlüsselung beim Verfahren ElsterLohn. Bei anderen Verfahren sollte NULL übergeben werden.

Dieser Wert kann mit dem Rückgabewert von EricGetPublicKey() befüllt werden. Der Inhalt dieses Parameters wird in das <TransportSchluessel>-Element der Rückgabe-XML geschrieben.

[out]xmlRueckgabePuffer

Handle auf einen Rückgabepuffer, in den das Elster-XML mit dem erzeugten TransportHeader geschrieben wird, siehe EricRueckgabepufferHandle.

Es wird immer ein vollständiger Elster-XML-Datensatz mit dem <Elster>-Element als Wurzel-Element zurückgeliefert. Bzgl. der darin enthaltenen XML-Namespace-Definitionen sind die bei der Beschreibung des Parameters "xml" genannten Einschränkungen zu berücksichtigen.

Rückgabe
Siehe auch

◆ EricCreateUUID()

ERICAPI_IMPORT int EricCreateUUID ( EricRueckgabepufferHandle uuidRueckgabePuffer)

Erzeugt einen Version 4 Universally Unique Identifier (UUID) gemäß RFC 4122.

Parameter
[out]uuidRueckgabePufferHandle auf einen Rückgabepuffer, in den die erzeugte UUID geschrieben wird.
Rückgabe

◆ EricDekodiereDaten()

ERICAPI_IMPORT int EricDekodiereDaten ( EricZertifikatHandle zertifikatHandle,
const byteChar * pin,
const byteChar * base64Eingabe,
EricRueckgabepufferHandle rueckgabePuffer )

Es werden die mit der Datenabholung abgeholten und verschlüsselten Daten entschlüsselt.

Falls während der Bearbeitung ein Fehler auftritt, liefert die Funktion EricHoleFehlerText() den dazugehörigen Fehlertext.

Parameter
[in]zertifikatHandleHandle auf das zum Entschlüsseln zu verwendende Zertifikat.
[in]pinPIN zum Zugriff auf das Zertifikat.
[in]base64Eingabe

Base64-kodierte verschlüsselte Daten oder Anhänge, welche mit dem Verfahren ElsterDatenabholung abgeholt wurden.

Die Abholdaten befinden sich im Element
/Elster[1]/DatenTeil[1]/Nutzdatenblock/Nutzdaten[1]/Datenabholung[1]/Abholung[1]/Datenpaket

Die optionalen Anhänge befinden sich im Element
/Elster[1]/DatenTeil[1]/Nutzdatenblock/Nutzdaten[1]/Datenabholung[1]/Abholung[1]/Anhaenge[1]/Anhang[1]/Dateiinhalt

[out]rueckgabePuffer

Handle auf einen Rückgabepuffer, in den die entschlüsselten Daten geschrieben werden. Im Fehlerfall ist der Inhalt des Rückgabepuffers undefiniert.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe EricRueckgabepufferHandle.

Rückgabe
Siehe auch

◆ EricEinstellungAlleZuruecksetzen()

ERICAPI_IMPORT int EricEinstellungAlleZuruecksetzen ( void )

Alle Einstellungen werden auf den jeweiligen Standardwert zurückgesetzt.

Die Standardwerte sind im Dokument ERiC-Entwicklerhandbuch.pdf, Kap. "Vorbelegung der ERiC-Einstellungen" zu finden.

Rückgabe
Siehe auch

◆ EricEinstellungLesen()

ERICAPI_IMPORT int EricEinstellungLesen ( const char * name,
EricRueckgabepufferHandle rueckgabePuffer )

Der Wert der API-Einstellung name wird im rueckgabePuffer zurückgeliefert.

Parameter
[in]nameName der API-Einstellung, NULL-terminierte Zeichenfolge.
[out]rueckgabePuffer

Handle auf einen Rückgabepuffer, in den der Wert der API-Einstellung geschrieben wird.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe EricRueckgabepufferHandle.

Rückgabe
Siehe auch

◆ EricEinstellungSetzen()

ERICAPI_IMPORT int EricEinstellungSetzen ( const char * name,
const char * wert )

Die API-Einstellung name wird auf den wert gesetzt.

Nach dem Laden der ERiC-Bibliotheken hat jede API-Einstellung ihren Standardwert. Mit dieser Funktion kann der Wert verändert werden. Der Wertebereich der jeweiligen API-Einstellung ist zu beachten.

Bei Pfad-Einstellungen muss auf Windows der Wert 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]nameName der API-Einstellung, NULL-terminierte Zeichenfolge.
[in]wertWert der API-Einstellung, NULL-terminierte Zeichenfolge.
Rückgabe
Siehe auch

◆ EricEinstellungZuruecksetzen()

ERICAPI_IMPORT int EricEinstellungZuruecksetzen ( const char * name)

Der Wert der API-Einstellung name wird auf den Standardwert zurückgesetzt.

Die Standardwerte sind im Dokument ERiC-Entwicklerhandbuch.pdf, Kap. "Vorbelegung der ERiC-Einstellungen" zu finden.

Parameter
[in]nameName der API-Einstellung, NULL-terminierte Zeichenfolge.
Rückgabe
Siehe auch

◆ EricEntladePlugins()

ERICAPI_IMPORT int EricEntladePlugins ( void )

Alle verwendeten Plugin-Bibliotheken werden entladen und deren Speicher wird freigegeben.

Der ERiC lädt die für die Bearbeitung notwendigen Plugin-Bibliotheken permanent in den Speicher und gibt diese erst mit dem Aufruf dieser Funktion wieder frei.

Zu beachten
EricEntladePlugins() sollte erste dann aufgerufen werden, wenn die Plugin-Bibliotheken definitiv nicht mehr benötigt werden. Ein erneutes Laden der Bibliotheken ist verhältnismäßig zeitintensiv.

Falls eine Plugin-Bibliothek nicht entladen werden kann, wird dies in eric.log protokolliert. Der Returncode ist immer ERIC_OK.

Rückgabe
Siehe auch

◆ EricFormatEWAz()

ERICAPI_IMPORT int EricFormatEWAz ( const byteChar * ewAzElster,
EricRueckgabepufferHandle ewAzBescheidPuffer )

Konvertiert ein Einheitswert-Aktenzeichen im ELSTER-Format in ein landesspezifisches Bescheidformat.

Konvertiert ein Einheitswert-Aktenzeichen im ELSTER-Format (z.B. 2831400190001250002) in ein landesspezifisches Einheitswert-Aktenzeichen im Bescheidformat (z.B. 3100190001250002).

Parameter
[in]ewAzElsterZeiger auf ein Einheitswert-Aktenzeichen im ELSTER-Format (z.B. 2831400190001250002)
[out]ewAzBescheidPuffer

Handle auf einen Rückgabepuffer, in den das Einheitswert-Aktenzeichen im Bescheidformat (z.B. 3100190001250002) geschrieben wird.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Rückgabe

◆ EricFormatStNr()

ERICAPI_IMPORT int EricFormatStNr ( const byteChar * eingabeSteuernummer,
EricRueckgabepufferHandle rueckgabePuffer )

Die Steuernummer eingabeSteuernummer wird in das Bescheid-Format des jeweiligen Bundeslandes umgewandelt.

Parameter
[in]eingabeSteuernummerGültige, zu formatierende Steuernummer im ELSTER-Steuernummernformat.
[out]rueckgabePuffer

Handle auf einen Rückgabepuffer, in den die formatierte Steuernummer im Bescheid-Format des jeweiligen Bundeslandes geschrieben wird.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Rückgabe
Siehe auch

◆ EricGetAuswahlListen()

ERICAPI_IMPORT int EricGetAuswahlListen ( const char * datenartVersion,
const char * feldkennung,
EricRueckgabepufferHandle rueckgabeXmlPuffer )

Die Auswahlliste(n) für datenartVersion oder feldkennung wird zurückgeliefert.

Anwendungsfälle:

  1. Parameter feldkennung ist nicht NULL:
    Die Funktion liefert die zur feldkennung und datenartVersion gehörige Auswahlliste.
  2. Parameter feldkennung ist NULL:
    Die Funktion liefert alle zur datenartVersion gehörigen Feldkennungen mit hinterlegten Auswahllisten.

Für die Ermittlung der Auswahllisten vieler Feldkennungen wird aus Performanzgründen Anwendungsfall 2 empfohlen. Die Funktion liefert Auswahllisten zu Feldkennungen vom Format "NichtAbgeschlosseneEnumeration" zurück. Diese Auswahllisten werden auch in der Jahres-/Deltadokumentation dokumentiert.

Parameter
[in]datenartVersionDieser Parameter darf nicht NULL sein. Die gültigen Datenartversionen sind in der Datenartversionmatrix.xml enthalten.
[in]feldkennungFeldkennung, für welche die Auswahlliste zu ermitteln ist.
[out]rueckgabeXmlPuffer

Handle auf einen Rückgabepuffer, in den die angeforderten Auswahlliste(n) als XML-Daten geschrieben werden. Die XML-Daten folgen der XML Schema Definition in Dokumentation\API-Rueckgabe-Schemata\EricGetAuswahlListen.xsd.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe EricRueckgabepufferHandle.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricGetAuswahlListen xmlns="http://www.elster.de/EricXML/1.0/EricGetAuswahlListen">
<AuswahlListe>
<Feldkennung>0104110</Feldkennung>
<ListenElement>Arbeitslosengeld</ListenElement>
<ListenElement>Elterngeld</ListenElement>
<ListenElement>Insolvenzgeld</ListenElement>
<ListenElement>Krankengeld</ListenElement>
<ListenElement>Mutterschaftsgeld</ListenElement>
</AuswahlListe>
</EricGetAuswahlListen>
Rückgabe

◆ EricGetErrormessagesFromXMLAnswer()

ERICAPI_IMPORT int EricGetErrormessagesFromXMLAnswer ( const char * xml,
EricRueckgabepufferHandle transferticketPuffer,
EricRueckgabepufferHandle returncodeTHPuffer,
EricRueckgabepufferHandle fehlertextTHPuffer,
EricRueckgabepufferHandle returncodesUndFehlertexteNDHXmlPuffer )

Aus dem Antwort-XML des Finanzamtservers wird das Transferticket und Returncodes/Fehlermeldungen zurückgegeben.

Die Funktion liefert bei erfolgreicher Ausführung:

  • Das Transferticket aus dem Antwort-XML in dem Parameter transferticketPuffer.
  • Den Returncode und die Fehlermeldung aus dem Transferheader in den Parametern returncodeTHPuffer und fehlertextTHPuffer.
  • Für jeden Nutzdatenheader dessen Returncode und Fehlermeldung als XML-Daten im Parameter returncodesUndFehlertexteNDHXmlPuffer nach XML Schema Definition Dokumentation\API-Rueckgabe-Schemata\EricGetErrormessagesFromXMLAnswer.xsd. Enthält das Antwort-XML keine Nutzdaten, wird kein <Fehler> Element zurückgegeben.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Parameter
[in]xmlAntwort-XML des ELSTER-Servers, das ausgewertet werden soll. Der originale XML-Server-Datenstrom sollte unverändert übergeben werden und darf insbesondere keine Zeilenumbruchzeichen enthalten.
[out]transferticketPufferHandle auf einen Rückgabepuffer, in den das Transferticket geschrieben wird, siehe EricRueckgabepufferHandle.
[out]returncodeTHPufferHandle auf einen Rückgabepuffer, in den der Returncode aus dem Transferheader geschrieben wird. Siehe EricRueckgabepufferHandle.
[out]fehlertextTHPufferHandle auf einen Rückgabepuffer, in den die Fehlermeldung aus dem Transferheader geschrieben wird, siehe EricRueckgabepufferHandle.
[out]returncodesUndFehlertexteNDHXmlPufferHandle auf einen Rückgabepuffer, in den die Liste der Returncodes nach XML-Schema Dokumentation\API-Rueckgabe-Schemata\EricGetErrormessagesFromXMLAnswer.xsd geschrieben werden, siehe EricRueckgabepufferHandle.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricGetErrormessagesFromXMLAnswer xmlns="http://www.elster.de/EricXML/1.0/EricGetErrormessagesFromXMLAnswer">
<Fehler>
<Code>1</Code>
<Meldung>Fehlermeldung 1</Meldung>
</Fehler>
<Fehler>
<Code>2</Code>
<Meldung>Fehlermeldung 2</Meldung>
</Fehler>
(...)
</EricGetErrormessagesFromXMLAnswer>
Rückgabe
Zu beachten
Diese Funktion kann nicht dafür verwendet werden, die Antwort im Datenteil aus einer dekodierten Serverantwort für Lohnsteuerbescheinigungen auszuwerten.
Siehe auch

◆ EricGetHandleToCertificate()

ERICAPI_IMPORT int EricGetHandleToCertificate ( EricZertifikatHandle * hToken,
uint32_t * iInfoPinSupport,
const byteChar * pathToKeystore )

Für das übergebene Zertifikat in pathToKeystore wird das Handle hToken und die unterstützten PIN-Werte iInfoPinSupport zurückgeliefert.

Die ERiC API benötigt Zertifikat-Handles typischerweise bei kryptografischen Operationen.

Zertifikat-Handles sollten möglichst frühzeitig, d.h. wenn sie nicht mehr benötigt werden, mit EricCloseHandleToCertificate() freigegeben werden, spätestens jedoch zum Programmende bzw. vor dem Entladen der ericapi Bibliothek.

Parameter
[out]hTokenHandle zu einem der folgenden Zertifikate:
  • Portalzertifikat
  • clientseitig erzeugtes Zertifikat
  • Ad Hoc-Zertifikat für den neuen Personalausweis
[out]iInfoPinSupport

Wird in iInfoPinSupport ein Zeiger ungleich NULL übergeben und die Funktion mit ERIC_OK beendet, dann enthält iInfoPinSupport einen vorzeichenlosen Integer-Wert.

In diesem Wert ist kodiert abgelegt, ob eine PIN-Eingabe erforderlich ist und welche PIN-Statusinformationen unterstützt werden.

Die kodierten Werte (nachfolgend in hexadezimaler Form angegeben) können durch ein binäres ODER kombiniert werden und bedeuten im Einzelnen:

  • 0x00: Keine PIN-Angabe erforderlich, kein PIN-Status unterstützt.
  • 0x01: PIN-Angabe für Signatur erforderlich.
  • 0x02: PIN-Angabe für Entschlüsselung erforderlich.
  • 0x04: PIN-Angabe für Verschlüsselung des Zertifikats erforderlich.
  • 0x08: reserviert (wird derzeit nicht verwendet)
  • 0x10: PIN-Status "Pin Ok" wird unterstützt.
  • 0x20: PIN-Status "Der letzte Versuch der Pin-Eingabe schlug fehl" wird unterstützt.
  • 0x40: PIN-Status "Beim nächsten fehlerhaften Versuch wird die Pin gesperrt" wird unterstützt.
  • 0x80: PIN-Status "Pin ist gesperrt" wird unterstützt.

Falls vom Aufrufer NULL übergeben wird, gibt die Funktion nichts zurück.

[in]pathToKeystoreFolgende Zertifikatstypen werden unterstützt:
  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 Kryptomittel wurden mit 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 (1). 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 (1). Weitere Informationen in der Anleitung zur Signaturkarte.

  5. Neuer Personalausweis (nPA):
    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. "Test Unterstützung bei der ERiC-Anbindung".

    Wichtig: Das Ad Hoc-Zertifikat, das in diesem Fall für den neuen Personalausweis erzeugt wird, ist nur 24 Stunden gültig.

(1) Bei Sicherheitssticks und Signaturkarten ist bei der Angabe des Treibers der Suchmechanismus nach dynamischen Modulen des jeweiligen Betriebssystems zu berücksichtigen. Weitere Informationen sind z.B. unter Windows der Dokumentation der LoadLibrary() oder unter Linux und macOS der Dokumentation der dlopen() 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".

Rückgabe
Zu beachten
Die folgenden Rückgabewerte gelten nur bei Verwendung des neuen Personalausweises.
Rückgabe
Siehe auch

◆ EricGetPinStatus()

ERICAPI_IMPORT int EricGetPinStatus ( EricZertifikatHandle hToken,
uint32_t * pinStatus,
uint32_t keyType )

Der PIN-Status wird für ein passwortgeschütztes Kryptomittel abgefragt und in pinStatus zurückgegeben.

Der PIN-Status wird für einen passwortgeschützten Bereich ermittelt, der durch das übergebene Zertifikat-Handle im Parameter hToken referenziert wird. Da bei Sicherheitssticks und Signaturkarten durch ein einziges Zertifikat-Handle zwei Schlüsselpaare referenziert werden können (eines für die Signatur und eines für die Verschlüsselung von Daten), muss grundsätzlich der Parameter keyType gesetzt werden.

Mit dem Rückgabewert der Funktion kann der Endanwender rechtzeitig informiert werden, falls bei einer weiteren falschen PIN-Eingabe das Kryptomittel gesperrt wird. Im Fehlerfall ist pinStatus nicht definiert.

Der Karten- bzw. Stickhersteller ist verantwortlich, dass seine Implementierung den korrekten PIN-Status zurückgibt, siehe auch Tabelle "PIN-Statusabfrage für POZ" im Unterkap. "Das Portalzertifikat (POZ)" im Dokument ERiC-Entwicklerhandbuch.pdf.

Parameter
[in]hToken

Zertifikat-Handle, für dessen passwortgeschützten Bereich der PIN-Status ermittelt werden soll.

Wird von der Funktion EricGetHandleToCertificate() zurückgeliefert.

[out]pinStatusMögliche Rückgabewerte:
  • 0: StatusPinOk: Kein Fehlversuch oder keine Informationen verfügbar
  • 1: StatusPinLocked: PIN gesperrt
  • 2: StatusPreviousPinError: Die letzte PIN-Eingabe war fehlerhaft
  • 3: StatusLockedIfPinError: Beim nächsten fehlerhaften Versuch wird die PIN gesperrt
[in]keyTypeMögliche Eingabewerte:
  • 0: eSignatureKey: Schlüssel für die Signatur von Daten
  • 1: eEncryptionKey: Schlüssel für die Verschlüsselung von Daten
Rückgabe
Siehe auch

◆ EricGetPublicKey()

ERICAPI_IMPORT int EricGetPublicKey ( const eric_verschluesselungs_parameter_t * cryptoParameter,
EricRueckgabepufferHandle rueckgabePuffer )

Es wird der öffentliche Schlüssel als base64-kodierte Zeichenkette für das übergebene Zertifikat-Handle in cryptoParameter zurückgeliefert. Von den beiden öffentlichen Schlüsseln, die in ELSTER-Zertifikaten enthalten sind, wird der Verschlüsselungsschlüssel (Encryption Key) zurückgegeben.

Parameter
[in]cryptoParameterDie Struktur enthält das Zertifikat-Handle und die PIN. Falls der Zugriff auf den öffentlichen Schlüssel keine PIN erfordert, ist PIN=NULL anzugeben.
[out]rueckgabePuffer

Handle auf den Rückgabepuffer. Bei Erfolg enthält der Rückgabepuffer den öffentlichen Schlüssel als base64-kodierte Zeichenkette.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Rückgabe

◆ EricHoleFehlerText()

ERICAPI_IMPORT int EricHoleFehlerText ( int fehlerkode,
EricRueckgabepufferHandle rueckgabePuffer )

Es wird die Klartextfehlermeldung zu dem fehlerkode ermittelt.

Die Funktion liefert die Klartextfehlermeldung zu einem ERiC Fehlercode - definiert in eric_fehlercodes.h

Parameter
[in]fehlerkodeEingabe-Fehlercode, definiert in eric_fehlercodes.h.
[out]rueckgabePuffer

Handle auf einen Rückgabepuffer, in den die Klartextfehlermeldung geschrieben wird.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Die Klartextfehlermeldung ist gemäß UTF-8 kodiert.

Rückgabe

◆ EricHoleFinanzaemter()

ERICAPI_IMPORT int EricHoleFinanzaemter ( const byteChar * finanzamtLandNummer,
EricRueckgabepufferHandle rueckgabeXmlPuffer )

Es wird die Finanzamtliste für eine bestimmte finanzamtLandNummer zurückgegeben.

Parameter
[in]finanzamtLandNummer

Die Finanzamtlandnummer besteht aus den ersten zwei Stellen der Bundesfinanzamtsnummer.

Eine Liste aller Finanzamtlandnummern wird von EricHoleFinanzamtLandNummern() zurückgegeben.

[out]rueckgabeXmlPuffer

Handle auf einen Rückgabepuffer, in den die Ergebnis XML-Daten geschrieben werden. Die XML-Daten folgen der XML Schema Definition Dokumentation\API-Rueckgabe-Schemata\EricHoleFinanzaemter.xsd.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricHoleFinanzaemter xmlns="http://www.elster.de/EricXML/1.0/EricHoleFinanzaemter">
<Finanzamt>
<BuFaNummer>2801</BuFaNummer>
<Name>Finanzamt Offenburg Außenstelle Achern</Name>
</Finanzamt>
<Finanzamt>
<BuFaNummer>2804</BuFaNummer>
<Name>Finanzamt Villingen-Schwenningen Außenstelle Donaueschingen</Name>
</Finanzamt>
(...)
</EricHoleFinanzaemter>
Rückgabe

◆ EricHoleFinanzamtLandNummern()

ERICAPI_IMPORT int EricHoleFinanzamtLandNummern ( EricRueckgabepufferHandle rueckgabeXmlPuffer)

Die Liste aller Finanzamtlandnummern wird zurückgegeben.

Parameter
[out]rueckgabeXmlPuffer

Handle auf einen Rückgabepuffer, in den die Ergebnis XML-Daten geschrieben werden. Die XML-Daten folgen der XML Schema Definition Dokumentation\API-Rueckgabe-Schemata\EricHoleFinanzamtLandNummern.xsd.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricHoleFinanzamtLandNummern xmlns="http://www.elster.de/EricXML/1.0/EricHoleFinanzamtLandNummern">
<FinanzamtLand>
<FinanzamtLandNummer>28</FinanzamtLandNummer>
<Name>Baden-Württemberg</Name>
</FinanzamtLand>
<FinanzamtLand>
<FinanzamtLandNummer>91</FinanzamtLandNummer>
<Name>Bayern (Zuständigkeit LfSt - München)</Name>
</FinanzamtLand>
(...)
</EricHoleFinanzamtLandNummern>
Rückgabe

◆ EricHoleFinanzamtsdaten()

ERICAPI_IMPORT int EricHoleFinanzamtsdaten ( const byteChar bufaNr[5],
EricRueckgabepufferHandle rueckgabeXmlPuffer )

Die finanzamtsdaten werden für eine Bundesfinanzamtsnummer zurückgegeben.

Die Bundesfinanzamtsnummer kann über die Kombination der Funktionen EricHoleFinanzamtLandNummern() und EricHoleFinanzaemter() ermittelt werden.

Parameter
[in]bufaNrÜbergabe der 4-stelligen Bundesfinanzamtsnummer.
[out]rueckgabeXmlPuffer

Handle auf einen Rückgabepuffer, in den die Ergebnis XML-Daten geschrieben werden. Die XML-Daten folgen der XML Schema Definition Dokumentation\API-Rueckgabe-Schemata\EricHoleFinanzamtsdaten.xsd.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Rückgabe
Siehe auch

◆ EricHoleTestfinanzaemter()

ERICAPI_IMPORT int EricHoleTestfinanzaemter ( EricRueckgabepufferHandle rueckgabeXmlPuffer)

Die Testfinanzamtliste wird in rueckgabeXmlPuffer zurückgegeben.

Parameter
[out]rueckgabeXmlPuffer

Handle auf einen Rückgabepuffer, in den die Ergebnis XML-Daten geschrieben werden. Die XML-Daten folgen der XML Schema Definition Dokumentation\API-Rueckgabe-Schemata\EricHoleTestFinanzaemter.xsd.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricHoleTestFinanzaemter xmlns="http://www.elster.de/EricXML/1.0/EricHoleTestFinanzaemter">
<Finanzamt>
<BuFaNummer>1096</BuFaNummer>
<Name>Testfinanzamt Saarland</Name>
</Finanzamt>
<Finanzamt>
<BuFaNummer>1097</BuFaNummer>
<Name>Finanzschule (Edenkoben)</Name>
</Finanzamt>
(...)
</EricHoleTestFinanzaemter>
Rückgabe

◆ EricHoleZertifikatEigenschaften()

ERICAPI_IMPORT int EricHoleZertifikatEigenschaften ( EricZertifikatHandle hToken,
const byteChar * pin,
EricRueckgabepufferHandle rueckgabeXmlPuffer )

Die Eigenschaften des übergebenen Zertifikats werden im rueckgabeXmlPuffer zurückgegeben.

Parameter
[in]hTokenHandle des Zertifikats, dessen Eigenschaften geholt werden sollen. Wird von der Funktion EricGetHandleToCertificate() zurückgeliefert.
[in]pinPIN zum Öffnen des Zertifikats. Wird bei Software-Portalzertifikaten benötigt.
[out]rueckgabeXmlPuffer

Handle auf einen Rückgabepuffer, in den die Zertifikateigenschaften im XML-Format geschrieben werden. Das Format ist im XML Schema Dokumentation\API-Rueckgabe-Schemata\EricHoleZertifikatEigenschaften.xsd definiert.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Zu beachten
Bei einem ELSTER-Softwarezertifikat (.pfx) steht im Common Name (CN) die ID des ELSTER-Kontos, für das das Zertifikat ausgestellt wurde. Die Konto-ID kann beispielsweise dafür genutzt werden, bei einer Zertifikatsverlängerung das verlängerte Zertifikat dem alten Zertifikat zuzuordnen.

Beispiel:

<EricHoleZertifikatEigenschaften xmlns="http://www.elster.de/EricXML/2.0/EricHoleZertifikatEigenschaften">
<Signaturzertifikateigenschaften>
<AusgestelltAm>220817152116Z</AusgestelltAm>
<GueltigBis>230817152116Z</GueltigBis>
<Signaturalgorithmus>sha1WithRSAEncryption(1.2.840.113549.1.1.5)</Signaturalgorithmus>
<PublicKeyMD5>6b8b191936677957fe74103198e77f4e</PublicKeyMD5>
<PublicKeySHA1>884b0dfe2e10221a2aedd28c986cf34db0f1d932</PublicKeySHA1>
<PublicKeyBitLength>2048</PublicKeyBitLength>
<Issuer>
<Info><Name>CN</Name><Wert>ElsterSoftCA</Wert></Info>
<Info><Name>OU</Name><Wert>CA</Wert></Info>
(...)
</Issuer>
<Subjekt>
<Info><Name>CN</Name><Wert>1000872896</Wert></Info>
</Subjekt>
<Identifikationsmerkmaltyp>Steuernummer</Identifikationsmerkmaltyp>
<Registrierertyp>Person</Registrierertyp>
<Verifikationsart>Postweg</Verifikationsart>
<TokenTyp>Software</TokenTyp>
<Testzertifikat>true</Testzertifikat>
</Signaturzertifikateigenschaften>
<Verschluesselungszertifikateigenschaften>
(...)
</Verschluesselungszertifikateigenschaften>
</EricHoleZertifikatEigenschaften>
Rückgabe
Siehe auch

◆ EricHoleZertifikatFingerabdruck()

ERICAPI_IMPORT int EricHoleZertifikatFingerabdruck ( const eric_verschluesselungs_parameter_t * cryptoParameter,
EricRueckgabepufferHandle fingerabdruckPuffer,
EricRueckgabepufferHandle signaturPuffer )

Der Fingerabdruck und dessen Signatur wird für das übergebene Zertifikat zurückgegeben.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Parameter
[in]cryptoParameterZertifikatsdaten, siehe eric_verschluesselungs_parameter_t. Das in der übergebenen Struktur referenzierte Zertifikat muss ein clientseitig erzeugtes Zertifikat (CEZ) sein.
[out]fingerabdruckPufferHandle auf einen Rückgabepuffer, in den der Fingerabdruck geschrieben wird, siehe EricRueckgabepufferHandle.
[out]signaturPufferHandle auf einen Rückgabepuffer, in den die Signatur des Fingerabdrucks geschrieben wird, siehe EricRueckgabepufferHandle.
Zu beachten
Die Erzeugung eines Fingerabdrucks mit dieser Funktion ist nur in Zusammenhang mit clientseitig erzeugten Zertifikaten definiert.
Rückgabe

◆ EricInitialisiere()

ERICAPI_IMPORT int EricInitialisiere ( const byteChar * pluginPfad,
const byteChar * logPfad )

Initialisiert den Singlethreading-ERiC.

Vor der Verwendung der Singlethreading-API muss EricInitialisiere() aufgerufen werden.

Mehrfache Aufrufe dieser Funktion, ohne das zwischendurch EricBeende() aufgerufen worden ist, führen dazu, dass der Fehlercode ERIC_GLOBAL_MEHRFACHE_INITIALISIERUNG zurückgegeben wird. Der zuvor initialisierte Singlethreading-ERiC bleibt davon aber unberührt und ist weiterhin in einem gültigen Zustand.

Parameter
[in]pluginPfadPfad, in dem die Plugins rekursiv gesucht werden. Ist der Zeiger gleich NULL, wird der Pfad zur Bibliothek ericapi verwendet.
[in]logPfadOptionaler Pfad zur Log-Datei eric.log. Ist der Wert gleich NULL, wird das betriebssystemspezifische Verzeichnis für temporäre Dateien verwendet.
Zu beachten

Kann kein eric.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 ERiC-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

◆ EricMakeElsterEWAz()

ERICAPI_IMPORT int EricMakeElsterEWAz ( const byteChar * ewAzBescheid,
const byteChar * landeskuerzel,
EricRueckgabepufferHandle ewAzElsterPuffer )

Konvertiert ein Einheitswert-Aktenzeichen in das ELSTER-Format.

Konvertiert ein gültiges Einheitswert-Aktenzeichen in einem landesspezifischen Bescheidformat (z.B. 208/035-3-03889.3) unter Angabe des Landeskürzels in ein Einheitswert-Aktenzeichen im ELSTER-Format (z.B. 520840353038893).

Parameter
[in]ewAzBescheidZeiger auf das Einheitswert-Aktenzeichen in einem landesspezifischen Bescheidformat.
[in]landeskuerzelZeiger auf das Landeskürzel (zum Beispiel BY für Bayern)
[out]ewAzElsterPufferHandle auf einen Rückgabepuffer, in den das erzeugte Einheitswert-Aktenzeichen im ELSTER-Format geschrieben wird.
Rückgabe
Siehe auch
  • Landeskürzel siehe ISO-3166-2

◆ EricMakeElsterStnr()

ERICAPI_IMPORT int EricMakeElsterStnr ( const byteChar * steuernrBescheid,
const byteChar landesnr[2+1],
const byteChar bundesfinanzamtsnr[4+1],
EricRueckgabepufferHandle steuernrPuffer )

Es wird eine Steuernummer im ELSTER-Steuernummerformat erzeugt.

Die Funktion erzeugt aus einer angegebenen Steuernummer im Format des Steuerbescheides eine 13-stellige Steuernummer im ELSTER-Steuernummerformat.

Die sich ergebende 13-stellige Steuernummer im ELSTER-Steuernummerformat wird von der Funktion EricMakeElsterStnr() auch auf Gültigkeit geprüft.

Einer der beiden Parameter landesnr oder bundesfinanzamtsnr muss korrekt angegeben werden. Der jeweils andere Parameter darf NULL oder leer sein. Bei bayerischen und berliner Steuernummern im Format BBB/UUUUP ist die Angabe der Bundesfinanzamtsnummer zwingend erforderlich.

Parameter
[in]steuernrBescheidFormat der Steuernummer wie auch auf amtlichen Schreiben angegeben.
[in]landesnr2-stellige Landesnummer (entspricht den ersten zwei Stellen der Bundesfinanzamtsnummer).
[in]bundesfinanzamtsnr4-stellige Bundesfinanzamtsnummer.
[out]steuernrPuffer

Handle auf einen Rückgabepuffer, in den die Steuernummer im ELSTER-Steuernummerformat geschrieben wird.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Rückgabe

◆ EricPruefeBIC()

ERICAPI_IMPORT int EricPruefeBIC ( const byteChar * bic)

Die bic wird auf Gültigkeit überprüft.

Die Prüfung erfolgt in zwei Schritten:

  1. Formale Prüfung auf gültige Zeichen und richtige Länge.
  2. Prüfung, ob das Länderkennzeichen für BIC gültig ist.

Falls die BIC ungültig ist liefert die Funktion EricHoleFehlerText() den zugehörigen Fehlertext.

Parameter
[in]bicZeiger auf eine NULL-terminierte Zeichenkette.
Rückgabe
Siehe auch

◆ EricPruefeBuFaNummer()

ERICAPI_IMPORT int EricPruefeBuFaNummer ( const byteChar * steuernummer)

Die Bundesfinanzamtsnummer wird überprüft.

Wird eine 13-stellige Steuernummer im ELSTER-Steuernummernformat angegeben, so wird nur die Bundesfinanzamtsnummer (= die ersten 4 Stellen der 13-stelligen Steuernummer) geprüft.

Eine Prüfung der Steuernummer selbst findet nicht statt (hierfür EricPruefeSteuernummer() verwenden).

Parameter
[in]steuernummer13-stellige Steuernummer im ELSTER Steuernummernformat bzw. 4-stellige Bundesfinanzamtsnummer.
Rückgabe
Siehe auch

◆ EricPruefeEWAz()

ERICAPI_IMPORT int EricPruefeEWAz ( const byteChar * einheitswertAz)

Überprüft ein Einheitswert-Aktenzeichen im ELSTER-Format auf Gültigkeit.

Parameter
[in]einheitswertAzZeiger auf ein Einheitswert-Aktenzeichen im ELSTER-Format
Rückgabe

◆ EricPruefeIBAN()

ERICAPI_IMPORT int EricPruefeIBAN ( const byteChar * iban)

Die iban wird auf Gültigkeit überprüft.

Die Prüfung erfolgt in vier Schritten:

  1. Formale Prüfung auf gültige Zeichen und richtige Länge.
  2. Prüfung, ob das Länderkennzeichen für IBAN gültig ist.
  3. Prüfung, ob das länderspezifische Format gültig ist.
  4. Prüfung, ob die Prüfziffer der IBAN gültig ist.

Falls die IBAN ungültig ist, liefert die Funktion EricHoleFehlerText() den zugehörigen Fehlertext.

Parameter
[in]ibanZeiger auf eine NULL-terminierte Zeichenkette.
Rückgabe
Siehe auch

◆ EricPruefeIdentifikationsMerkmal()

ERICAPI_IMPORT int EricPruefeIdentifikationsMerkmal ( const byteChar * steuerId)

Die steuerId wird auf Gültigkeit überprüft.

Parameter
[in]steuerIdSteuer-Identifikationsnummer (IdNr)
Rückgabe
Siehe auch

◆ EricPruefeSteuernummer()

ERICAPI_IMPORT int EricPruefeSteuernummer ( const byteChar * steuernummer)

Die steuernummer wird einschließlich Bundesfinanzamtsnummer auf formale Richtigkeit geprüft.

Zur Prüfung der Bundesfinanzamtsnummer wird EricPruefeBuFaNummer() verwendet.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Parameter
[in]steuernummerNULL-terminierte 13-stellige Steuernummer im ELSTER-Steuernummernformat.
Rückgabe
Siehe auch

◆ EricPruefeWIdNr()

ERICAPI_IMPORT int EricPruefeWIdNr ( const byteChar * wIdNr)

Die Wirtschafts-Identifikationsnummer (W-IdNr.) wird auf formale Gültigkeit überprüft.

Parameter
[in]wIdNrNULL-terminierte Wirtschafts-Identifikationsnummer mit oder ohne Unterscheidungsmerkmal.
Rückgabe
Siehe auch

◆ EricPruefeZertifikatPin()

ERICAPI_IMPORT int EricPruefeZertifikatPin ( const byteChar * pathToKeystore,
const byteChar * pin,
uint32_t keyType )

Prüft, ob die pin zum Zertifikat pathToKeystore passt. Nicht anwendbar auf Ad Hoc-Zertifikate (AHZ), die für einen neuen Personalausweis (nPA) ausgestellt sind.

Parameter
[in]pathToKeystoreFolgende Zertifikatstypen werden unterstützt:
  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 Kryptomittel wurden mit 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 (2). 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 (2). Weitere Informationen in der Anleitung zur Signaturkarte.
[in]pinPIN für den Zugriff auf den privaten Schlüssel des Zertifikats.
[in]keyTypeMögliche Eingabewerte:
  • 0: eSignatureKey: Schlüssel für die Signatur von Daten, siehe (1).
  • 1: eEncryptionKey: Schlüssel für die Verschlüsselung von Daten, siehe (1).

(1) Bei einem Zertifikat wie dem mit EricCreateKey() clientseitig erzeugten Zertifikat (CEZ), das nur einen einzigen, gemeinsamen Schlüssel für Signatur und Verschlüsselung besitzt, sind beide Eingabewerte erlaubt. Die Werte beziehen sich dann beide auf denselben Schlüssel.

(2) Bei Sicherheitssticks und Signaturkarten ist bei der Angabe des Treibers der Suchmechanismus nach dynamischen Modulen des jeweiligen Betriebssystems zu berücksichtigen. Weitere Informationen sind z.B. unter Windows der Dokumentation der LoadLibrary() oder unter Linux und macOS der Dokumentation der dlopen() 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".

Es wird empfohlen, geöffnete Zertifikatshandle zu schließen, bevor mit der API-Funktion EricPruefeZertifikatPin() das gewünschte Zertifikat geprüft wird.

Zu beachten
Eine falsche PIN-Eingabe erhöht bei Sicherheitsstick und Signaturkarte den Zähler für Fehlversuche. Welche Zertifikatstypen aufgrund von 3 Fehlversuchen gesperrt werden, ist im ERiC-Entwicklerhandbuch.pdf, Kap. "Das Portalzertifikat (POZ)" beschrieben.
Rückgabe

◆ EricRegistriereFortschrittCallback()

ERICAPI_IMPORT int EricRegistriereFortschrittCallback ( EricFortschrittCallback funktion,
void * benutzerdaten )

Die funktion wird als Callback-Funktion für EricBearbeiteVorgang() registriert.

Die registrierte Callback-Funktion wird von der Funktion EricBearbeiteVorgang() aufgerufen, um bei der Verarbeitung den Fortschritt der einzelnen Arbeitsbereiche anzuzeigen.

Parameter
[in]funktionZeiger auf die zu registrierende Funktion oder NULL
[in]benutzerdatenZeiger, der der registrierten Funktion immer mitgegeben wird. Die Anwendung kann diesen Parameter dazu verwenden, einen Zeiger auf eigene Daten oder Funktionen an die zu registrierende Funktion übergeben zu lassen.
Rückgabe
Bemerkungen
  • Wenn eine zuvor registrierte Funktion nicht mehr aufgerufen werden soll, ist EricRegistriereFortschrittCallback() mit dem Wert NULL im Parameter funktion aufzurufen.
  • Es ist nicht erlaubt eine ERiC API-Funktion aus einer Callback-Funktion aufzurufen.
  • Die Verarbeitung im Callback findet synchron statt. Deshalb sollte der Callback sehr schnell ausgeführt werden.
Siehe auch

◆ EricRegistriereGlobalenFortschrittCallback()

ERICAPI_IMPORT int EricRegistriereGlobalenFortschrittCallback ( EricFortschrittCallback funktion,
void * benutzerdaten )

Die registrierte funktion wird als Callback-Funktion von EricBearbeiteVorgang() aufgerufen und zeigt den Gesamtfortschritt der Verarbeitung an.

Parameter
[in]funktionZeiger auf die zu registrierende Funktion oder NULL
[in]benutzerdatenZeiger, der der registrierten Funktion immer mitgegeben wird. Die Anwendung kann diesen Parameter dazu verwenden, einen Zeiger auf eigene Daten oder Funktionen an die zu registrierende Funktion übergeben zu lassen.
Rückgabe
Bemerkungen
  • Wenn eine zuvor registrierte Funktion nicht mehr aufgerufen werden soll, ist EricRegistriereGlobalenFortschrittCallback() mit dem Wert NULL im Parameter funktion aufzurufen.
  • Es ist nicht erlaubt eine ERiC API-Funktion aus einer Callback-Funktion aufzurufen.
  • Die Verarbeitung im Callback findet synchron statt. Deshalb sollte der Callback sehr schnell ausgeführt werden.
Siehe auch

◆ EricRegistriereLogCallback()

ERICAPI_IMPORT int EricRegistriereLogCallback ( EricLogCallback funktion,
uint32_t schreibeEricLogDatei,
void * benutzerdaten )

Die registrierte funktion wird als Callback-Funktion für jede Lognachricht aufgerufen. Die Ausgabe entspricht einer Zeile im eric.log.

Parameter
[in]funktionZeiger auf die zu registrierende Funktion oder NULL.
[in]schreibeEricLogDateiLog-Nachrichten im eric.log:
  • 1 Jede Log-Nachricht wird nach eric.log geschrieben. Der Parameter funktion kann auf eine Funktion zeigen oder NULL sein.
  • 0 Falls funktion != NULL werden keine Log-Nachrichten nach eric.log geschrieben, andernfalls werden die Log-Nachrichten nach eric.log geschrieben.
[in]benutzerdaten

Zeiger, welcher der registrierten Funktion immer mitgegeben wird.

Die Anwendung kann diesen Parameter dazu verwenden, einen Zeiger auf eigene Daten oder Funktionen an die zu registrierende Funktion übergeben zu lassen.

Rückgabe
Bemerkungen
  • Wenn eine zuvor registrierte Funktion nicht mehr aufgerufen werden soll, ist EricRegistriereLogCallback() mit dem Wert NULL im Parameter funktion aufzurufen (=Deregistrierung).
  • Vor dem Beenden der Steueranwendung ist eine registrierte Funktion zu deregistrieren, da es sonst zu einem Absturz kommen kann.
  • Es ist nicht erlaubt eine ERiC API-Funktion aus einer Callback-Funktion aufzurufen.
  • Die Verarbeitung im Callback findet synchron statt. Deshalb sollte der Callback sehr schnell ausgeführt werden.

◆ EricRueckgabepufferErzeugen()

ERICAPI_IMPORT EricRueckgabepufferHandle EricRueckgabepufferErzeugen ( void )

Diese API-Funktion erzeugt einen Rückgabepuffer und gibt ein Handle darauf zurück.

Die von dieser Funktion erzeugten Rückgabepuffer werden verwendet, um die Ausgaben von ERiC-Funktionen (z.B. EricBearbeiteVorgang()) 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 EricRueckgabepufferInhalt() übergeben. Ein einmal erzeugtes Rückgabepuffer-Handle kann für weitere nachfolgende Aufrufe von ERiC API-Funktionen wiederverwendet werden. Bei einer Wiederverwendung eines Handles werden frühere Inhalte überschrieben. Nach Verwendung muss jeder Rückgabepuffer mit EricRueckgabepufferFreigeben() freigegeben werden.

Rückgabepuffer sind der Singlethreading-API bzw. einer ERiC-Instanz der Multithreading-API fest zugeordnet. Die Funktionen der ERiC API, die einen Rückgabepuffer entgegennehmen, geben den Fehlercode ERIC_GLOBAL_PUFFER_UNGLEICHER_INSTANZ zurück, wenn der übergebene Rückgabepuffer:

  • mit der Singlethreading-API erzeugt worden ist und dann mit der Multithreading-API verwendet wird.
  • mit der Multithreading-API erzeugt worden ist und dann mit der Singlethreading-API verwendet wird.
  • mit einer ERiC-Instanz erzeugt worden ist und dann mit einer anderen Instanz verwendet wird.
Rückgabe
Siehe auch

◆ EricRueckgabepufferFreigeben()

ERICAPI_IMPORT int EricRueckgabepufferFreigeben ( EricRueckgabepufferHandle handle)

Der durch das handle bezeichnete Rückgabepuffer wird freigegeben.

Das Handle darf danach nicht weiter verwendet werden. Es wird daher empfohlen, Handle-Variablen nach der Freigabe explizit auf NULL zu setzen.

Parameter
[in]handleHandle auf einen mit EricRueckgabepufferErzeugen(). angelegten Rückgabepuffer. Dieser Rückgabepuffer darf nicht bereits freigegeben worden sein.
Rückgabe
Siehe auch

◆ EricRueckgabepufferInhalt()

ERICAPI_IMPORT const char * EricRueckgabepufferInhalt ( EricRueckgabepufferHandle handle)

Der durch das handle bezeichnete Inhalt des Rückgabepuffers wird zurückgegeben.

Der zurückgegebene Zeiger verweist auf ein Byte-Array, das alle in den Rückgabepuffer geschriebenen Bytes sowie eine abschließende NULL-Terminierung 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.

Parameter
[in]handleHandle auf einen mit EricRueckgabepufferErzeugen(). angelegten Rückgabepuffer. Dieser Rückgabepuffer darf nicht bereits freigegeben worden sein.
Rückgabe
  • Zeiger auf den NULL-terminierten Rückgabepufferinhalt, wenn ein gültiges Handle übergeben wird.
  • NULL: Bei Übergabe des ungültigen Handles NULL.
Siehe auch

◆ EricRueckgabepufferLaenge()

ERICAPI_IMPORT uint32_t EricRueckgabepufferLaenge ( EricRueckgabepufferHandle handle)

Die Länge des Rückgabepufferinhalts wird zurückgegeben.

Die zurückgegebene Zahl entspricht der Anzahl von Bytes, die von einer zuvor aufgerufenen ERiC API-Funktion in den Rückgabepuffer geschrieben wurden. Die NULL-Terminierung, die bei Aufruf von EricRueckgabepufferInhalt() an das zurückgegebene Byte-Array angefügt wird, wird bei dieser Längenangabe nicht berücksichtigt.

Parameter
[in]handleHandle auf einen mit EricRueckgabepufferErzeugen() angelegten Rückgabepuffer. Dieser Rückgabepuffer darf nicht bereits freigegeben worden sein.
Rückgabe
  • Anzahl der in den Rückgabepuffer geschriebenen Bytes, wenn ein gültiges Handle übergeben wird.
  • 0: Bei Übergabe des ungültigen Handles NULL.
Siehe auch

◆ EricSystemCheck()

ERICAPI_IMPORT int EricSystemCheck ( void )

Es werden Plattform-, Betriebssystem- und ERiC-Informationen ausgegeben.

Diese Funktion liefert Informationen über die verwendeten ERiC-Bibliotheken, ERiC-Druckvorlagen, die eingesetzte Plattform, den Arbeitsspeicher und das verwendete Betriebssystem.

Rückgabe
Siehe auch

◆ EricVersion()

ERICAPI_IMPORT int EricVersion ( EricRueckgabepufferHandle rueckgabeXmlPuffer)

Es wird eine Liste sämtlicher Produkt- und Dateiversionen der verwendeten ERiC-Bibliotheken als XML-Daten zurückgegeben.

Diese Funktion kann bei auftretenden Fehlern die Fehlersuche beschleunigen und Supportfälle unterstützen.

Parameter
[out]rueckgabeXmlPuffer

Handle auf einen Rückgabepuffer, in den zu allen ERiC-Bibliotheken die Produkt- und Dateiversionen als XML-Daten nach XML Schema Definition Dokumentation\API-Rueckgabe-Schemata\EricVersion.xsd geschrieben werden.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricVersion xmlns="http://www.elster.de/EricXML/1.0/EricVersion">
<Bibliothek>
<Name>ericapi.dll</Name>
<Produktversion>99, 1, 2, 32767</Produktversion>
<Dateiversion>2008, 3, 5, 0</Dateiversion>
</Bibliothek>
<Bibliothek>
<Name>ericctrl.dll</Name>
<Produktversion>99, 1, 2, 32767</Produktversion>
<Dateiversion>2008, 3, 5, 0</Dateiversion>
</Bibliothek>
(...)
</EricVersion>
Rückgabe
Siehe auch

◆ EricZertifikatOeffnenAusBytes()

ERICAPI_IMPORT int EricZertifikatOeffnenAusBytes ( EricZertifikatHandle * hToken,
const byteChar * pkcs12Container,
uint32_t containerGroesse,
const byteChar * pkcs12Passwort )

Für das im Speicher übergebene Zertifikat wird das Handle hToken zurückgeliefert.

Die ERiC API benötigt Zertifikat-Handles typischerweise bei kryptografischen Operationen.

Zertifikat-Handles sollten möglichst frühzeitig, d.h. wenn sie nicht mehr benötigt werden, mit EricCloseHandleToCertificate() freigegeben werden, spätestens jedoch zum Programmende bzw. vor dem Entladen der Bibliothek ericapi.

Parameter
[out]hTokenHandle zu einem der folgenden Zertifikate:
  • Portalzertifikat
  • clientseitig erzeugtes Zertifikat
[in]pkcs12ContainerSpeicheradresse des Zertifikats im PKCS#12-Format. Es werden nur passwortgeschützte PKCS#12-Container akzeptiert.
[in]containerGroesseGröße des PKCS#12-Containers in Bytes
[in]pkcs12PasswortDas Passwort oder die PIN des PKCS#12-Containers. Dieser Parameter darf nicht NULL sein.
Rückgabe
Siehe auch