2 * Copyright (C) 2010 Martin Willi
4 * Copyright (C) secunet Security Networks AG
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the
8 * Free Software Foundation; either version 2 of the License, or (at your
9 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
11 * This program is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
18 * @defgroup tls_socket tls_socket
27 typedef struct tls_socket_t tls_socket_t
;
32 * Wraps a blocking (socket) file descriptor for a reliable transport into a
33 * TLS secured socket. TLS negotiation happens on demand, certificates and
34 * private keys are fetched from any registered credential set.
39 * Read data from secured socket.
41 * This call is blocking, you may use select() on the underlying socket to
42 * wait for data. If "block" is FALSE and no application data is available,
43 * the function returns -1 and sets errno to EWOULDBLOCK.
45 * @param buf buffer to write received data to
46 * @param len size of buffer
47 * @param block TRUE to block this call, FALSE to fail if it would block
48 * @return number of bytes read, 0 on EOF, -1 on error
50 ssize_t (*read
)(tls_socket_t
*this, void *buf
, size_t len
, bool block
);
53 * Write data over the secured socket.
55 * @param buf data to send
56 * @param len number of bytes to write from buf
57 * @return number of bytes written, -1 on error
59 ssize_t (*write
)(tls_socket_t
*this, void *buf
, size_t len
);
62 * Read/write plain data from file descriptor.
64 * This call is blocking, but a thread cancellation point. Data is
65 * exchanged until one of the sockets gets closed or an error occurs.
67 * @param rfd file descriptor to read plain data from
68 * @param wfd file descriptor to write plain data to
69 * @return TRUE if data exchanged successfully
71 bool (*splice
)(tls_socket_t
*this, int rfd
, int wfd
);
74 * Get the underlying file descriptor passed to the constructor.
76 * @return file descriptor
78 int (*get_fd
)(tls_socket_t
*this);
81 * Return the server identity.
83 * @return server identity
85 identification_t
* (*get_server_id
)(tls_socket_t
*this);
88 * Return the peer identity.
90 * @return peer identity
92 identification_t
* (*get_peer_id
)(tls_socket_t
*this);
95 * Destroy a tls_socket_t.
97 void (*destroy
)(tls_socket_t
*this);
101 * Create a tls_socket instance.
103 * Use TLS_UNSPEC to default to the configured min/max version.
105 * @param is_server TRUE to act as TLS server
106 * @param server server identity
107 * @param peer client identity, NULL for no client authentication
108 * @param fd socket to read/write from
109 * @param cache session cache to use, or NULL
110 * @param min_version minimum TLS version to negotiate or TLS_UNSPEC
111 * @param max_version maximum TLS version to negotiate or TLS_UNSPEC
112 * @param flags flags controlling the TLS stack
113 * @return TLS socket wrapper
115 tls_socket_t
*tls_socket_create(bool is_server
, identification_t
*server
,
116 identification_t
*peer
, int fd
,
117 tls_cache_t
*cache
, tls_version_t min_version
,
118 tls_version_t max_version
, tls_flag_t flags
);
120 #endif /** TLS_SOCKET_H_ @}*/