/*
- * Copyright (c) 2009-2010 Niels Provos and Nick Mathewson
+ * Copyright (c) 2009-2012 Niels Provos and Nick Mathewson
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
#ifndef _EVENT2_BUFFEREVENT_SSL_H_
#define _EVENT2_BUFFEREVENT_SSL_H_
-/** @file bufferevent_ssl.h
+/** @file event2/bufferevent_ssl.h
OpenSSL support for bufferevents.
*/
extern "C" {
#endif
+/* This is what openssl's SSL objects are underneath. */
struct ssl_st;
+/**
+ The state of an SSL object to be used when creating a new
+ SSL bufferevent.
+ */
enum bufferevent_ssl_state {
BUFFEREVENT_SSL_OPEN = 0,
BUFFEREVENT_SSL_CONNECTING = 1,
BUFFEREVENT_SSL_ACCEPTING = 2
};
-#ifdef _EVENT_HAVE_OPENSSL
+#if defined(_EVENT_HAVE_OPENSSL) || defined(_EVENT_IN_DOXYGEN)
+/**
+ Create a new SSL bufferevent to send its data over another bufferevent.
+
+ @param base An event_base to use to detect reading and writing. It
+ must also be the base for the underlying bufferevent.
+ @param underlying A socket to use for this SSL
+ @param ssl A SSL* object from openssl.
+ @param state The current state of the SSL connection
+ @param options One or more bufferevent_options
+ @return A new bufferevent on success, or NULL on failure
+*/
struct bufferevent *
bufferevent_openssl_filter_new(struct event_base *base,
struct bufferevent *underlying,
enum bufferevent_ssl_state state,
int options);
+/**
+ Create a new SSL bufferevent to send its data over an SSL * on a socket.
+
+ @param base An event_base to use to detect reading and writing
+ @param fd A socket to use for this SSL
+ @param ssl A SSL* object from openssl.
+ @param state The current state of the SSL connection
+ @param options One or more bufferevent_options
+ @return A new bufferevent on success, or NULL on failure.
+*/
struct bufferevent *
bufferevent_openssl_socket_new(struct event_base *base,
evutil_socket_t fd,
enum bufferevent_ssl_state state,
int options);
+/** Return the underlying openssl SSL * object for an SSL bufferevent. */
struct ssl_st *
bufferevent_openssl_get_ssl(struct bufferevent *bufev);
+/** Tells a bufferevent to begin SSL renegotiation. */
int bufferevent_ssl_renegotiate(struct bufferevent *bev);
+/** Return the most recent OpenSSL error reported on an SSL bufferevent. */
unsigned long bufferevent_get_openssl_error(struct bufferevent *bev);
#endif