![]() |
![]() |
![]() |
GEIER Reference Manual | ![]() |
---|---|---|---|---|
geier_context; int geier_init (int debug); int geier_exit (void); geier_context* geier_context_new (void); void geier_context_free (geier_context *context); int geier_send (geier_context *context, const xmlDoc *input, xmlDoc **output); int geier_send_text (geier_context *context, unsigned char *input, size_t inlen, unsigned char **output, size_t *outlen); char* geier_get_clearing_error (geier_context *context, const xmlDoc *input); char* geier_get_clearing_error_text (geier_context *context, unsigned char *input, size_t inlen); int geier_send_encrypted (geier_context *context, const xmlDoc *input, xmlDoc **output); int geier_send_encrypted_text (geier_context *context, unsigned char *input, size_t inlen, unsigned char **output, size_t *outlen); int geier_encrypt (geier_context *context, const xmlDoc *input, xmlDoc **output); int geier_encrypt_text (geier_context *context, unsigned char *input, size_t inlen, unsigned char **output, size_t *outlen); int geier_decrypt (geier_context *context, const xmlDoc *input, xmlDoc **output); int geier_decrypt_text (geier_context *context, unsigned char *input, size_t inlen, unsigned char **output, size_t *outlen); int geier_xml_to_text (geier_context *context, const xmlDoc *input, unsigned char **output, size_t *outlen); int geier_xml_to_encoded_text (geier_context *context, const xmlDoc *input, const char *encoding, unsigned char **output, size_t *outlen); int geier_text_to_xml (geier_context *context, unsigned char *input, size_t inlen, xmlDoc **output); enum geier_format; int geier_validate (geier_context *context, geier_format f, const xmlDoc *input); int geier_validate_text (geier_context *context, geier_format f, unsigned char *input, size_t inlen); int geier_dsig_sign (geier_context *context, const xmlDoc *input, xmlDoc **output, const char *softpse_filename, const char *pincode); int geier_dsig_sign_softpse (geier_context *context, const xmlDoc *input, xmlDoc **output, const char *softpse_filename, const char *pincode); int geier_dsig_sign_opensc (geier_context *context, const xmlDoc *input, xmlDoc **output, unsigned int cert_id); int geier_dsig_sign_text (geier_context *context, unsigned char *input, size_t inlen, unsigned char **output, size_t *outlen, const char *softpse_filename, const char *pincode); int geier_dsig_sign_softpse_text (geier_context *context, unsigned char *input, size_t inlen, unsigned char **output, size_t *outlen, const char *softpse_filename, const char *pincode); int geier_dsig_sign_opensc_text (geier_context *context, unsigned char *input, size_t inlen, unsigned char **output, size_t *outlen, unsigned int cert_id); int geier_xsltify (geier_context *context, const xmlDoc *input, xmlDoc **output); int geier_xsltify_text (geier_context *context, unsigned char *input, size_t inlen, unsigned char **output, size_t *outlen);
typedef struct _geier_context geier_context;
A transparent structure, that has to be passed to most of the functions contained in this library. It mainly is used to store encoder information as well as session keys, needed when sending data to the fiscal authorities.
Please make sure not to call two library functions using the same context within two different threads. Everything else should be threadsafe.
int geier_init (int debug);
Initialize GEIER library as well as libxml, libxmlsec, libxslt in turn. This has to be called first.
|
set the debug level (0 for no debuging output)
|
Returns : |
0 on success, 1 on error.
|
int geier_exit (void);
Shut the GEIER library down. Ask libxml, libxmlsec, libxslt to shut down as well. This should be called last.
Returns : |
0 on success, 1 on error.
|
geier_context* geier_context_new (void);
Allocate a new geier_context.
Returns : |
a new geier_context. |
void geier_context_free (geier_context *context);
Deallocates a previously allocated geier_context.
|
the geier_context to free. |
int geier_send (geier_context *context, const xmlDoc *input, xmlDoc **output);
Send the Elster-XML document, which is supplied as input
, like
geier_send_encrypted does, but automatically take care of encryption
and decryption. Furthermore compression and Base64 encoding is
handled internally.
Beware that this functions returns 0
upon successful transmission, this
is, if the transmitted data is invalid, 0
is returned no matter what.
See geier_get_clearing_error for details.
|
a geier_context. |
|
the XML document that should be sent. |
|
pointer to where the returned XML document should be written to. |
Returns : |
0 upon successful transmission, 1 on error. The returned
document is written to output on success.
|
int geier_send_text (geier_context *context, unsigned char *input, size_t inlen, unsigned char **output, size_t *outlen);
Send the Elster-XML document, which is supplied as input
, like
geier_send_encrypted_text, but automatically take care of encryption
and decryption. Furthermore compression and Base64 encoding is
handled automatically.
Beware that this functions returns 0
upon successful transmission, this
is, if the transmitted data is invalid, 0
is returned no matter what.
See geier_get_clearing_error_text for details.
|
a geier_context. |
|
the XML document that should be sent, supplied as a C string. |
|
the length of input .
|
|
pointer to where the returned XML document should be written to (as a C string). |
|
the length of the buffer output points to.
|
Returns : |
0 upon successful transmission, 1 on error. The returned
document is written to output on success, the length of output is
stored to outlen .
|
char* geier_get_clearing_error (geier_context *context, const xmlDoc *input);
Check the provided (unencrypted) Elster-XML document, supplied as input
,
for error codes and return suitable error messages. input
should be
a XML document supplied by one of the clearing hosts as returned by
geier_send.
|
a geier_context. |
|
the XML document that should be checked for errors. |
Returns : |
NULL upon success, a suitable error message otherwise. The
error message should be user understandable and is in German language.
Call free on the returned pointer, if the message is not needed anymore.
|
char* geier_get_clearing_error_text (geier_context *context, unsigned char *input, size_t inlen);
Check the provided (unencrypted) Elster-XML document, supplied as input
,
for error codes and return suitable error messages. input
should be
a XML document supplied by one of the clearing hosts as returned by
geier_send_text.
|
a geier_context. |
|
the XML document that should be checked for errors, supplied as a C string. |
|
the length of input .
|
Returns : |
NULL upon success, a suitable error message otherwise. The
error message should be user understandable and is in German language.
Call free on the returned pointer, if the message is not needed anymore.
|
int geier_send_encrypted (geier_context *context, const xmlDoc *input, xmlDoc **output);
Send an already encrypted Elster-XML document, which is supplied as
input
, quite like geier_send does. But unlike the latter don't
care for encipherment. This is, geier_send_encrypted relies on
input
being encrypted using geier_encrypt already.
Beware that this functions returns 0
upon successful transmission, this
is, if the transmitted data is invalid, 0
is returned no matter what.
See geier_get_clearing_error for details.
|
a geier_context. |
|
the XML document that should be sent. |
|
pointer to where the returned XML document should be written to. |
Returns : |
0 upon successful transmission, 1 on error. The returned
document is written to output on success.
|
int geier_send_encrypted_text (geier_context *context, unsigned char *input, size_t inlen, unsigned char **output, size_t *outlen);
Send an already encrypted Elster-XML document, which is supplied as
input
, quite like geier_send_text does. But unlike the latter
don't care for encipherment. This is, geier_send_encrypted_text
relies on input
being encrypted using geier_encrypt_text already.
Beware that this functions returns 0
upon successful transmission, this
is, if the transmitted data is invalid, 0
is returned no matter what.
See geier_get_clearing_error_text for details.
|
a geier_context. |
|
the XML document that should be sent, supplied as a C string. |
|
the length of input .
|
|
pointer to where the returned XML document should be written to (as a C string). |
|
the length of the buffer output points to.
|
Returns : |
0 upon successful transmission, 1 on error. The returned
document is written to output on success, the length of output is
stored to outlen .
|
int geier_encrypt (geier_context *context, const xmlDoc *input, xmlDoc **output);
Encrypt the relevant parts (those the Coala specification requires to be
crypted) of the provided Elster-XML document (supplied as input
).
Furthermore compression and Base64 encoding is handled automatically.
|
a geier_context. |
|
the XML document that should be encrypted. |
|
pointer to where the encrypted XML document should be written to. |
Returns : |
0 on success, 1 on error. The encrypted document is written to
output on success.
|
int geier_encrypt_text (geier_context *context, unsigned char *input, size_t inlen, unsigned char **output, size_t *outlen);
Encrypt the relevant parts (those the Coala specification requires to be
crypted) of the provided Elster-XML document (supplied as input
).
Furthermore compression and Base64 encoding is handled automatically.
|
a geier_context. |
|
the XML document that should be encrypted, supplied as a C string. |
|
the length of input .
|
|
pointer to where the encrypted XML document should be written to (as a C string). |
|
the length of the buffer output points to.
|
Returns : |
0 on success, 1 on error. The encrypted document is written to
output on success, the length of output is stored to outlen .
|
int geier_decrypt (geier_context *context, const xmlDoc *input, xmlDoc **output);
Decrypt the encrypted parts (those that the Coala specification requires
to be sent encrypted) of the Elster-XML document provided as input
.
Furthermore decompression and Base64 decoding is handled
internally.
Please mind, that you cannot use geier_decrypt to decrypt data that has been enciphered and sent using another geier_context. This is due to the 3DES key to be contained in the geier_context.
|
a geier_context. |
|
the XML document that should be decrypted. |
|
pointer to where the decrypted XML document should be written to. |
Returns : |
0 on success, 1 on error. The decrypted document is written to
output on success.
|
int geier_decrypt_text (geier_context *context, unsigned char *input, size_t inlen, unsigned char **output, size_t *outlen);
Decrypt the encrypted parts (those that the Coala specification requires
to be sent encrypted) of the Elster-XML document provided as input
.
Furthermore decompression and Base64 decoding is handled internally.
Please mind, that you cannot use geier_decrypt to decrypt data that has been enciphered and sent using another geier_context. This is due to the 3DES key to be contained in the geier_context.
|
a geier_context. |
|
the XML document that should be decrypted, supplied as a C string. |
|
the length of input .
|
|
pointer to where the decrypted XML document should be written to (as a C string). |
|
the length of the buffer output points to.
|
Returns : |
0 on success, 1 on error. The decrypted document is written to
output on success, the length of output is stored to outlen .
|
int geier_xml_to_text (geier_context *context, const xmlDoc *input, unsigned char **output, size_t *outlen);
Convert the XML document to a zero-terminated C string.
|
a geier_context. |
|
the XML document that should be converted |
|
pointer to where the document should be written to (as a C string) |
|
the length of the buffer output points to.
|
Returns : |
0 on success, 1 on error. The not further modified document is
written to output on success, the length of output is stored to outlen .
|
int geier_xml_to_encoded_text (geier_context *context, const xmlDoc *input, const char *encoding, unsigned char **output, size_t *outlen);
Convert the XML document to a zero-terminated C string, like
geier_xml_to_text does, but furthermore convert to encoding encoding
.
|
a geier_context. |
|
the XML document that should be converted |
|
the encoding to possibly convert the XML document to. |
|
pointer to where the document should be written to (as a C string) |
|
the length of the buffer output points to.
|
Returns : |
0 on success, 1 on error. The resulting document is
written to output on success, the length of output is stored to outlen .
|
int geier_text_to_xml (geier_context *context, unsigned char *input, size_t inlen, xmlDoc **output);
Convert the XML document, supplied as a C string as input
, to a libxml
XML document.
|
a geier_context. |
|
the XML document that should be converted, supplied as a C string. |
|
the length of input .
|
|
pointer to where the document should be written to |
Returns : |
0 on success, 1 on error. The not further modified document is
written to output on success.
|
typedef enum _geier_format { geier_format_encrypted, geier_format_unencrypted, /* geier_nutzdatenblock, */ /* geier_nutzdaten_raw, */ /* geier_nutzdaten_user, */ } geier_format;
Format specifier that has to be passed to geier_validate and geier_validate_text for those to distinct between different Elster-XML tree flavours.
Please mind, that currently only geier_format_unencrypted is supported.
int geier_validate (geier_context *context, geier_format f, const xmlDoc *input);
Validate the Elster-XML document against the Schema files supplied by the German fiscal authorities and shipped along with libgeier.
Please mind the the only geier_format (f
) that currently is supported
by geier_validate is geier_format_unencrypted.
|
a geier_context. |
|
geier_format specifier. |
|
the XML document that should be validated. |
Returns : |
0 upon successful validation, 1 on error.
|
int geier_validate_text (geier_context *context, geier_format f, unsigned char *input, size_t inlen);
Validate the Elster-XML document against the Schema files supplied by the German fiscal authorities and shipped along with libgeier.
Please mind the the only geier_format (f
) that currently is supported
by geier_validate_text is geier_format_unencrypted.
|
a geier_context. |
|
geier_format specifier. |
|
the XML document that should be validated, supplied as a C string. |
|
the length of input .
|
Returns : |
0 upon successful validation, 1 on error.
|
int geier_dsig_sign (geier_context *context, const xmlDoc *input, xmlDoc **output, const char *softpse_filename, const char *pincode);
Sign the provided Elster-XML document (supplied as input
) with the software
certificate, that is automatically extracted from the PKCS#12 file with
the provided filename. The pincode
is used to decrypt the container.
Deprecated
: This funtion has been renamed since 0.8. Please use
geier_dsig_sign_softpse, which has exactly the same signature.
|
a geier_context. |
|
the XML document that should be signed. |
|
pointer to where the signed XML document should be written to. |
|
name of the PKCS#12 container file. |
|
the pincode. |
Returns : |
0 on success, 1 on error. The signed document is written to
output .
|
int geier_dsig_sign_softpse (geier_context *context, const xmlDoc *input, xmlDoc **output, const char *softpse_filename, const char *pincode);
Sign the provided Elster-XML document (supplied as input
) with the software
certificate, that is automatically extracted from the PKCS#12 file with
the provided filename. The pincode
is used to decrypt the container.
|
a geier_context. |
|
the XML document that should be signed. |
|
pointer to where the signed XML document should be written to. |
|
name of the PKCS#12 container file. |
|
the pincode. |
Returns : |
0 on success, 1 on error. The signed document is written to
output .
|
int geier_dsig_sign_opensc (geier_context *context, const xmlDoc *input, xmlDoc **output, unsigned int cert_id);
Sign the provided Elster-XML document (supplied as input
) using a
smartcard. You need to specify the ID of the certificate to use for
signing as cert_id
, as it is returned by pkcs15-tool.
This function is only available in OpenSSL-based libgeier versions.
|
a geier_context. |
|
the XML document that should be signed. |
|
pointer to where the signed XML document should be written to. |
|
the certificate id to use. |
Returns : |
0 on success, 1 on error. The signed document is written to
output .
|
int geier_dsig_sign_text (geier_context *context, unsigned char *input, size_t inlen, unsigned char **output, size_t *outlen, const char *softpse_filename, const char *pincode);
Sign the provided Elster-XML document (supplied as input
) with the software
certificate, that is automatically extracted from the PKCS#12 file with
the provided filename. The pincode
is used to decrypt the container.
Deprecated
: This funtion has been renamed since 0.8. Please use
geier_dsig_sign_softpse_text, which has exactly the same signature.
|
a geier_context. |
|
the XML document that should be signed, supplied as a C string. |
|
the length of input .
|
|
pointer to where the resulting XML document should be written to (as a C string) |
|
the length of the buffer output points to.
|
|
name of the PKCS#12 container file. |
|
the pincode. |
Returns : |
0 on success, 1 on error. The signed document is written to
output , the length of output is stored to outlen on success.
|
int geier_dsig_sign_softpse_text (geier_context *context, unsigned char *input, size_t inlen, unsigned char **output, size_t *outlen, const char *softpse_filename, const char *pincode);
Sign the provided Elster-XML document (supplied as input
) with the software
certificate, that is automatically extracted from the PKCS#12 file with
the provided filename. The pincode
is used to decrypt the container.
|
a geier_context. |
|
the XML document that should be signed, supplied as a C string. |
|
the length of input .
|
|
pointer to where the resulting XML document should be written to (as a C string) |
|
the length of the buffer output points to.
|
|
name of the PKCS#12 container file. |
|
the pincode. |
Returns : |
0 on success, 1 on error. The signed document is written to
output , the length of output is stored to outlen on success.
|
int geier_dsig_sign_opensc_text (geier_context *context, unsigned char *input, size_t inlen, unsigned char **output, size_t *outlen, unsigned int cert_id);
Sign the provided Elster-XML document (supplied as input
) using a
smartcard. You need to specify the ID of the certificate to use for
signing as cert_id
, as it is returned by pkcs15-tool.
This function is only available in OpenSSL-based libgeier versions.
|
a geier_context. |
|
the XML document that should be signed, supplied as a C string. |
|
the length of input .
|
|
pointer to where the resulting XML document should be written to (as a C string) |
|
the length of the buffer output points to.
|
|
the certificate id to use. |
Returns : |
0 on success, 1 on error. The signed document is written to
output , the length of output is stored to outlen on success.
|
int geier_xsltify (geier_context *context, const xmlDoc *input, xmlDoc **output);
Automatically generate a transmission protocol for the Elster-XML
document, that is supplied as input
. The protocol is generated
using the XSLT-File that is shipped along with this library.
You can call this function even before calling geier_send, this will result in a common protocol that only states that it has been printed before transmission.
|
a geier_context. |
|
the XML document for that a protocol should be generated. |
|
pointer to where the returned XHTML document should be written to. |
Returns : |
0 upon successful transmission, 1 on error. The returned
document is written to output on success.
|
int geier_xsltify_text (geier_context *context, unsigned char *input, size_t inlen, unsigned char **output, size_t *outlen);
Automatically generate a transmission protocol for the Elster-XML
document, that is supplied as input
. The protocol is generated
using the XSLT-File that is shipped along with this library.
You can call this function even before calling geier_send_text, this will result in a common protocol that only states that it has been printed before transmission.
|
a geier_context. |
|
the XML document for that a protocol should be generated, supplied as a C string. |
|
the length of input .
|
|
pointer to where the returned XHTML document should be written to (as a C string). |
|
the length of the buffer output points to.
|
Returns : |
0 upon successful generation, 1 on error. The returned
document is written to output on success, the length of output is
stored to outlen .
|