Kannel: Open Source WAP and SMS gateway  $Revision: 5037 $
conn.h
Go to the documentation of this file.
1 /* ====================================================================
2  * The Kannel Software License, Version 1.0
3  *
4  * Copyright (c) 2001-2016 Kannel Group
5  * Copyright (c) 1998-2001 WapIT Ltd.
6  * All rights reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * 1. Redistributions of source code must retain the above copyright
13  * notice, this list of conditions and the following disclaimer.
14  *
15  * 2. Redistributions in binary form must reproduce the above copyright
16  * notice, this list of conditions and the following disclaimer in
17  * the documentation and/or other materials provided with the
18  * distribution.
19  *
20  * 3. The end-user documentation included with the redistribution,
21  * if any, must include the following acknowledgment:
22  * "This product includes software developed by the
23  * Kannel Group (http://www.kannel.org/)."
24  * Alternately, this acknowledgment may appear in the software itself,
25  * if and wherever such third-party acknowledgments normally appear.
26  *
27  * 4. The names "Kannel" and "Kannel Group" must not be used to
28  * endorse or promote products derived from this software without
29  * prior written permission. For written permission, please
30  * contact org@kannel.org.
31  *
32  * 5. Products derived from this software may not be called "Kannel",
33  * nor may "Kannel" appear in their name, without prior written
34  * permission of the Kannel Group.
35  *
36  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39  * DISCLAIMED. IN NO EVENT SHALL THE KANNEL GROUP OR ITS CONTRIBUTORS
40  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
41  * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
42  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
43  * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
44  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
45  * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
46  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
47  * ====================================================================
48  *
49  * This software consists of voluntary contributions made by many
50  * individuals on behalf of the Kannel Group. For more information on
51  * the Kannel Group, please see <http://www.kannel.org/>.
52  *
53  * Portions of this software are based upon software originally written at
54  * WapIT Ltd., Helsinki, Finland for the Kannel project.
55  */
56 
57 /*
58  * conn.h - declare Connection type to wrap a file descriptor
59  *
60  * This file defines operations on the Connection type, which provides
61  * input and output buffers for a two-way file descriptor, such as a
62  * socket or a serial device.
63  *
64  * The operations are designed for non-blocking use. Blocking can be
65  * done explicitly with conn_wait() or conn_flush(). A thread that
66  * blocks in these functions can be woken up with gwthread_wakeup.
67  *
68  * The write operations will queue the data for sending. They will
69  * try to send whatever data can be sent immediately, if there's enough
70  * of it queued. "Enough" is defined by a value which can be set with
71  * conn_set_output_buffering. The caller must call either conn_wait
72  * or conn_flush to actually send the data.
73  *
74  * The read operations will return whatever data is immediately
75  * available. If none is, then the caller should not simply re-try
76  * the request (that would cause a busy-loop); instead, it should
77  * wait for more data with conn_wait().
78  *
79  * The Connection structure has internal locks, so it can be shared
80  * safely between threads. There is a race condition in the interface,
81  * however, that can cause threads to wait unnecessarily if there are
82  * multiple readers. But in that case there will always be at least one
83  * thread busy reading.
84  *
85  * The overhead of locking can be avoided by "claiming" a Connection.
86  * This means that only one thread will ever do operations on that
87  * Connection; the caller must guarantee this.
88  *
89  * If any operation returns a code that indicates that the connection
90  * is broken (due to an I/O error, normally), it will also have closed
91  * the connection. Most operations work only on open connections;
92  * not much can be done with a closed connection except destroy it.
93  */
94 
95 typedef struct Connection Connection;
96 
97 /* If conn_register was called for this connection, a callback function
98  * of type conn_callback_t will be called when new input is available,
99  * or when all data that was previously queued for output is sent.
100  * The data pointer is the one supplied by the caller of conn_register.
101  * NOTE: Beware of concurrency issues. The callback function will run
102  * in the fdset's private thread, not in the caller's thread.
103  * This also means that if the callback does a lot of work it will slow
104  * down the polling process. This may be good or bad. */
105 typedef void conn_callback_t(Connection *conn, void *data);
106 
107 /*
108  * If conn_register was called for this connection, a callback data destroyer
109  * function will be called if conn_unregister, conn_destroy or conn_register
110  * (with different data) called for this connection.
111  * This function is responsible to destroy callback data.
112  */
113 typedef void conn_callback_data_destroyer_t(void *data);
114 
115 #ifdef HAVE_LIBSSL
116 /* Open an SSL connection to the given host and port. Same behavior
117  * as conn_open_tcp() below. 'certkeyfile' specifies a PEM-encoded
118  * file where OpenSSL looks for a private key and a certificate.
119  */
120 Connection *conn_open_ssl(Octstr *host, int port, Octstr *certkeyfile, Octstr *our_host);
121 
122 /* Open an SSL connection to the given host and port. Same behavior
123  * as conn_open_tcp_nb() below. 'certkeyfile' specifies a PEM-encoded
124  * file where OpenSSL looks for a private key and a certificate.
125  */
126 Connection *conn_open_ssl_nb(Octstr *host, int port, Octstr *certkeyfile, Octstr *our_host);
127 
128 void server_ssl_init(void); /* used by http.c */
129 #endif /* HAVE_LIBSSL */
130 
131 /*
132  * get the SSL config parameters from the provided Config group.
133  * For a non-SSL system this is a no-op that does nothing.
134  */
135 void conn_config_ssl (CfgGroup *grp);
136 
137 
138 /* Open a TCP/IP connection to the given host and port. Return the
139  * new Connection. If the connection can not be made, return NULL
140  * and log the problem. */
142 
143 /* As above, but binds our end to 'our_port'. If 'our_port' is 0, uses
144  * any port like conn_open_tcp. */
146  Octstr *our_host);
147 
148 /* Open a TCP/IP connection to the given host and port. Return NULL in case of
149  * error. Overwise return new Connection. */
151 
152 /* As above, but binds our end to 'our_port'. If 'our_port' is 0, uses
153  * any port like conn_open_tcp. */
155  Octstr *our_host);
156 
157 /* Returns 0 if socket is connected, -1 overwise */
158 int conn_is_connected(Connection *conn);
159 
160 /* If socket is in the 'connecting' state, it must be listen by poller.
161  * After poller returns, connection must be checked for connection
162  * procedure's result. Return 0 if connection done successfully */
164 
165 /* Create a Connection structure around the given file descriptor.
166  * The file descriptor must not be used for anything else after this;
167  * it must always be accessed via the Connection operations. This
168  * operation cannot fail. Second var indicates if the is a SSL enabled
169  * connection. */
170 Connection *conn_wrap_fd(int fd, int ssl);
171 
172 /* Close and deallocate a Connection. Log any errors reported by
173  * the close operation. */
174 void conn_destroy(Connection *conn);
175 
176 /* Assert that the calling thread will be the only one to ever
177  * use this Connection. From now on no locking will be done
178  * on this Connection.
179  * It is a fatal error for two threads to try to claim one Connection,
180  * or for another thread to try to use a Connection that has been claimed.
181  */
182 void conn_claim(Connection *conn);
183 
184 /* Return the length of the unsent data queued for sending, in octets. */
185 long conn_outbuf_len(Connection *conn);
186 
187 /* Return the length of the unprocessed data ready for reading, in octets. */
188 long conn_inbuf_len(Connection *conn);
189 
190 /* Return 1 if there was an end-of-file indication from the last read or
191  * wait operation. */
192 int conn_eof(Connection *conn);
193 
194 /* Return 1 if there was an error indication from the last read or wait
195  * operation. */
196 int conn_error(Connection *conn);
197 
198 /* Try to write data in chunks of this size or more. Set it to 0 to
199  * get an unbuffered connection. See the discussion on output buffering
200  * at the top of this file for more information. */
201 void conn_set_output_buffering(Connection *conn, unsigned int size);
202 
203 /* Register this connection with an FDSet. This will make it unnecessary
204  * to call conn_wait. Instead, the callback function will be called when
205  * there is new data available, or when all data queued for output is
206  * sent (note that small amounts are usually sent immediately without
207  * queuing, and thus won't trigger the callback). A connection can be
208  * registered with only one FDSet at a time. Return -1 if it was
209  * already registered with a different FDSet, otherwise return 0.
210  * A connection can be re-registered with the same FDSet. This will
211  * change only the callback information, and is much more efficient
212  * than calling conn_unregister first.
213  * NOTE: Using conn_register will always mean that the Connection will be
214  * used by more than one thread, so don't also call conn_claim. */
215 #define conn_register(conn, fdset, callback, data) \
216  conn_register_real(conn, fdset, callback, data, NULL)
217 int conn_register_real(Connection *conn, FDSet *fdset,
219 
220 /*
221  * Remove the current registration and call data destroyer if not NULL.
222  */
223 void conn_unregister(Connection *conn);
224 
225 /* Block the thread until one of the following is true:
226  * - The timeout expires
227  * - New data is available for reading
228  * - Some data queued for output is sent (if there was any)
229  * - The thread is woken up via the wakeup interface (in gwthread.h)
230  * Return 1 if the timeout expired. Return 0 otherwise, if the
231  * connection is okay. Return -1 if the connection is broken.
232  * If the timeout is 0 seconds, check for the conditions above without
233  * actually blocking. If it is negative, block indefinitely.
234  */
235 int conn_wait(Connection *conn, double seconds);
236 
237 /* Try to send all data currently queued for output. Block until this
238  * is done, or until the thread is interrupted or woken up. Return 0
239  * if it worked, 1 if there was an interruption, or -1 if the connection
240  * is broken. */
241 int conn_flush(Connection *conn);
242 
243 /* Output functions. Each of these takes an open connection and some
244  * data, formats the data and queues it for sending. It may also
245  * try to send the data immediately. The current implementation always
246  * does so.
247  * Return 0 if the data was sent, 1 if it was queued for sending,
248  * and -1 if the connection is broken.
249  */
250 int conn_write(Connection *conn, Octstr *data);
251 int conn_write_data(Connection *conn, unsigned char *data, long length);
252 /* Write the length of the octstr as a standard network long, then
253  * write the octstr itself. */
254 int conn_write_withlen(Connection *conn, Octstr *data);
255 
256 /* Input functions. Each of these takes an open connection and
257  * returns data if it's available, or NULL if it's not. They will
258  * not block. They will try to read in more data if there's not
259  * enough in the buffer to fill the request. */
260 
261 /* Return whatever data is available. */
263 
264 /* Return exactly "length" octets of data, if at least that many
265  * are available. Otherwise return NULL.
266  */
267 Octstr *conn_read_fixed(Connection *conn, long length);
268 
269 /* If the input buffer starts with a full line of data (terminated by
270  * LF or CR LF), then return that line as an Octstr and remove it
271  * from the input buffer. Otherwise return NULL.
272  */
274 
275 /* Read a standard network long giving the length of the following
276  * data, then read the data itself, and pack it into an Octstr and
277  * remove it from the input buffer. Otherwise return NULL.
278  */
280 
281 /* If the input buffer contains a packet delimited by the "startmark"
282  * and "endmark" characters, then return that packet (including the marks)
283  * and delete everything up to the end of that packet from the input buffer.
284  * Otherwise return NULL.
285  * Everything up to the first startmark is discarded.
286  */
288 
289 #ifdef HAVE_LIBSSL
290 
291 #include <openssl/x509.h>
292 #include <openssl/ssl.h>
293 
294 /* Returns the SSL peer certificate for the given Connection or NULL
295  * if none.
296  */
297 X509 *get_peer_certificate(Connection *conn);
298 
299 /* These are called to initialize and shutdown the OpenSSL mutex locks.
300  * They should be called before the _init_ssl, _shutdown_ssl functions.
301  */
302 void openssl_init_locks(void);
303 void openssl_shutdown_locks(void);
304 
305 /* These must be called if SSL is used. Currently http.c calls
306  * conn_init_ssl and server_init_ssl from http_init and
307  * conn_shutdown_ssl and server_shutdown_ssl from http_shutdown.
308  */
309 void conn_init_ssl(void);
310 void conn_shutdown_ssl(void);
311 void server_init_ssl(void);
312 void server_shutdown_ssl(void);
313 
314 /* Specifies a global PEM-encoded certificate and a private key file
315  * to be used with SSL client connections (outgoing HTTP requests).
316  * conn_init_ssl() must be called first. This checks that the private
317  * key matches with the certificate and will panic if it doesn't.
318  */
319 void conn_use_global_client_certkey_file(Octstr *certkeyfile);
320 
321 /* Specifies a global PEM-encoded certificate and a private key file
322  * to be used with SSL server connections (incoming HTTP requests).
323  * conn_init_ssl() must be called first. This checks that the private
324  * key matches with the certificate and will panic if it doesn't.
325  */
326 void conn_use_global_server_certkey_file(Octstr *certfile, Octstr *keyfile);
327 
328 /* Specifies files containing certificates Kannel is willing to trusted when
329  * actins as https clients
330  */
331 void conn_use_global_trusted_ca_file(Octstr *ssl_trusted_ca_file);
332 
333 /* Configures all global variables for client and server SSL mode
334  * from the values specified within the configuration file.
335  */
336 void conn_config_ssl(CfgGroup *grp);
337 
338 /* Returns the pointer to the SSL structure of the Connection given.
339  * This should be used for determining if certain connections are
340  * SSL enabled outside of the scope of conn.c.
341  */
342 SSL *conn_get_ssl(Connection *conn);
343 
344 
345 X509 *conn_get_peer_certificate(Connection *conn);
346 #endif /* HAVE_LIBSSL */
347 
348 int conn_get_id(Connection *conn);
static long our_port
Definition: radius_acct.c:87
int conn_is_connected(Connection *conn)
Definition: conn.c:517
Definition: http.c:1998
int size
Definition: wsasm.c:84
int conn_wait(Connection *conn, double seconds)
Definition: conn.c:896
void conn_set_output_buffering(Connection *conn, unsigned int size)
Definition: conn.c:721
conn_callback_t * callback
Definition: conn.c:140
int ssl
static void startmark(unsigned char *p, long number)
Definition: gwmem-check.c:263
void conn_destroy(Connection *conn)
Definition: conn.c:619
Connection * conn_open_tcp_nb_with_port(Octstr *host, int port, int our_port, Octstr *our_host)
Definition: conn.c:498
static void endmark(unsigned char *p, size_t size)
Definition: gwmem-check.c:255
static Octstr * host
Definition: fakesmsc.c:121
long conn_outbuf_len(Connection *conn)
Definition: conn.c:675
Octstr * conn_read_everything(Connection *conn)
Definition: conn.c:1082
long conn_inbuf_len(Connection *conn)
Definition: conn.c:686
Connection * conn_open_tcp_nb(Octstr *host, int port, Octstr *our_host)
Definition: conn.c:493
void conn_claim(Connection *conn)
Definition: conn.c:663
static Octstr * our_host
Definition: radius_acct.c:86
Octstr * conn_read_fixed(Connection *conn, long length)
Definition: conn.c:1102
int conn_error(Connection *conn)
Definition: conn.c:708
void conn_callback_data_destroyer_t(void *data)
Definition: conn.h:113
int conn_get_id(Connection *conn)
Definition: conn.c:1478
Octstr * conn_read_packet(Connection *conn, int startmark, int endmark)
Definition: conn.c:1204
Octstr * conn_read_line(Connection *conn)
Definition: conn.c:1126
Connection * conn_open_tcp(Octstr *host, int port, Octstr *our_host)
Definition: conn.c:488
int fd
Definition: conn.c:117
void conn_callback_t(Connection *conn, void *data)
Definition: conn.h:105
Connection * conn_wrap_fd(int fd, int ssl)
Definition: conn.c:558
int conn_flush(Connection *conn)
Definition: conn.c:987
Definition: octstr.c:118
int conn_register_real(Connection *conn, FDSet *fdset, conn_callback_t callback, void *data, conn_callback_data_destroyer_t destroyer)
Octstr * conn_read_withlen(Connection *conn)
Definition: conn.c:1161
Definition: cfg.c:73
int conn_eof(Connection *conn)
Definition: conn.c:697
int conn_write_withlen(Connection *conn, Octstr *data)
Definition: conn.c:1067
Definition: fdset.c:70
void conn_unregister(Connection *conn)
Definition: conn.c:850
Connection * conn_open_tcp_with_port(Octstr *host, int port, int our_port, Octstr *our_host)
Definition: conn.c:540
int conn_write_data(Connection *conn, unsigned char *data, long length)
Definition: conn.c:1055
int conn_write(Connection *conn, Octstr *data)
Definition: conn.c:1043
int conn_get_connect_result(Connection *conn)
Definition: conn.c:522
void conn_config_ssl(CfgGroup *grp)
Definition: conn.c:1472
See file LICENSE for details about the license agreement for using, modifying, copying or deriving work from this software.