1 files changed, 123 insertions, 0 deletions
diff --git a/src/lib/libssl/doc/SSL_CTX_set_mode.3 b/src/lib/libssl/doc/SSL_CTX_set_mode.3
new file mode 100644
index 0000000000..b980d43dbe
--- /dev/null
+++ b/src/lib/libssl/doc/SSL_CTX_set_mode.3
@@ -0,0 +1,123 @@
+.Dd $Mdocdate: October 12 2014 $
+.Dt SSL_CTX_SET_MODE 3
+.Os
+.Sh NAME
+.Nm SSL_CTX_set_mode ,
+.Nm SSL_set_mode ,
+.Nm SSL_CTX_get_mode ,
+.Nm SSL_get_mode
+.Nd manipulate SSL engine mode
+.Sh SYNOPSIS
+.In openssl/ssl.h
+.Ft long
+.Fn SSL_CTX_set_mode "SSL_CTX *ctx" "long mode"
+.Ft long
+.Fn SSL_set_mode "SSL *ssl" "long mode"
+.Ft long
+.Fn SSL_CTX_get_mode "SSL_CTX *ctx"
+.Ft long
+.Fn SSL_get_mode "SSL *ssl"
+.Sh DESCRIPTION
+.Fn SSL_CTX_set_mode
+adds the mode set via bitmask in
+.Fa mode
+to
+.Fa ctx .
+Options already set before are not cleared.
+.Pp
+.Fn SSL_set_mode
+adds the mode set via bitmask in
+.Fa mode
+to
+.Fa ssl .
+Options already set before are not cleared.
+.Pp
+.Fn SSL_CTX_get_mode
+returns the mode set for
+.Fa ctx .
+.Pp
+.Fn SSL_get_mode
+returns the mode set for
+.Fa ssl .
+.Sh NOTES
+The following mode changes are available:
+.Bl -tag -width Ds
+.It Dv SSL_MODE_ENABLE_PARTIAL_WRITE
+Allow
+.Fn SSL_write ... n
+to return
+.Ms r
+with
+.EQ
+0 < r < n
+.EN
+(i.e., report success when just a single record has been written).
+When not set (the default),
+.Xr SSL_write 3
+will only report success once the complete chunk was written.
+Once
+.Xr SSL_write 3
+returns with
+.Ms r ,
+.Ms r
+bytes have been successfully written and the next call to
+.Xr SSL_write 3
+must only send the
+.Ms n \(mi r
+bytes left, imitating the behaviour of
+.Xr write 2 .
+.It Dv SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER
+Make it possible to retry
+.Xr SSL_write 3
+with changed buffer location (the buffer contents must stay the same).
+This is not the default to avoid the misconception that non-blocking
+.Xr SSL_write 3
+behaves like non-blocking
+.Xr write 2 .
+.It Dv SSL_MODE_AUTO_RETRY
+Never bother the application with retries if the transport is blocking.
+If a renegotiation take place during normal operation, a
+.Xr SSL_read 3
+or
+.Xr SSL_write 3
+would return
+with \(mi1 and indicate the need to retry with
+.Dv SSL_ERROR_WANT_READ .
+In a non-blocking environment applications must be prepared to handle
+incomplete read/write operations.
+In a blocking environment, applications are not always prepared to deal with
+read/write operations returning without success report.
+The flag
+.Dv SSL_MODE_AUTO_RETRY
+will cause read/write operations to only return after the handshake and
+successful completion.
+.It Dv SSL_MODE_RELEASE_BUFFERS
+When we no longer need a read buffer or a write buffer for a given
+.Vt SSL ,
+then release the memory we were using to hold it.
+Released memory is either appended to a list of unused RAM chunks on the
+.Vt SSL_CTX ,
+or simply freed if the list of unused chunks would become longer than
+.Va "SSL_CTX->freelist_max_len" ,
+which defaults to 32.
+Using this flag can save around 34k per idle SSL connection.
+This flag has no effect on SSL v2 connections, or on DTLS connections.
+.El
+.Sh RETURN VALUES
+.Fn SSL_CTX_set_mode
+and
+.Fn SSL_set_mode
+return the new mode bitmask after adding
+.Fa mode .
+.Pp
+.Fn SSL_CTX_get_mode
+and
+.Fn SSL_get_mode
+return the current bitmask.
+.Sh SEE ALSO
+.Xr ssl 3 ,
+.Xr SSL_read 3 ,
+.Xr SSL_write 3
+.Sh HISTORY
+.Dv SSL_MODE_AUTO_RETRY
+was added in OpenSSL 0.9.6.

diff --git a/src/lib/libssl/doc/SSL_CTX_set_mode.3 b/src/lib/libssl/doc/SSL_CTX_set_mode.3 new file mode 100644 index 0000000000..b980d43dbe --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_mode.3
@@ -0,0 +1,123 @@
	1	.Dd $Mdocdate: October 12 2014 $
	2	.Dt SSL_CTX_SET_MODE 3
	3	.Os
	4	.Sh NAME
	5	.Nm SSL_CTX_set_mode ,
	6	.Nm SSL_set_mode ,
	7	.Nm SSL_CTX_get_mode ,
	8	.Nm SSL_get_mode
	9	.Nd manipulate SSL engine mode
	10	.Sh SYNOPSIS
	11	.In openssl/ssl.h
	12	.Ft long
	13	.Fn SSL_CTX_set_mode "SSL_CTX *ctx" "long mode"
	14	.Ft long
	15	.Fn SSL_set_mode "SSL *ssl" "long mode"
	16	.Ft long
	17	.Fn SSL_CTX_get_mode "SSL_CTX *ctx"
	18	.Ft long
	19	.Fn SSL_get_mode "SSL *ssl"
	20	.Sh DESCRIPTION
	21	.Fn SSL_CTX_set_mode
	22	adds the mode set via bitmask in
	23	.Fa mode
	24	to
	25	.Fa ctx .
	26	Options already set before are not cleared.
	27	.Pp
	28	.Fn SSL_set_mode
	29	adds the mode set via bitmask in
	30	.Fa mode
	31	to
	32	.Fa ssl .
	33	Options already set before are not cleared.
	34	.Pp
	35	.Fn SSL_CTX_get_mode
	36	returns the mode set for
	37	.Fa ctx .
	38	.Pp
	39	.Fn SSL_get_mode
	40	returns the mode set for
	41	.Fa ssl .
	42	.Sh NOTES
	43	The following mode changes are available:
	44	.Bl -tag -width Ds
	45	.It Dv SSL_MODE_ENABLE_PARTIAL_WRITE
	46	Allow
	47	.Fn SSL_write ... n
	48	to return
	49	.Ms r
	50	with
	51	.EQ
	52	0 < r < n
	53	.EN
	54	(i.e., report success when just a single record has been written).
	55	When not set (the default),
	56	.Xr SSL_write 3
	57	will only report success once the complete chunk was written.
	58	Once
	59	.Xr SSL_write 3
	60	returns with
	61	.Ms r ,
	62	.Ms r
	63	bytes have been successfully written and the next call to
	64	.Xr SSL_write 3
	65	must only send the
	66	.Ms n \(mi r
	67	bytes left, imitating the behaviour of
	68	.Xr write 2 .
	69	.It Dv SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER
	70	Make it possible to retry
	71	.Xr SSL_write 3
	72	with changed buffer location (the buffer contents must stay the same).
	73	This is not the default to avoid the misconception that non-blocking
	74	.Xr SSL_write 3
	75	behaves like non-blocking
	76	.Xr write 2 .
	77	.It Dv SSL_MODE_AUTO_RETRY
	78	Never bother the application with retries if the transport is blocking.
	79	If a renegotiation take place during normal operation, a
	80	.Xr SSL_read 3
	81	or
	82	.Xr SSL_write 3
	83	would return
	84	with \(mi1 and indicate the need to retry with
	85	.Dv SSL_ERROR_WANT_READ .
	86	In a non-blocking environment applications must be prepared to handle
	87	incomplete read/write operations.
	88	In a blocking environment, applications are not always prepared to deal with
	89	read/write operations returning without success report.
	90	The flag
	91	.Dv SSL_MODE_AUTO_RETRY
	92	will cause read/write operations to only return after the handshake and
	93	successful completion.
	94	.It Dv SSL_MODE_RELEASE_BUFFERS
	95	When we no longer need a read buffer or a write buffer for a given
	96	.Vt SSL ,
	97	then release the memory we were using to hold it.
	98	Released memory is either appended to a list of unused RAM chunks on the
	99	.Vt SSL_CTX ,
	100	or simply freed if the list of unused chunks would become longer than
	101	.Va "SSL_CTX->freelist_max_len" ,
	102	which defaults to 32.
	103	Using this flag can save around 34k per idle SSL connection.
	104	This flag has no effect on SSL v2 connections, or on DTLS connections.
	105	.El
	106	.Sh RETURN VALUES
	107	.Fn SSL_CTX_set_mode
	108	and
	109	.Fn SSL_set_mode
	110	return the new mode bitmask after adding
	111	.Fa mode .
	112	.Pp
	113	.Fn SSL_CTX_get_mode
	114	and
	115	.Fn SSL_get_mode
	116	return the current bitmask.
	117	.Sh SEE ALSO
	118	.Xr ssl 3 ,
	119	.Xr SSL_read 3 ,
	120	.Xr SSL_write 3
	121	.Sh HISTORY
	122	.Dv SSL_MODE_AUTO_RETRY
	123	was added in OpenSSL 0.9.6.