1: /*
2: * Copyright (C) 2010 Martin Willi
3: * Copyright (C) 2010 revosec AG
4: *
5: * This program is free software; you can redistribute it and/or modify it
6: * under the terms of the GNU General Public License as published by the
7: * Free Software Foundation; either version 2 of the License, or (at your
8: * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9: *
10: * This program is distributed in the hope that it will be useful, but
11: * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12: * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13: * for more details.
14: */
15:
16: /**
17: * @defgroup tls_socket tls_socket
18: * @{ @ingroup libtls
19: */
20:
21: #ifndef TLS_SOCKET_H_
22: #define TLS_SOCKET_H_
23:
24: #include "tls.h"
25:
26: typedef struct tls_socket_t tls_socket_t;
27:
28: /**
29: * TLS secured socket.
30: *
31: * Wraps a blocking (socket) file descriptor for a reliable transport into a
32: * TLS secured socket. TLS negotiation happens on demand, certificates and
33: * private keys are fetched from any registered credential set.
34: */
35: struct tls_socket_t {
36:
37: /**
38: * Read data from secured socket.
39: *
40: * This call is blocking, you may use select() on the underlying socket to
41: * wait for data. If "block" is FALSE and no application data is available,
42: * the function returns -1 and sets errno to EWOULDBLOCK.
43: *
44: * @param buf buffer to write received data to
45: * @param len size of buffer
46: * @param block TRUE to block this call, FALSE to fail if it would block
47: * @return number of bytes read, 0 on EOF, -1 on error
48: */
49: ssize_t (*read)(tls_socket_t *this, void *buf, size_t len, bool block);
50:
51: /**
52: * Write data over the secured socket.
53: *
54: * @param buf data to send
55: * @param len number of bytes to write from buf
56: * @return number of bytes written, -1 on error
57: */
58: ssize_t (*write)(tls_socket_t *this, void *buf, size_t len);
59:
60: /**
61: * Read/write plain data from file descriptor.
62: *
63: * This call is blocking, but a thread cancellation point. Data is
64: * exchanged until one of the sockets gets closed or an error occurs.
65: *
66: * @param rfd file descriptor to read plain data from
67: * @param wfd file descriptor to write plain data to
68: * @return TRUE if data exchanged successfully
69: */
70: bool (*splice)(tls_socket_t *this, int rfd, int wfd);
71:
72: /**
73: * Get the underlying file descriptor passed to the constructor.
74: *
75: * @return file descriptor
76: */
77: int (*get_fd)(tls_socket_t *this);
78:
79: /**
80: * Return the server identity.
81: *
82: * @return server identity
83: */
84: identification_t* (*get_server_id)(tls_socket_t *this);
85:
86: /**
87: * Return the peer identity.
88: *
89: * @return peer identity
90: */
91: identification_t* (*get_peer_id)(tls_socket_t *this);
92:
93: /**
94: * Destroy a tls_socket_t.
95: */
96: void (*destroy)(tls_socket_t *this);
97: };
98:
99: /**
100: * Create a tls_socket instance.
101: *
102: * Use TLS_UNSPEC to default to the configured min/max version.
103: *
104: * @param is_server TRUE to act as TLS server
105: * @param server server identity
106: * @param peer client identity, NULL for no client authentication
107: * @param fd socket to read/write from
108: * @param cache session cache to use, or NULL
109: * @param min_version minimum TLS version to negotiate or TLS_UNSPEC
110: * @param max_version maximum TLS version to negotiate or TLS_UNSPEC
111: * @param flags flags controlling the TLS stack
112: * @return TLS socket wrapper
113: */
114: tls_socket_t *tls_socket_create(bool is_server, identification_t *server,
115: identification_t *peer, int fd,
116: tls_cache_t *cache, tls_version_t min_version,
117: tls_version_t max_version, tls_flag_t flags);
118:
119: #endif /** TLS_SOCKET_H_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>