bufferevent_ssl.h revision 1.1.1.3
1279377Simp/* $NetBSD: bufferevent_ssl.h,v 1.1.1.3 2017/01/31 21:14:53 christos Exp $ */ 2279377Simp/* 3279377Simp * Copyright (c) 2009-2012 Niels Provos and Nick Mathewson 4279377Simp * 5279377Simp * Redistribution and use in source and binary forms, with or without 6279377Simp * modification, are permitted provided that the following conditions 7279377Simp * are met: 8279377Simp * 1. Redistributions of source code must retain the above copyright 9279377Simp * notice, this list of conditions and the following disclaimer. 10279377Simp * 2. Redistributions in binary form must reproduce the above copyright 11279377Simp * notice, this list of conditions and the following disclaimer in the 12279377Simp * documentation and/or other materials provided with the distribution. 13279377Simp * 3. The name of the author may not be used to endorse or promote products 14279377Simp * derived from this software without specific prior written permission. 15279377Simp * 16279377Simp * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17279377Simp * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18279377Simp * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19279377Simp * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20279377Simp * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21279377Simp * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22279377Simp * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23279377Simp * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24279377Simp * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25279377Simp * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26279377Simp */ 27279377Simp#ifndef EVENT2_BUFFEREVENT_SSL_H_INCLUDED_ 28279377Simp#define EVENT2_BUFFEREVENT_SSL_H_INCLUDED_ 29279377Simp 30279377Simp/** @file event2/bufferevent_ssl.h 31279377Simp 32279377Simp OpenSSL support for bufferevents. 33279377Simp */ 34279377Simp#include <event2/visibility.h> 35279377Simp#include <event2/event-config.h> 36279377Simp#include <event2/bufferevent.h> 37279377Simp#include <event2/util.h> 38279377Simp 39279377Simp#ifdef __cplusplus 40279377Simpextern "C" { 41279377Simp#endif 42279377Simp 43279377Simp/* This is what openssl's SSL objects are underneath. */ 44279377Simpstruct ssl_st; 45279377Simp 46279377Simp/** 47279377Simp The state of an SSL object to be used when creating a new 48279377Simp SSL bufferevent. 49279377Simp */ 50279377Simpenum bufferevent_ssl_state { 51279377Simp BUFFEREVENT_SSL_OPEN = 0, 52279377Simp BUFFEREVENT_SSL_CONNECTING = 1, 53279377Simp BUFFEREVENT_SSL_ACCEPTING = 2 54279377Simp}; 55279377Simp 56279377Simp#if defined(EVENT__HAVE_OPENSSL) || defined(EVENT_IN_DOXYGEN_) 57279377Simp/** 58279377Simp Create a new SSL bufferevent to send its data over another bufferevent. 59295436Sandrew 60295436Sandrew @param base An event_base to use to detect reading and writing. It 61279377Simp must also be the base for the underlying bufferevent. 62279377Simp @param underlying A socket to use for this SSL 63279377Simp @param ssl A SSL* object from openssl. 64279377Simp @param state The current state of the SSL connection 65279377Simp @param options One or more bufferevent_options 66295436Sandrew @return A new bufferevent on success, or NULL on failure 67295436Sandrew*/ 68295436SandrewEVENT2_EXPORT_SYMBOL 69295436Sandrewstruct bufferevent * 70295436Sandrewbufferevent_openssl_filter_new(struct event_base *base, 71295436Sandrew struct bufferevent *underlying, 72295436Sandrew struct ssl_st *ssl, 73295436Sandrew enum bufferevent_ssl_state state, 74295436Sandrew int options); 75295436Sandrew 76295436Sandrew/** 77295436Sandrew Create a new SSL bufferevent to send its data over an SSL * on a socket. 78295436Sandrew 79295436Sandrew @param base An event_base to use to detect reading and writing 80295436Sandrew @param fd A socket to use for this SSL 81279377Simp @param ssl A SSL* object from openssl. 82279377Simp @param state The current state of the SSL connection 83279377Simp @param options One or more bufferevent_options 84279377Simp @return A new bufferevent on success, or NULL on failure. 85279377Simp*/ 86295436SandrewEVENT2_EXPORT_SYMBOL 87295436Sandrewstruct bufferevent * 88279377Simpbufferevent_openssl_socket_new(struct event_base *base, 89279377Simp evutil_socket_t fd, 90279377Simp struct ssl_st *ssl, 91279377Simp enum bufferevent_ssl_state state, 92279377Simp int options); 93295436Sandrew 94279377Simp/** Control how to report dirty SSL shutdowns. 95279377Simp 96279377Simp If the peer (or the network, or an attacker) closes the TCP 97279377Simp connection before closing the SSL channel, and the protocol is SSL >= v3, 98279377Simp this is a "dirty" shutdown. If allow_dirty_shutdown is 0 (default), 99279377Simp this is reported as BEV_EVENT_ERROR. 100279377Simp 101279377Simp If instead allow_dirty_shutdown=1, a dirty shutdown is reported as 102279377Simp BEV_EVENT_EOF. 103279377Simp 104279377Simp (Note that if the protocol is < SSLv3, you will always receive 105279377Simp BEV_EVENT_EOF, since SSL 2 and earlier cannot distinguish a secure 106279377Simp connection close from a dirty one. This is one reason (among many) 107279377Simp not to use SSL 2.) 108279377Simp*/ 109279377Simp 110279377SimpEVENT2_EXPORT_SYMBOL 111279377Simpint bufferevent_openssl_get_allow_dirty_shutdown(struct bufferevent *bev); 112279377SimpEVENT2_EXPORT_SYMBOL 113279377Simpvoid bufferevent_openssl_set_allow_dirty_shutdown(struct bufferevent *bev, 114279377Simp int allow_dirty_shutdown); 115279377Simp 116279377Simp/** Return the underlying openssl SSL * object for an SSL bufferevent. */ 117279377SimpEVENT2_EXPORT_SYMBOL 118279377Simpstruct ssl_st * 119279377Simpbufferevent_openssl_get_ssl(struct bufferevent *bufev); 120279377Simp 121279377Simp/** Tells a bufferevent to begin SSL renegotiation. */ 122279377SimpEVENT2_EXPORT_SYMBOL 123279377Simpint bufferevent_ssl_renegotiate(struct bufferevent *bev); 124279377Simp 125279377Simp/** Return the most recent OpenSSL error reported on an SSL bufferevent. */ 126279377SimpEVENT2_EXPORT_SYMBOL 127279377Simpunsigned long bufferevent_get_openssl_error(struct bufferevent *bev); 128279377Simp 129279377Simp#endif 130279377Simp 131279377Simp#ifdef __cplusplus 132279377Simp} 133279377Simp#endif 134279377Simp 135279377Simp#endif /* EVENT2_BUFFEREVENT_SSL_H_INCLUDED_ */ 136279377Simp