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
|
<refentry id="refsockinit">
<refmeta>
<refentrytitle>ne_sock_init</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname id="ne_sock_init">ne_sock_init</refname>
<refname id="ne_sock_exit">ne_sock_exit</refname>
<refpurpose>perform library initialization</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ne_socket.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>ne_sock_init</function></funcdef>
<void/>
</funcprototype>
<funcprototype>
<funcdef>void <function>ne_sock_exit</function></funcdef>
<void/>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>In some platforms and configurations, &neon; may be using
some socket or SSL libraries which require global initialization
before use. To perform this initialization, the
<function>ne_sock_init</function> function must be called before
any other library functions are used.</para>
<para>Once all use of &neon; is complete,
<function>ne_sock_exit</function> can be called to perform
de-initialization of socket or SSL libraries, if necessary. Uses
of <function>ne_sock_init</function> and
<function>ne_sock_exit</function> are "reference counted"; if N
calls to <function>ne_sock_init</function> are made, only the Nth
call to <function>ne_sock_exit</function> will have effect.</para>
<para><function>ne_sock_init</function> will set the disposition
of the <literal>SIGPIPE</literal> signal to
<emphasis>ignored</emphasis>. No change is made to the
<literal>SIGPIPE</literal> disposition by
<function>ne_sock_exit</function>.</para>
<para>Both the SSL libraries supported by &neon; — OpenSSL
and GnuTLS — require callbacks to be registered to allow
thread-safe use of SSL. These callbacks are stored as global
variables and so their state persists for as long as the library
in question is loaded into the process. If multiple users of the
SSL library exist within the process, this can be problematic,
particularly if one is dynamically loaded (and may subsequently be
unloaded).</para>
<para>If &neon; is configured using the
<literal>--enable-threadsafe-ssl</literal> flag, thread-safe SSL
support will be enabled automatically, as covered in the following
section. Otherwise, it is not safe to use &neon; with SSL in a
multi-threaded process. The <xref linkend="ne_has_support"/>
function can be used to determine whether &neon; is built to
enable thread-safety support in the SSL library.</para>
<refsect2>
<title>Thread-safe SSL with OpenSSL</title>
<para>&neon; follows two simple rules when dealing with the
OpenSSL locking callbacks:
<itemizedlist>
<listitem><simpara><function>ne_sock_init</function> will set
thread-safety locking callbacks if and only if no locking
callbacks are already registered.</simpara></listitem>
<listitem><simpara><function>ne_sock_exit</function> will
unset the thread-safety locking callbacks if and only if the
locking callbacks registered are those registered by
<function>ne_sock_init</function>.</simpara></listitem>
</itemizedlist>
Applications and libraries should be able to co-operate to
ensure that SSL use is always thread-safe if similar rules are
always followed.</para>
</refsect2>
<refsect2>
<title>Thread-safe SSL with GnuTLS</title>
<para>The cryptography library used by GnuTLS, libgcrypt, only
supports an initialization operation to register thread-safety
callbacks. <function>ne_sock_init</function> will register the
thread-safe locking callbacks on first use;
<function>ne_sock_exit</function> cannot unregister them. If
multiple users of GnuTLS are present within the process, it is
unsafe to dynamically unload &neon; from the process if &neon;
is configured with thread-safe SSL support enabled (since the
callbacks would be left pointing at unmapped memory once &neon;
is unloaded).</para>
</refsect2>
</refsect1>
<refsect1>
<title>Return value</title>
<para><function>ne_sock_init</function> returns zero on success,
or non-zero on error. If an error occurs, no further use of the
&neon; library should be attempted.</para>
</refsect1>
<refsect1>
<title>See also</title>
<para><xref linkend="refneon"/>, <xref linkend="reffeat"/></para>
</refsect1>
</refentry>
|
