1TLS_CONN_VERSION(3)      BSD Library Functions Manual      TLS_CONN_VERSION(3)
2

NAME

4     tls_conn_version, tls_conn_cipher, tls_conn_cipher_strength,
5     tls_conn_alpn_selected, tls_conn_servername, tls_conn_session_resumed,
6     tls_peer_cert_provided, tls_peer_cert_contains_name,
7     tls_peer_cert_chain_pem, tls_peer_cert_issuer, tls_peer_cert_subject,
8     tls_peer_cert_hash, tls_peer_cert_notbefore, tls_peer_cert_notafter —
9     inspect an established TLS connection
10

SYNOPSIS

12     #include <tls.h>
13
14     const char *
15     tls_conn_version(struct tls *ctx);
16
17     const char *
18     tls_conn_cipher(struct tls *ctx);
19
20     int
21     tls_conn_cipher_strength(struct tls *ctx);
22
23     const char *
24     tls_conn_alpn_selected(struct tls *ctx);
25
26     const char *
27     tls_conn_servername(struct tls *ctx);
28
29     int
30     tls_conn_session_resumed(struct tls *ctx);
31
32     int
33     tls_peer_cert_provided(struct tls *ctx);
34
35     int
36     tls_peer_cert_contains_name(struct tls *ctx, const char *name);
37
38     const uint8_t *
39     tls_peer_cert_chain_pem(struct tls *ctx, size_t *size);
40
41     const char *
42     tls_peer_cert_issuer(struct tls *ctx);
43
44     const char *
45     tls_peer_cert_subject(struct tls *ctx);
46
47     const char *
48     tls_peer_cert_hash(struct tls *ctx);
49
50     time_t
51     tls_peer_cert_notbefore(struct tls *ctx);
52
53     time_t
54     tls_peer_cert_notafter(struct tls *ctx);
55

DESCRIPTION

57     These functions return information about a TLS connection and will only
58     succeed after the handshake is complete (the connection information
59     applies to both clients and servers, unless noted otherwise):
60
61     tls_conn_version() returns a string corresponding to a TLS version nego‐
62     tiated with the peer connected to ctx.
63
64     tls_conn_cipher() returns a string corresponding to the cipher suite
65     negotiated with the peer connected to ctx.
66
67     tls_conn_cipher_strength() returns the strength in bits for the symmetric
68     cipher that is being used with the peer connected to ctx.
69
70     tls_conn_alpn_selected() returns a string that specifies the ALPN proto‐
71     col selected for use with the peer connected to ctx.  If no protocol was
72     selected then NULL is returned.
73
74     tls_conn_servername() returns a string corresponding to the servername
75     that the client connected to ctx requested by sending a TLS Server Name
76     Indication extension (server only).
77
78     tls_conn_session_resumed() indicates whether a TLS session has been
79     resumed during the handshake with the server connected to ctx (client
80     only).
81
82     tls_peer_cert_provided() checks if the peer of ctx has provided a cer‐
83     tificate.
84
85     tls_peer_cert_contains_name() checks if the peer of a TLS ctx has pro‐
86     vided a certificate that contains a SAN or CN that matches name.
87
88     tls_peer_cert_chain_pem() returns a pointer to memory containing a PEM-
89     encoded certificate chain for the peer certificate from ctx.
90
91     tls_peer_cert_subject() returns a string corresponding to the subject of
92     the peer certificate from ctx.
93
94     tls_peer_cert_issuer() returns a string corresponding to the issuer of
95     the peer certificate from ctx.
96
97     tls_peer_cert_hash() returns a string corresponding to a hash of the raw
98     peer certificate from ctx prefixed by a hash name followed by a colon.
99     The hash currently used is SHA256, though this could change in the
100     future.  The hash string for a certificate in file mycert.crt can be gen‐
101     erated using the commands:
102
103           h=$(openssl x509 -outform der -in mycert.crt | sha256)
104           printf "SHA256:${h}\n"
105
106     tls_peer_cert_notbefore() returns the time corresponding to the start of
107     the validity period of the peer certificate from ctx.
108
109     tls_peer_cert_notafter() returns the time corresponding to the end of the
110     validity period of the peer certificate from ctx.
111

RETURN VALUES

113     The tls_conn_session_resumed() function returns 1 if a TLS session was
114     resumed or 0 if it was not.
115
116     The tls_peer_cert_provided() and tls_peer_cert_contains_name() functions
117     return 1 if the check succeeds or 0 if it does not.
118
119     tls_peer_cert_notbefore() and tls_peer_cert_notafter() return a time in
120     epoch-seconds on success or -1 on error.
121
122     The functions that return a pointer return NULL on error or an out of
123     memory condition.
124

SEE ALSO

126     tls_configure(3), tls_handshake(3), tls_init(3),
127     tls_ocsp_process_response(3)
128

HISTORY

130     tls_conn_version(), tls_conn_cipher(), tls_peer_cert_provided(),
131     tls_peer_cert_contains_name(), tls_peer_cert_issuer(),
132     tls_peer_cert_subject(), tls_peer_cert_hash(), tls_peer_cert_notbefore(),
133     and tls_peer_cert_notafter() appeared in OpenBSD 5.9.
134
135     tls_conn_servername() and tls_conn_alpn_selected() appeared in
136     OpenBSD 6.1.
137
138     tls_conn_session_resumed() appeared in OpenBSD 6.3.
139
140     tls_conn_cipher_strength() appeared in OpenBSD 6.7.
141

AUTHORS

143     Bob Beck <beck@openbsd.org>
144     Joel Sing <jsing@openbsd.org>
145
146BSD                            November 2, 2019                            BSD