1.\" $OpenBSD: tls_conn_version.3,v 1.10 2019/11/02 13:43:14 jsing 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: November 2 2019 $ 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_hash , 34.Nm tls_peer_cert_notbefore , 35.Nm tls_peer_cert_notafter 36.Nd inspect an established TLS connection 37.Sh SYNOPSIS 38.In tls.h 39.Ft const char * 40.Fn tls_conn_version "struct tls *ctx" 41.Ft const char * 42.Fn tls_conn_cipher "struct tls *ctx" 43.Ft int 44.Fn tls_conn_cipher_strength "struct tls *ctx" 45.Ft const char * 46.Fn tls_conn_alpn_selected "struct tls *ctx" 47.Ft const char * 48.Fn tls_conn_servername "struct tls *ctx" 49.Ft int 50.Fn tls_conn_session_resumed "struct tls *ctx" 51.Ft int 52.Fn tls_peer_cert_provided "struct tls *ctx" 53.Ft int 54.Fo tls_peer_cert_contains_name 55.Fa "struct tls *ctx" 56.Fa "const char *name" 57.Fc 58.Ft const uint8_t * 59.Fo tls_peer_cert_chain_pem 60.Fa "struct tls *ctx" 61.Fa "size_t *size" 62.Fc 63.Ft const char * 64.Fn tls_peer_cert_issuer "struct tls *ctx" 65.Ft const char * 66.Fn tls_peer_cert_subject "struct tls *ctx" 67.Ft const char * 68.Fn tls_peer_cert_hash "struct tls *ctx" 69.Ft time_t 70.Fn tls_peer_cert_notbefore "struct tls *ctx" 71.Ft time_t 72.Fn tls_peer_cert_notafter "struct tls *ctx" 73.Sh DESCRIPTION 74These functions return information about a TLS connection and will only 75succeed after the handshake is complete (the connection information applies 76to both clients and servers, unless noted otherwise): 77.Pp 78.Fn tls_conn_version 79returns a string corresponding to a TLS version negotiated with the peer 80connected to 81.Ar ctx . 82.Pp 83.Fn tls_conn_cipher 84returns a string corresponding to the cipher suite negotiated with the peer 85connected to 86.Ar ctx . 87.Pp 88.Fn tls_conn_cipher_strength 89returns the strength in bits for the symmetric cipher that is being 90used with the peer connected to 91.Ar ctx . 92.Pp 93.Fn tls_conn_alpn_selected 94returns a string that specifies the ALPN protocol selected for use with the peer 95connected to 96.Ar ctx . 97If no protocol was selected then NULL is returned. 98.Pp 99.Fn tls_conn_servername 100returns a string corresponding to the servername that the client connected to 101.Ar ctx 102requested by sending a TLS Server Name Indication extension (server only). 103.Pp 104.Fn tls_conn_session_resumed 105indicates whether a TLS session has been resumed during the handshake with 106the server connected to 107.Ar ctx 108(client only). 109.Pp 110.Fn tls_peer_cert_provided 111checks if the peer of 112.Ar ctx 113has provided a certificate. 114.Pp 115.Fn tls_peer_cert_contains_name 116checks if the peer of a TLS 117.Ar ctx 118has provided a certificate that contains a 119SAN or CN that matches 120.Ar name . 121.Pp 122.Fn tls_peer_cert_chain_pem 123returns a pointer to memory containing a PEM-encoded certificate chain for the 124peer certificate from 125.Ar ctx . 126.Pp 127.Fn tls_peer_cert_subject 128returns a string 129corresponding to the subject of the peer certificate from 130.Ar ctx . 131.Pp 132.Fn tls_peer_cert_issuer 133returns a string 134corresponding to the issuer of the peer certificate from 135.Ar ctx . 136.Pp 137.Fn tls_peer_cert_hash 138returns a string 139corresponding to a hash of the raw peer certificate from 140.Ar ctx 141prefixed by a hash name followed by a colon. 142The hash currently used is SHA256, though this 143could change in the future. 144The hash string for a certificate in file 145.Ar mycert.crt 146can be generated using the commands: 147.Bd -literal -offset indent 148h=$(openssl x509 -outform der -in mycert.crt | sha256) 149printf "SHA256:${h}\\n" 150.Ed 151.Pp 152.Fn tls_peer_cert_notbefore 153returns the time corresponding to the start of the validity period of 154the peer certificate from 155.Ar ctx . 156.Pp 157.Fn tls_peer_cert_notafter 158returns the time corresponding to the end of the validity period of 159the peer certificate from 160.Ar ctx . 161.Sh RETURN VALUES 162The 163.Fn tls_conn_session_resumed 164function returns 1 if a TLS session was resumed or 0 if it was not. 165.Pp 166The 167.Fn tls_peer_cert_provided 168and 169.Fn tls_peer_cert_contains_name 170functions return 1 if the check succeeds or 0 if it does not. 171.Pp 172.Fn tls_peer_cert_notbefore 173and 174.Fn tls_peer_cert_notafter 175return a time in epoch-seconds on success or -1 on error. 176.Pp 177The functions that return a pointer return 178.Dv NULL 179on error or an out of memory condition. 180.Sh SEE ALSO 181.Xr tls_configure 3 , 182.Xr tls_handshake 3 , 183.Xr tls_init 3 , 184.Xr tls_ocsp_process_response 3 185.Sh HISTORY 186.Fn tls_conn_version , 187.Fn tls_conn_cipher , 188.Fn tls_peer_cert_provided , 189.Fn tls_peer_cert_contains_name , 190.Fn tls_peer_cert_issuer , 191.Fn tls_peer_cert_subject , 192.Fn tls_peer_cert_hash , 193.Fn tls_peer_cert_notbefore , 194and 195.Fn tls_peer_cert_notafter 196appeared in 197.Ox 5.9 . 198.Pp 199.Fn tls_conn_servername 200and 201.Fn tls_conn_alpn_selected 202appeared in 203.Ox 6.1 . 204.Pp 205.Fn tls_conn_session_resumed 206appeared in 207.Ox 6.3 . 208.Pp 209.Fn tls_conn_cipher_strength 210appeared in 211.Ox 6.7 . 212.Sh AUTHORS 213.An Bob Beck Aq Mt beck@openbsd.org 214.An Joel Sing Aq Mt jsing@openbsd.org 215