1.\" $OpenBSD: tls_conn_version.3,v 1.11 2024/12/10 08:42:12 tb Exp $ 2.\" 3.\" Copyright (c) 2015 Bob Beck <beck@openbsd.org> 4.\" Copyright (c) 2016, 2018 Joel Sing <jsing@openbsd.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: December 10 2024 $ 19.Dt TLS_CONN_VERSION 3 20.Os 21.Sh NAME 22.Nm tls_conn_version , 23.Nm tls_conn_cipher , 24.Nm tls_conn_cipher_strength , 25.Nm tls_conn_alpn_selected , 26.Nm tls_conn_servername , 27.Nm tls_conn_session_resumed , 28.Nm tls_peer_cert_provided , 29.Nm tls_peer_cert_contains_name , 30.Nm tls_peer_cert_chain_pem , 31.Nm tls_peer_cert_issuer , 32.Nm tls_peer_cert_subject , 33.Nm tls_peer_cert_common_name , 34.Nm tls_peer_cert_hash , 35.Nm tls_peer_cert_notbefore , 36.Nm tls_peer_cert_notafter 37.Nd inspect an established TLS connection 38.Sh SYNOPSIS 39.In tls.h 40.Ft const char * 41.Fn tls_conn_version "struct tls *ctx" 42.Ft const char * 43.Fn tls_conn_cipher "struct tls *ctx" 44.Ft int 45.Fn tls_conn_cipher_strength "struct tls *ctx" 46.Ft const char * 47.Fn tls_conn_alpn_selected "struct tls *ctx" 48.Ft const char * 49.Fn tls_conn_servername "struct tls *ctx" 50.Ft int 51.Fn tls_conn_session_resumed "struct tls *ctx" 52.Ft int 53.Fn tls_peer_cert_provided "struct tls *ctx" 54.Ft int 55.Fo tls_peer_cert_contains_name 56.Fa "struct tls *ctx" 57.Fa "const char *name" 58.Fc 59.Ft const uint8_t * 60.Fo tls_peer_cert_chain_pem 61.Fa "struct tls *ctx" 62.Fa "size_t *size" 63.Fc 64.Ft const char * 65.Fn tls_peer_cert_issuer "struct tls *ctx" 66.Ft const char * 67.Fn tls_peer_cert_subject "struct tls *ctx" 68.Ft const char * 69.Fn tls_peer_cert_common_name "struct tls *ctx" 70.Ft const char * 71.Fn tls_peer_cert_hash "struct tls *ctx" 72.Ft time_t 73.Fn tls_peer_cert_notbefore "struct tls *ctx" 74.Ft time_t 75.Fn tls_peer_cert_notafter "struct tls *ctx" 76.Sh DESCRIPTION 77These functions return information about a TLS connection and will only 78succeed after the handshake is complete (the connection information applies 79to both clients and servers, unless noted otherwise): 80.Pp 81.Fn tls_conn_version 82returns a string corresponding to a TLS version negotiated with the peer 83connected to 84.Ar ctx . 85.Pp 86.Fn tls_conn_cipher 87returns a string corresponding to the cipher suite negotiated with the peer 88connected to 89.Ar ctx . 90.Pp 91.Fn tls_conn_cipher_strength 92returns the strength in bits for the symmetric cipher that is being 93used with the peer connected to 94.Ar ctx . 95.Pp 96.Fn tls_conn_alpn_selected 97returns a string that specifies the ALPN protocol selected for use with the peer 98connected to 99.Ar ctx . 100If no protocol was selected then NULL is returned. 101.Pp 102.Fn tls_conn_servername 103returns a string corresponding to the servername that the client connected to 104.Ar ctx 105requested by sending a TLS Server Name Indication extension (server only). 106.Pp 107.Fn tls_conn_session_resumed 108indicates whether a TLS session has been resumed during the handshake with 109the server connected to 110.Ar ctx 111(client only). 112.Pp 113.Fn tls_peer_cert_provided 114checks if the peer of 115.Ar ctx 116has provided a certificate. 117.Pp 118.Fn tls_peer_cert_contains_name 119checks if the peer of a TLS 120.Ar ctx 121has provided a certificate that contains a 122SAN or CN that matches 123.Ar name . 124.Pp 125.Fn tls_peer_cert_chain_pem 126returns a pointer to memory containing a PEM-encoded certificate chain for the 127peer certificate from 128.Ar ctx . 129.Pp 130.Fn tls_peer_cert_subject 131returns a string 132corresponding to the subject of the peer certificate from 133.Ar ctx . 134.Pp 135.Fn tls_peer_cert_issuer 136returns a string 137corresponding to the issuer of the peer certificate from 138.Ar ctx . 139.Fn tls_peer_cert_common_name 140returns a string 141corresponding to the common name of the peer certificate from 142.Ar ctx 143or the empty string if no common name is present. 144.Pp 145.Fn tls_peer_cert_hash 146returns a string 147corresponding to a hash of the raw peer certificate from 148.Ar ctx 149prefixed by a hash name followed by a colon. 150The hash currently used is SHA256, though this 151could change in the future. 152The hash string for a certificate in file 153.Ar mycert.crt 154can be generated using the commands: 155.Bd -literal -offset indent 156h=$(openssl x509 -outform der -in mycert.crt | sha256) 157printf "SHA256:${h}\\n" 158.Ed 159.Pp 160.Fn tls_peer_cert_notbefore 161returns the time corresponding to the start of the validity period of 162the peer certificate from 163.Ar ctx . 164.Pp 165.Fn tls_peer_cert_notafter 166returns the time corresponding to the end of the validity period of 167the peer certificate from 168.Ar ctx . 169.Sh RETURN VALUES 170The 171.Fn tls_conn_session_resumed 172function returns 1 if a TLS session was resumed or 0 if it was not. 173.Pp 174The 175.Fn tls_peer_cert_provided 176and 177.Fn tls_peer_cert_contains_name 178functions return 1 if the check succeeds or 0 if it does not. 179.Pp 180.Fn tls_peer_cert_notbefore 181and 182.Fn tls_peer_cert_notafter 183return a time in epoch-seconds on success or -1 on error. 184.Pp 185The functions that return a pointer return 186.Dv NULL 187on error or an out of memory condition. 188.Sh SEE ALSO 189.Xr tls_configure 3 , 190.Xr tls_handshake 3 , 191.Xr tls_init 3 , 192.Xr tls_ocsp_process_response 3 193.Sh HISTORY 194.Fn tls_conn_version , 195.Fn tls_conn_cipher , 196.Fn tls_peer_cert_provided , 197.Fn tls_peer_cert_contains_name , 198.Fn tls_peer_cert_issuer , 199.Fn tls_peer_cert_subject , 200.Fn tls_peer_cert_hash , 201.Fn tls_peer_cert_notbefore , 202and 203.Fn tls_peer_cert_notafter 204appeared in 205.Ox 5.9 . 206.Pp 207.Fn tls_conn_servername 208and 209.Fn tls_conn_alpn_selected 210appeared in 211.Ox 6.1 . 212.Pp 213.Fn tls_conn_session_resumed 214appeared in 215.Ox 6.3 . 216.Pp 217.Fn tls_conn_cipher_strength 218appeared in 219.Ox 6.7 . 220.Fn tls_peer_cert_common_name 221appeared in 222.Ox 7.7 . 223.Sh AUTHORS 224.An Bob Beck Aq Mt beck@openbsd.org 225.An Joel Sing Aq Mt jsing@openbsd.org 226