eric-bindings 0.5.0

Rust bindings for the ELSTER Rich Client (ERiC)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

<!-- markdownlint-disable MD059 -->

# Eric

[![latest version](https://img.shields.io/crates/v/eric-bindings.svg?label=eric-bindings)](https://crates.io/crates/eric-bindings)
[![documentation](https://img.shields.io/docsrs/eric-bindings?label=eric-bindings)](https://docs.rs/eric-bindings)
[![latest version](https://img.shields.io/crates/v/eric-sdk.svg?label=eric-sdk)](https://crates.io/crates/eric-sdk)
[![documentation](https://img.shields.io/docsrs/eric-sdk?label=eric-sdk)](https://docs.rs/eric-sdk)
[![build status](https://github.com/quambene/eric-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/quambene/eric-rs/actions/workflows/ci.yml)

Rust bindings and SDK for the ELSTER Rich Client (ERiC)

- [What is ELSTER?](#what-is-elster)
- [What is ERiC?](#what-is-eric)
- [Requirements](#requirements)
- [Rust bindings](#rust-bindings)
  - [Select bindings](#select-bindings)
  - [Generate bindings](#generate-bindings)
  - [Test bindings](#test-bindings)
- [Eric SDK](#eric-sdk)
  - [Usage](#usage)
  - [Supported Eric versions](#supported-eric-versions)
  - [Test SDK](#test-sdk)
- [Changelog](#changelog)

## What is ELSTER?

Elster (short for _Elektronische Steuererklärung_) is a project by the German tax administration to process tax returns and declarations.

## What is ERiC?

ERiC (short for _Elster Rich Client_) is a shared C library that is integrated into a tax application. ERiC checks the data provided by the tax application for plausibility, and transmits the validated data in encrypted form to the computing center of the respective tax administration.

## Requirements

You need to have the shared library `libericapi.so` and the header file `ericapi.h` available on your system which can be downloaded from [ELSTER for developers](https://www.elster.de/elsterweb/entwickler/login) after access has been requested [here](https://www.elster.de/elsterweb/registrierung-entwickler/form).

## Rust bindings

Specify the path to the Eric library via environment variable `ERIC_PATH`. For
example:

``` bash
ERIC_PATH="ERiC-43.3.2.0-Linux-x86_64/ERiC-43.3.2.0/Linux-x86_64"
```

Relevant environment variables then default to

``` bash
LIBRARY_NAME=ericapi
LIBRARY_PATH="$ERIC_PATH/lib"
HEADER_FILE="$ERIC_PATH/include/ericapi.h"
PLUGIN_PATH="$ERIC_PATH/lib/plugins"
```

### Select bindings

Select bindings from the pre-generated bindings:

``` bash
cargo build -p eric-bindings
```

### Generate bindings

You can also generate bindings on-the-fly for your specific platform and
architecture by using feature flag `generate-bindings`:

``` bash
cargo build -p eric-bindings --features generate-bindings
```

The bindings are generated in
`target/debug/build/eric-bindings-<random-id>/out/bindings.rs`.

To generate the bindings on your platform and architecture, you need `libclang` as well. For example, on Debian/Ubuntu install:

``` bash
apt install llvm-dev libclang-dev clang
```

### Test bindings

The bindings are included in `src/lib.rs` via `include!` macro and tested by:

``` bash
cargo test -p eric-bindings --lib
```

Logs are written to `eric.log` in the current directory.

## Eric SDK

`eric-sdk` supports single-threaded Eric instances.

### Usage

To use `eric-sdk`, add the shared C library to your path (e.g. to `LD_LIBRARY_PATH` on Linux):

``` bash
export LD_LIBRARY_PATH="$ERIC_PATH/lib:$LD_LIBRARY_PATH"
```

To send the xml file, the path and password of the Elster certificate have to be provided via environment variables `CERTIFICATE_PATH` and `CERTIFICATE_PASSWORD`. External tests also require a `VENDOR_ID`.

### Supported Eric versions

Currently, only the latest version of the Eric library is supported.

| Rust SDK | Rust bindings | Eric     |
| -------- | ------------- | -------- |
| 0.1.0    | 0.2.0         | 38.1.6.0 |
| 0.2.0    | 0.3.0         | 39.6.4.0 |
| 0.3.0    | 0.4.0         | 40.1.8.0 |
| 0.4.0    | 0.5.0         | 43.3.2.0 |

### Test SDK

``` bash
# Run unit tests
cargo test -p eric-sdk --lib

# Run integration tests (requires ERiC library)
cargo test -p eric-sdk --test '*' -- --test-threads=1
```

To run those tests that interact with the ELSTER servers, you need to provide the following environment variables:

- `CERTIFICATE_PATH`: Path to your ELSTER certificate (`.pfx`)
- `CERTIFICATE_PASSWORD`: Password for your certificate
- `VENDOR_ID`: Your official ELSTER Vendor ID (Hersteller-ID)

``` bash
cargo test -p eric-sdk --test '*' --features external-test -- --test-threads=1
```

## Changelog

The `eric-rs` repository contains multiple crates with separate changelogs:

- `eric-bindings`: [view changelog](https://github.com/quambene/eric-rs/blob/main/eric-bindings/CHANGELOG.md)
- `eric-sdk`: [view changelog](https://github.com/quambene/eric-rs/blob/main/eric-sdk/CHANGELOG.md)