about summary refs log tree commit diff
path: root/man/tls_conn_version.3
blob: 9ab6932f54f179b9ded3a55602250fa1a8d126f0 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
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