Geier Core Functionality

Geier Core Functionality

Functions

Types and Values

Description

Functions

geier_init ()

int
geier_init (int debug);

Initialize GEIER library as well as libxml, libxmlsec, libxslt in turn. This has to be called first.

Parameters

debug

set the debug level (0 for no debuging output)

 

Returns

0 on success, 1 on error.


geier_exit ()

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_new ()

geier_context *
geier_context_new (void);

Allocate a new geier_context.

Returns

a new geier_context.


geier_context_free ()

void
geier_context_free (geier_context *context);

Deallocates a previously allocated geier_context.

Parameters

context

the geier_context to free.

 

geier_send ()

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.

Parameters

context

a geier_context.

 

input

the XML document that should be sent.

 

output

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.


geier_send_text ()

int
geier_send_text (geier_context *context,
                 const 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.

Parameters

context

a geier_context.

 

input

the XML document that should be sent, supplied as a C string.

 

inlen

the length of input .

 

output

pointer to where the returned XML document should be written to (as a C string).

 

outlen

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 .


geier_get_clearing_error ()

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.

Parameters

context

a geier_context.

 

input

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.


geier_get_clearing_error_text ()

char *
geier_get_clearing_error_text (geier_context *context,
                               const 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.

Parameters

context

a geier_context.

 

input

the XML document that should be checked for errors, supplied as a C string.

 

inlen

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.


geier_send_encrypted ()

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.

Parameters

context

a geier_context.

 

input

the XML document that should be sent.

 

output

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.


geier_send_encrypted_text ()

int
geier_send_encrypted_text (geier_context *context,
                           const 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.

Parameters

context

a geier_context.

 

input

the XML document that should be sent, supplied as a C string.

 

inlen

the length of input .

 

output

pointer to where the returned XML document should be written to (as a C string).

 

outlen

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 .


geier_encrypt ()

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.

Parameters

context

a geier_context.

 

input

the XML document that should be encrypted.

 

output

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.


geier_encrypt_text ()

int
geier_encrypt_text (geier_context *context,
                    const 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.

Parameters

context

a geier_context.

 

input

the XML document that should be encrypted, supplied as a C string.

 

inlen

the length of input .

 

output

pointer to where the encrypted XML document should be written to (as a C string).

 

outlen

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 .


geier_decrypt ()

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.

Parameters

context

a geier_context.

 

input

the XML document that should be decrypted.

 

output

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.


geier_decrypt_text ()

int
geier_decrypt_text (geier_context *context,
                    const 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.

Parameters

context

a geier_context.

 

input

the XML document that should be decrypted, supplied as a C string.

 

inlen

the length of input .

 

output

pointer to where the decrypted XML document should be written to (as a C string).

 

outlen

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 .


geier_xml_to_text ()

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.

Parameters

context

a geier_context.

 

input

the XML document that should be converted

 

output

pointer to where the document should be written to (as a C string)

 

outlen

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 .


geier_xml_to_encoded_text ()

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 .

Parameters

context

a geier_context.

 

input

the XML document that should be converted

 

encoding

the encoding to possibly convert the XML document to.

 

output

pointer to where the document should be written to (as a C string)

 

outlen

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 .


geier_text_to_xml ()

int
geier_text_to_xml (geier_context *context,
                   const unsigned char *input,
                   size_t inlen,
                   xmlDoc **output);

Convert the XML document, supplied as a C string as input , to a libxml XML document.

Parameters

context

a geier_context.

 

input

the XML document that should be converted, supplied as a C string.

 

inlen

the length of input .

 

output

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.


geier_validate ()

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.

Parameters

context

a geier_context.

 

f

geier_format specifier.

 

input

the XML document that should be validated.

 

Returns

0 upon successful validation, 1 on error.


geier_validate_text ()

int
geier_validate_text (geier_context *context,
                     geier_format f,
                     const 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.

Parameters

context

a geier_context.

 

f

geier_format specifier.

 

input

the XML document that should be validated, supplied as a C string.

 

inlen

the length of input .

 

Returns

0 upon successful validation, 1 on error.


geier_dsig_sign ()

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.

Parameters

context

a geier_context.

 

input

the XML document that should be signed.

 

output

pointer to where the signed XML document should be written to.

 

softpse_filename

name of the PKCS#12 container file.

 

pincode

the pincode.

 

Returns

0 on success, 1 on error. The signed document is written to output .


geier_dsig_sign_softpse ()

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.

Parameters

context

a geier_context.

 

input

the XML document that should be signed.

 

output

pointer to where the signed XML document should be written to.

 

softpse_filename

name of the PKCS#12 container file.

 

pincode

the pincode.

 

Returns

0 on success, 1 on error. The signed document is written to output .


geier_dsig_sign_opensc ()

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.

Parameters

context

a geier_context.

 

input

the XML document that should be signed.

 

output

pointer to where the signed XML document should be written to.

 

cert_id

the certificate id to use.

 

Returns

0 on success, 1 on error. The signed document is written to output .


geier_dsig_sign_text ()

int
geier_dsig_sign_text (geier_context *context,
                      const 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.

Parameters

context

a geier_context.

 

input

the XML document that should be signed, supplied as a C string.

 

inlen

the length of input .

 

output

pointer to where the resulting XML document should be written to (as a C string)

 

outlen

the length of the buffer output points to.

 

softpse_filename

name of the PKCS#12 container file.

 

pincode

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.


geier_dsig_sign_softpse_text ()

int
geier_dsig_sign_softpse_text (geier_context *context,
                              const 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.

Parameters

context

a geier_context.

 

input

the XML document that should be signed, supplied as a C string.

 

inlen

the length of input .

 

output

pointer to where the resulting XML document should be written to (as a C string)

 

outlen

the length of the buffer output points to.

 

softpse_filename

name of the PKCS#12 container file.

 

pincode

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.


geier_dsig_sign_opensc_text ()

int
geier_dsig_sign_opensc_text (geier_context *context,
                             const 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.

Parameters

context

a geier_context.

 

input

the XML document that should be signed, supplied as a C string.

 

inlen

the length of input .

 

output

pointer to where the resulting XML document should be written to (as a C string)

 

outlen

the length of the buffer output points to.

 

cert_id

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.


geier_xsltify ()

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.

Parameters

context

a geier_context.

 

input

the XML document for that a protocol should be generated.

 

output

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.


geier_xsltify_text ()

int
geier_xsltify_text (geier_context *context,
                    const 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.

Parameters

context

a geier_context.

 

input

the XML document for that a protocol should be generated, supplied as a C string.

 

inlen

the length of input .

 

output

pointer to where the returned XHTML document should be written to (as a C string).

 

outlen

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 .

Types and Values

geier_context

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.


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

Members

geier_format_encrypted

   

geier_format_unencrypted