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
|
Written by Albrecht Dreß <albrecht.dress@arcor.de>
Copyright (C) Albrecht Dreß 2017 - 2020
This library is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published bythe Free Software
Foundation, either version 2 of the License, or (at your option) any later
version.
This library is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with
this library. If not, see <https://www.gnu.org/licenses/>.
Purpose
=======
This library provides an implementation of CRLF-terminated line-based client
protocols built on top of GIO. It provides a base module, containing the
line-based IO methods, and on top of that POP3 (RFC1939) and SMTP (RFC5321)
client classes.
Coding Style
============
The implementation tries to follow the MISRA C:2012 (MISRA C3) and SEI CERT
Secure Coding standards for safer code. For further details about these
standards, see
<https://www.misra.org.uk/Publications/tabid/57/Default.aspx> and
<https://www.securecoding.cert.org/confluence/display/c/SEI+CERT+C+Coding+Standard>.
Requirements
============
Apart from GLib/GIO (at least version 2.40.0) it requires GnuTLS.
For Kerberos V5 single sign-on (GSSAPI, RFC 4752) authentication, a Kerberos
library (e.g. Heimdal) is required.
API Documentation
=================
Doxygen is required to create a HTML API documentation. Install doxygen from
<http://www.stack.nl/~dimitri/doxygen/download.html>. Then run in this folder
make doc
and open html/index.html.
Testing
=======
In the folder test, a test application for running unit tests, a check for
memory leaks and a coverage analysis is available. The following packages
are required for running them:
- the Sput Unit Testing Framework for C/C++, available from
<http://www.use-strict.de/sput-unit-testing/>
- python2
- screen, available from <https://www.gnu.org/software/screen/>
- sudo, available from <https://www.sudo.ws/>
- Valgrind, avilable from <http://valgrind.org/>
- LCOV and Genhtml, available from
<http://ltp.sourceforge.net/coverage/lcov.php>
- gnutls-serv, which is a part of the GnuTLS package, available from
<https://www.gnutls.org/>
- INetSim Internet Services Simulation Suite, available from
<http://www.inetsim.org/>
Note that most of these requirements are typically available pre-packaged
for your favorite distribution.
Unfortunately, INetSim 1.3.2 has two bugs in POP3 handling and does not
offer pipelining. The file test/inetsim-1.3.2.diff contains a patch which
fixes these issues.
Some gnutls-serv versions will replace received CRLF line endings by just
LF, breaking several tests. A fixed version is available from the GnuTLS
gitlab repository only (see https://gitlab.com/gnutls/gnutls/-/issues/1073
and https://gitlab.com/gnutls/gnutls/-/merge_requests/1314).
For running the tests, open two terminal windows, and cd to the test folder
of this package.
In the first terminal, call
./start-test-env.sh
which will launch several dummy servers and two INetSim instances required
for testing. Note that INetSim requires root permissions and is thus
called via sudo.
Then, in the second terminal, call
make tests
to build the test application, and run it in Valgrind.
The test produces the following output:
- stdout/stderr: unit test results, which shall report zero failed
- tests.vg: the output of the Valgrind memory check
- gcov/index.html: results of the coverage analysis
Finally, just terminate the test servers in the first window. Note that
INetSim will dump further information in its output files in the test
folder. You should verify that INetSim recorded the requested operations
properly.
Note that no unit tests are available for the GSSAPI authentication methods
as they are not supported by INetSim.
-oOo-
|
