From 7861e7da79ff45f2ba53802840b5e46511f3b002 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sat, 10 Dec 2016 13:54:32 +0000 Subject: New manual pages SSL_get_certificate(3), SSL_get_state(3), and SSL_num_renegotiations(3) written from scratch. These functions are listed in ssl(3) and , so they are clearly public. --- src/lib/libssl/man/Makefile | 5 +- src/lib/libssl/man/SSL_get_certificate.3 | 61 ++++++++++++ src/lib/libssl/man/SSL_get_state.3 | 146 ++++++++++++++++++++++++++++ src/lib/libssl/man/SSL_num_renegotiations.3 | 71 ++++++++++++++ src/lib/libssl/man/SSL_renegotiate.3 | 7 +- 5 files changed, 286 insertions(+), 4 deletions(-) create mode 100644 src/lib/libssl/man/SSL_get_certificate.3 create mode 100644 src/lib/libssl/man/SSL_get_state.3 create mode 100644 src/lib/libssl/man/SSL_num_renegotiations.3 diff --git a/src/lib/libssl/man/Makefile b/src/lib/libssl/man/Makefile index f58f568de7..d1d7bf3cc6 100644 --- a/src/lib/libssl/man/Makefile +++ b/src/lib/libssl/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.50 2016/12/07 20:11:55 schwarze Exp $ +# $OpenBSD: Makefile,v 1.51 2016/12/10 13:54:32 schwarze Exp $ .include @@ -60,6 +60,7 @@ MAN = BIO_f_ssl.3 \ SSL_dup_CA_list.3 \ SSL_free.3 \ SSL_get_SSL_CTX.3 \ + SSL_get_certificate.3 \ SSL_get_ciphers.3 \ SSL_get_client_CA_list.3 \ SSL_get_current_cipher.3 \ @@ -72,11 +73,13 @@ MAN = BIO_f_ssl.3 \ SSL_get_peer_certificate.3 \ SSL_get_rbio.3 \ SSL_get_session.3 \ + SSL_get_state.3 \ SSL_get_verify_result.3 \ SSL_get_version.3 \ SSL_library_init.3 \ SSL_load_client_CA_file.3 \ SSL_new.3 \ + SSL_num_renegotiations.3 \ SSL_pending.3 \ SSL_read.3 \ SSL_renegotiate.3 \ diff --git a/src/lib/libssl/man/SSL_get_certificate.3 b/src/lib/libssl/man/SSL_get_certificate.3 new file mode 100644 index 0000000000..35650c75b1 --- /dev/null +++ b/src/lib/libssl/man/SSL_get_certificate.3 @@ -0,0 +1,61 @@ +.\" $OpenBSD: SSL_get_certificate.3,v 1.1 2016/12/10 13:54:32 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: December 10 2016 $ +.Dt SSL_GET_CERTIFICATE 3 +.Os +.Sh NAME +.Nm SSL_get_certificate , +.Nm SSL_get_privatekey +.Nd get SSL certificate and private key +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft X509 * +.Fo SSL_get_certificate +.Fa "const SSL *ssl" +.Fc +.Ft EVP_PKEY * +.Fo SSL_get_privatekey +.Fa "SSL *ssl" +.Fc +.Sh DESCRIPTION +These functions retrieve certificate and key data from an +.Vt SSL +object. +They return internal pointers that must not be freed by the application +program. +.Sh RETURN VALUES +.Fn SSL_get_certificate +returns the active X.509 certificate currently used by +.Fa ssl +or +.Dv NULL +if none is active. +.Pp +.Fn SSL_get_privatekey +returns the active private key currently used by +.Fa ssl +or +.Dv NULL +if none is active. +.Sh SEE ALSO +.Xr SSL_check_private_key 3 , +.Xr SSL_use_certificate 3 +.Sh HISTORY +.Fn SSL_get_certificate +and +.Fn SSL_get_privatekey +are available in all versions of OpenSSL. diff --git a/src/lib/libssl/man/SSL_get_state.3 b/src/lib/libssl/man/SSL_get_state.3 new file mode 100644 index 0000000000..d835b52291 --- /dev/null +++ b/src/lib/libssl/man/SSL_get_state.3 @@ -0,0 +1,146 @@ +.\" $OpenBSD: SSL_get_state.3,v 1.1 2016/12/10 13:54:32 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: December 10 2016 $ +.Dt SSL_GET_STATE 3 +.Os +.Sh NAME +.Nm SSL_get_state , +.Nm SSL_state , +.Nm SSL_in_accept_init , +.Nm SSL_in_before , +.Nm SSL_in_connect_init , +.Nm SSL_in_init , +.Nm SSL_is_init_finished +.Nd inspect the state of the SSL state machine +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fo SSL_get_state +.Fa "const SSL *ssl" +.Fc +.Ft int +.Fo SSL_state +.Fa "const SSL *ssl" +.Fc +.Ft int +.Fo SSL_in_accept_init +.Fa "const SSL *ssl" +.Fc +.Ft int +.Fo SSL_in_before +.Fa "const SSL *ssl" +.Fc +.Ft int +.Fo SSL_in_connect_init +.Fa "const SSL *ssl" +.Fc +.Ft int +.Fo SSL_in_init +.Fa "const SSL *ssl" +.Fc +.Ft int +.Fo SSL_is_init_finished +.Fa "const SSL *ssl" +.Fc +.Sh DESCRIPTION +.Fn SSL_get_state +returns an encoded representation of the current state of the SSL +state machine. +.Fn SSL_state +is a deprecated alias for +.Fn SSL_get_state . +.Pp +The following bits may be set: +.Bl -tag -width Ds +.It Dv SSL_ST_ACCEPT +This bit is set by +.Xr SSL_accept 3 +and by +.Xr SSL_set_accept_state 3 . +It indicates that +.Fa ssl +is set up for server mode and no client initiated the TLS handshake yet. +The function +.Fn SSL_in_accept_init +returns non-zero if this bit is set or 0 otherwise. +.It Dv SSL_ST_BEFORE +This bit is set by the +.Xr SSL_accept 3 , +.Xr SSL_connect 3 , +.Xr SSL_set_accept_state 3 , +and +.Xr SSL_set_connect_state 3 +functions. +It indicates that the TLS handshake was not initiated yet. +The function +.Fn SSL_in_before +returns non-zero if this bit is set or 0 otherwise. +.It Dv SSL_ST_CONNECT +This bit is set by +.Xr SSL_connect 3 +and by +.Xr SSL_set_connect_state 3 . +It indicates that +.Fa ssl +is set up for client mode and no TLS handshake was initiated yet. +The function +.Fn SSL_in_connect_init +returns non-zero if this bit is set or 0 otherwise. +.El +.Pp +The following masks can be used: +.Bl -tag -width Ds +.It Dv SSL_ST_INIT +Set if +.Dv SSL_ST_ACCEPT +or +.Dv SSL_ST_CONNECT +is set. +The function +.Fn SSL_in_init +returns a non-zero value if one of these is set or 0 otherwise. +.It Dv SSL_ST_MASK +This mask includes all bits except +.Dv SSL_ST_ACCEPT , +.Dv SSL_ST_BEFORE , +and +.Dv SSL_ST_CONNECT . +.It Dv SSL_ST_OK +The state is set to this value when a connection is established. +The function +.Fn SSL_is_init_finished +returns a non-zero value if the state equals this constant, or 0 otherwise. +.It Dv SSL_ST_RENEGOTIATE +The program is about to renegotiate, for example when entering +.Xr SSL_read 3 +or +.Xr SSL_write 3 +right after +.Xr SSL_renegotiate 3 +was called. +.El +.Pp +The meaning of other bits is protocol-dependent. +Application programs usually do not need to inspect any of those +other bits. +.Pp +All these functions may be implemented as macros. +.Sh SEE ALSO +.Xr SSL_renegotiate 3 , +.Xr SSL_set_connect_state 3 +.Sh HISTORY +These functions are available in all versions of OpenSSL. diff --git a/src/lib/libssl/man/SSL_num_renegotiations.3 b/src/lib/libssl/man/SSL_num_renegotiations.3 new file mode 100644 index 0000000000..d1986a674c --- /dev/null +++ b/src/lib/libssl/man/SSL_num_renegotiations.3 @@ -0,0 +1,71 @@ +.\" $OpenBSD: SSL_num_renegotiations.3,v 1.1 2016/12/10 13:54:32 schwarze Exp $ +.\" +.\" Copyright (c) 2016 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 +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: December 10 2016 $ +.Dt SSL_NUM_RENEGOTIATIONS 3 +.Os +.Sh NAME +.Nm SSL_num_renegotiations , +.Nm SSL_clear_num_renegotiations , +.Nm SSL_total_renegotiations +.Nd renegotiation counters +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft long +.Fo SSL_num_renegotiations +.Fa "SSL *ssl" +.Fc +.Ft long +.Fo SSL_clear_num_renegotiations +.Fa "SSL *ssl" +.Fc +.Ft long +.Fo SSL_total_renegotiations +.Fa "SSL *ssl" +.Fc +.Sh DESCRIPTION +.Fn SSL_num_renegotiations +reports the number of renegotiations initiated in +.Fa ssl +since +.Xr SSL_new 3 , +.Xr SSL_clear 3 , +or +.Xr SSL_clear_num_renegotiations 3 +was last called on that object. +.Pp +.Fn SSL_clear_num_renegotiations +does the same and additionally resets the renegotiation counter to 0. +.Pp +.Fn SSL_total_renegotiations +reports the number of renegotiations initiated in +.Fa ssl +since +.Xr SSL_new 3 +or +.Xr SSL_clear 3 +was last called on that object. +.Pp +These functions are implemented as macros. +.Sh RETURN VALUES +All these functions return a number of renegotiations. +.Sh SEE ALSO +.Xr BIO_set_ssl_renegotiate_bytes 3 , +.Xr SSL_read 3 , +.Xr SSL_renegotiate 3 , +.Xr SSL_write 3 +.Sh HISTORY +These functions are available in all versions of OpenSSL. diff --git a/src/lib/libssl/man/SSL_renegotiate.3 b/src/lib/libssl/man/SSL_renegotiate.3 index c07a1e2c2a..f5b59bae95 100644 --- a/src/lib/libssl/man/SSL_renegotiate.3 +++ b/src/lib/libssl/man/SSL_renegotiate.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: SSL_renegotiate.3,v 1.1 2016/12/07 20:11:55 schwarze Exp $ +.\" $OpenBSD: SSL_renegotiate.3,v 1.2 2016/12/10 13:54:32 schwarze Exp $ .\" .\" Copyright (c) 2016 Ingo Schwarze .\" @@ -14,7 +14,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: December 7 2016 $ +.Dd $Mdocdate: December 10 2016 $ .Dt SSL_RENEGOTIATE 3 .Os .Sh NAME @@ -38,7 +38,7 @@ and .Xr SSL_write 3 whenever the renegotiation byte count set by .Xr BIO_set_ssl_renegotiate_bytes 3 -or the timeout set by +or the timeout set by .Xr BIO_set_ssl_renegotiate_timeout 3 are exceeded. .Sh RETURN VALUES @@ -49,6 +49,7 @@ is set, in which case it may return 0. The API provides no function to set that flag; it can only be set by manipulating internal data structures. .Sh SEE ALSO +.Xr SSL_num_renegotiations 3 , .Xr SSL_read 3 , .Xr SSL_write 3 .Sh HISTORY -- cgit v1.2.3-55-g6feb