include/event2/bufferevent_ssl.h

0001 /*
0002  * Copyright (c) 2009-2012 Niels Provos and Nick Mathewson
0003  *
0004  * Redistribution and use in source and binary forms, with or without
0005  * modification, are permitted provided that the following conditions
0006  * are met:
0007  * 1. Redistributions of source code must retain the above copyright
0008  *    notice, this list of conditions and the following disclaimer.
0009  * 2. Redistributions in binary form must reproduce the above copyright
0010  *    notice, this list of conditions and the following disclaimer in the
0011  *    documentation and/or other materials provided with the distribution.
0012  * 3. The name of the author may not be used to endorse or promote products
0013  *    derived from this software without specific prior written permission.
0014  *
0015  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
0016  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
0017  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
0018  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
0019  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
0020  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
0021  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
0022  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
0023  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
0024  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
0025  */
0026 #ifndef EVENT2_BUFFEREVENT_SSL_H_INCLUDED_
0027 #define EVENT2_BUFFEREVENT_SSL_H_INCLUDED_
0028
0029 /** @file event2/bufferevent_ssl.h
0030
0031     OpenSSL support for bufferevents.
0032  */
0033 #include <event2/visibility.h>
0034 #include <event2/event-config.h>
0035 #include <event2/bufferevent.h>
0036 #include <event2/util.h>
0037
0038 #ifdef __cplusplus
0039 extern "C" {
0040 #endif
0041
0042 /* This is what openssl's SSL objects are underneath. */
0043 struct ssl_st;
0044
0045 /**
0046    The state of an SSL object to be used when creating a new
0047    SSL bufferevent.
0048  */
0049 enum bufferevent_ssl_state {
0050     BUFFEREVENT_SSL_OPEN = 0,
0051     BUFFEREVENT_SSL_CONNECTING = 1,
0052     BUFFEREVENT_SSL_ACCEPTING = 2
0053 };
0054
0055 #if defined(EVENT__HAVE_OPENSSL) || defined(EVENT_IN_DOXYGEN_)
0056 /**
0057    Create a new SSL bufferevent to send its data over another bufferevent.
0058
0059    @param base An event_base to use to detect reading and writing.  It
0060       must also be the base for the underlying bufferevent.
0061    @param underlying A socket to use for this SSL
0062    @param ssl A SSL* object from openssl.
0063    @param state The current state of the SSL connection
0064    @param options One or more bufferevent_options
0065    @return A new bufferevent on success, or NULL on failure
0066 */
0067 EVENT2_EXPORT_SYMBOL
0068 struct bufferevent *
0069 bufferevent_openssl_filter_new(struct event_base *base,
0070     struct bufferevent *underlying,
0071     struct ssl_st *ssl,
0072     enum bufferevent_ssl_state state,
0073     int options);
0074
0075 /**
0076    Create a new SSL bufferevent to send its data over an SSL * on a socket.
0077
0078    @param base An event_base to use to detect reading and writing
0079    @param fd A socket to use for this SSL
0080    @param ssl A SSL* object from openssl.
0081    @param state The current state of the SSL connection
0082    @param options One or more bufferevent_options
0083    @return A new bufferevent on success, or NULL on failure.
0084 */
0085 EVENT2_EXPORT_SYMBOL
0086 struct bufferevent *
0087 bufferevent_openssl_socket_new(struct event_base *base,
0088     evutil_socket_t fd,
0089     struct ssl_st *ssl,
0090     enum bufferevent_ssl_state state,
0091     int options);
0092
0093 /** Control how to report dirty SSL shutdowns.
0094
0095     If the peer (or the network, or an attacker) closes the TCP
0096     connection before closing the SSL channel, and the protocol is SSL >= v3,
0097     this is a "dirty" shutdown.  If allow_dirty_shutdown is 0 (default),
0098     this is reported as BEV_EVENT_ERROR.
0099
0100     If instead allow_dirty_shutdown=1, a dirty shutdown is reported as
0101     BEV_EVENT_EOF.
0102
0103     (Note that if the protocol is < SSLv3, you will always receive
0104     BEV_EVENT_EOF, since SSL 2 and earlier cannot distinguish a secure
0105     connection close from a dirty one.  This is one reason (among many)
0106     not to use SSL 2.)
0107 */
0108
0109 EVENT2_EXPORT_SYMBOL
0110 int bufferevent_openssl_get_allow_dirty_shutdown(struct bufferevent *bev);
0111 EVENT2_EXPORT_SYMBOL
0112 void bufferevent_openssl_set_allow_dirty_shutdown(struct bufferevent *bev,
0113     int allow_dirty_shutdown);
0114
0115 /** Return the underlying openssl SSL * object for an SSL bufferevent. */
0116 EVENT2_EXPORT_SYMBOL
0117 struct ssl_st *
0118 bufferevent_openssl_get_ssl(struct bufferevent *bufev);
0119
0120 /** Tells a bufferevent to begin SSL renegotiation. */
0121 EVENT2_EXPORT_SYMBOL
0122 int bufferevent_ssl_renegotiate(struct bufferevent *bev);
0123
0124 /** Return the most recent OpenSSL error reported on an SSL bufferevent. */
0125 EVENT2_EXPORT_SYMBOL
0126 unsigned long bufferevent_get_openssl_error(struct bufferevent *bev);
0127
0128 #endif
0129
0130 #ifdef __cplusplus
0131 }
0132 #endif
0133
0134 #endif /* EVENT2_BUFFEREVENT_SSL_H_INCLUDED_ */