diff options
Diffstat (limited to 'man/tls_conn_version.3')
| -rw-r--r-- | man/tls_conn_version.3 | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/man/tls_conn_version.3 b/man/tls_conn_version.3 new file mode 100644 index 0000000..9ab6932 --- /dev/null +++ b/man/tls_conn_version.3 @@ -0,0 +1,214 @@ +.\" $OpenBSD: tls_conn_version.3,v 1.10 2019/11/02 13:43:14 jsing Exp $ +.\" +.\" Copyright (c) 2015 Bob Beck <beck@openbsd.org> +.\" Copyright (c) 2016, 2018 Joel Sing <jsing@openbsd.org> +.\" +.\" 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: November 2 2019 $ +.Dt TLS_CONN_VERSION 3 +.Os +.Sh NAME +.Nm tls_conn_version , +.Nm tls_conn_cipher , +.Nm tls_conn_cipher_strength , +.Nm tls_conn_alpn_selected , +.Nm tls_conn_servername , +.Nm tls_conn_session_resumed , +.Nm tls_peer_cert_provided , +.Nm tls_peer_cert_contains_name , +.Nm tls_peer_cert_chain_pem , +.Nm tls_peer_cert_issuer , +.Nm tls_peer_cert_subject , +.Nm tls_peer_cert_hash , +.Nm tls_peer_cert_notbefore , +.Nm tls_peer_cert_notafter +.Nd inspect an established TLS connection +.Sh SYNOPSIS +.In tls.h +.Ft const char * +.Fn tls_conn_version "struct tls *ctx" +.Ft const char * +.Fn tls_conn_cipher "struct tls *ctx" +.Ft int +.Fn tls_conn_cipher_strength "struct tls *ctx" +.Ft const char * +.Fn tls_conn_alpn_selected "struct tls *ctx" +.Ft const char * +.Fn tls_conn_servername "struct tls *ctx" +.Ft int +.Fn tls_conn_session_resumed "struct tls *ctx" +.Ft int +.Fn tls_peer_cert_provided "struct tls *ctx" +.Ft int +.Fo tls_peer_cert_contains_name +.Fa "struct tls *ctx" +.Fa "const char *name" +.Fc +.Ft const uint8_t * +.Fo tls_peer_cert_chain_pem +.Fa "struct tls *ctx" +.Fa "size_t *size" +.Fc +.Ft const char * +.Fn tls_peer_cert_issuer "struct tls *ctx" +.Ft const char * +.Fn tls_peer_cert_subject "struct tls *ctx" +.Ft const char * +.Fn tls_peer_cert_hash "struct tls *ctx" +.Ft time_t +.Fn tls_peer_cert_notbefore "struct tls *ctx" +.Ft time_t +.Fn tls_peer_cert_notafter "struct tls *ctx" +.Sh DESCRIPTION +These functions return information about a TLS connection and will only +succeed after the handshake is complete (the connection information applies +to both clients and servers, unless noted otherwise): +.Pp +.Fn tls_conn_version +returns a string corresponding to a TLS version negotiated with the peer +connected to +.Ar ctx . +.Pp +.Fn tls_conn_cipher +returns a string corresponding to the cipher suite negotiated with the peer +connected to +.Ar ctx . +.Pp +.Fn tls_conn_cipher_strength +returns the strength in bits for the symmetric cipher that is being +used with the peer connected to +.Ar ctx . +.Pp +.Fn tls_conn_alpn_selected +returns a string that specifies the ALPN protocol selected for use with the peer +connected to +.Ar ctx . +If no protocol was selected then NULL is returned. +.Pp +.Fn tls_conn_servername +returns a string corresponding to the servername that the client connected to +.Ar ctx +requested by sending a TLS Server Name Indication extension (server only). +.Pp +.Fn tls_conn_session_resumed +indicates whether a TLS session has been resumed during the handshake with +the server connected to +.Ar ctx +(client only). +.Pp +.Fn tls_peer_cert_provided +checks if the peer of +.Ar ctx +has provided a certificate. +.Pp +.Fn tls_peer_cert_contains_name +checks if the peer of a TLS +.Ar ctx +has provided a certificate that contains a +SAN or CN that matches +.Ar name . +.Pp +.Fn tls_peer_cert_chain_pem +returns a pointer to memory containing a PEM-encoded certificate chain for the +peer certificate from +.Ar ctx . +.Pp +.Fn tls_peer_cert_subject +returns a string +corresponding to the subject of the peer certificate from +.Ar ctx . +.Pp +.Fn tls_peer_cert_issuer +returns a string +corresponding to the issuer of the peer certificate from +.Ar ctx . +.Pp +.Fn tls_peer_cert_hash +returns a string +corresponding to a hash of the raw peer certificate from +.Ar ctx +prefixed by a hash name followed by a colon. +The hash currently used is SHA256, though this +could change in the future. +The hash string for a certificate in file +.Ar mycert.crt +can be generated using the commands: +.Bd -literal -offset indent +h=$(openssl x509 -outform der -in mycert.crt | sha256) +printf "SHA256:${h}\\n" +.Ed +.Pp +.Fn tls_peer_cert_notbefore +returns the time corresponding to the start of the validity period of +the peer certificate from +.Ar ctx . +.Pp +.Fn tls_peer_cert_notafter +returns the time corresponding to the end of the validity period of +the peer certificate from +.Ar ctx . +.Sh RETURN VALUES +The +.Fn tls_conn_session_resumed +function returns 1 if a TLS session was resumed or 0 if it was not. +.Pp +The +.Fn tls_peer_cert_provided +and +.Fn tls_peer_cert_contains_name +functions return 1 if the check succeeds or 0 if it does not. +.Pp +.Fn tls_peer_cert_notbefore +and +.Fn tls_peer_cert_notafter +return a time in epoch-seconds on success or -1 on error. +.Pp +The functions that return a pointer return +.Dv NULL +on error or an out of memory condition. +.Sh SEE ALSO +.Xr tls_configure 3 , +.Xr tls_handshake 3 , +.Xr tls_init 3 , +.Xr tls_ocsp_process_response 3 +.Sh HISTORY +.Fn tls_conn_version , +.Fn tls_conn_cipher , +.Fn tls_peer_cert_provided , +.Fn tls_peer_cert_contains_name , +.Fn tls_peer_cert_issuer , +.Fn tls_peer_cert_subject , +.Fn tls_peer_cert_hash , +.Fn tls_peer_cert_notbefore , +and +.Fn tls_peer_cert_notafter +appeared in +.Ox 5.9 . +.Pp +.Fn tls_conn_servername +and +.Fn tls_conn_alpn_selected +appeared in +.Ox 6.1 . +.Pp +.Fn tls_conn_session_resumed +appeared in +.Ox 6.3 . +.Pp +.Fn tls_conn_cipher_strength +appeared in +.Ox 6.7 . +.Sh AUTHORS +.An Bob Beck Aq Mt beck@openbsd.org +.An Joel Sing Aq Mt jsing@openbsd.org |