From bed6069126e89ffb93d1298db322577383495227 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Mon, 20 Feb 2017 13:09:15 +0000 Subject: document tls_config_error(3) RETURN VALUES, improve what is said about tls_error(3), and warn about some traps; OK jmc@ --- src/lib/libtls/man/tls_init.3 | 29 +++++++++++++++++++++++++++-- src/lib/libtls/man/tls_read.3 | 36 ++++++++++++++++++++++++++++++++---- 2 files changed, 59 insertions(+), 6 deletions(-) (limited to 'src/lib') diff --git a/src/lib/libtls/man/tls_init.3 b/src/lib/libtls/man/tls_init.3 index 36d2e29084..b17bb814fe 100644 --- a/src/lib/libtls/man/tls_init.3 +++ b/src/lib/libtls/man/tls_init.3 @@ -1,7 +1,8 @@ -.\" $OpenBSD: tls_init.3,v 1.3 2017/01/28 00:59:36 schwarze Exp $ +.\" $OpenBSD: tls_init.3,v 1.4 2017/02/20 13:09:15 schwarze Exp $ .\" .\" Copyright (c) 2014 Ted Unangst .\" Copyright (c) 2016 Joel Sing +.\" Copyright (c) 2017 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -15,7 +16,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: January 28 2017 $ +.Dd $Mdocdate: February 20 2017 $ .Dt TLS_INIT 3 .Os .Sh NAME @@ -107,6 +108,15 @@ returns 0 on success or -1 on error. returns .Dv NULL on error or an out of memory condition. +.Pp +.Fn tls_config_error +returns +.Dv NULL +if no error occured with +.Fa config +at all, or if memory allocation failed while trying to assemble the +string describing the most recent error related to +.Fa config . .Sh SEE ALSO .Xr tls_accept_socket 3 , .Xr tls_client 3 , @@ -142,3 +152,18 @@ appeared in .Pp Many others contributed to various parts of the library; see the individual manual pages for more information. +.Sh CAVEATS +The function +.Fn tls_config_error +returns an internal pointer. +It must not be freed by the application, or a double free error +will occur. +The pointer will become invalid when the next error occurs with +.Fa config . +Consequently, if the application may need the message at a later +time, it has to copy the string before calling the next +.Sy libtls +function involving +.Fa config , +or a segmentation fault or read access to unintended data is the +likely result. diff --git a/src/lib/libtls/man/tls_read.3 b/src/lib/libtls/man/tls_read.3 index e990361017..a7faebaea7 100644 --- a/src/lib/libtls/man/tls_read.3 +++ b/src/lib/libtls/man/tls_read.3 @@ -1,9 +1,10 @@ -.\" $OpenBSD: tls_read.3,v 1.3 2017/01/28 00:59:36 schwarze Exp $ +.\" $OpenBSD: tls_read.3,v 1.4 2017/02/20 13:09:15 schwarze Exp $ .\" .\" Copyright (c) 2014, 2015 Ted Unangst .\" Copyright (c) 2015 Doug Hogan .\" Copyright (c) 2015 Joel Sing .\" Copyright (c) 2015 Bob Beck +.\" Copyright (c) 2017 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -17,7 +18,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: January 28 2017 $ +.Dd $Mdocdate: February 20 2017 $ .Dt TLS_READ 3 .Os .Sh NAME @@ -106,8 +107,20 @@ return 0 on success or -1 on error. .Fn tls_error returns .Dv NULL -if no error occurred or the first place, or if memory allocation -failed while trying to assemble the string describing the error. +if no error occurred with +.Fa ctx +during or since the last call to +.Fn tls_handshake , +.Fn tls_read , +.Fn tls_write , +.Fn tls_close , +or +.Fn tls_reset +involving +.Fa ctx , +or if memory allocation failed while trying to assemble the string +describing the most recent error related to +.Fa ctx . .Pp The .Fn tls_read , @@ -215,3 +228,18 @@ appeared in .An Joel Sing Aq Mt jsing@openbsd.org with contributions from .An Bob Beck Aq Mt beck@openbsd.org +.Sh CAVEATS +The function +.Fn tls_error +returns an internal pointer. +It must not be freed by the application, or a double free error +will occur. +The pointer will become invalid when the next error occurs with +.Fa ctx . +Consequently, if the application may need the message at a later +time, it has to copy the string before calling the next +.Sy libtls +function involving +.Fa ctx , +or a segmentation fault or read access to unintended data is the +likely result. -- cgit v1.2.3-55-g6feb