summaryrefslogtreecommitdiff
path: root/src/lib/libtls/tls_init.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/lib/libtls/tls_init.3885
1 files changed, 0 insertions, 885 deletions
diff --git a/src/lib/libtls/tls_init.3 b/src/lib/libtls/tls_init.3
deleted file mode 100644
index 5d4be14ede..0000000000
--- a/src/lib/libtls/tls_init.3
+++ /dev/null
@@ -1,885 +0,0 @@
1.\" $OpenBSD: tls_init.3,v 1.86 2017/01/24 07:57:39 jmc Exp $
2.\"
3.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: January 24 2017 $
18.Dt TLS_INIT 3
19.Os
20.Sh NAME
21.Nm tls_init ,
22.Nm tls_config_error ,
23.Nm tls_error ,
24.Nm tls_config_new ,
25.Nm tls_config_free ,
26.Nm tls_config_parse_protocols ,
27.Nm tls_config_add_keypair_file ,
28.Nm tls_config_add_keypair_mem ,
29.Nm tls_config_add_ticket_key ,
30.Nm tls_config_set_alpn ,
31.Nm tls_config_set_ca_file ,
32.Nm tls_config_set_ca_path ,
33.Nm tls_config_set_ca_mem ,
34.Nm tls_config_set_cert_file ,
35.Nm tls_config_set_cert_mem ,
36.Nm tls_config_set_ciphers ,
37.Nm tls_config_set_dheparams ,
38.Nm tls_config_set_ecdhecurve ,
39.Nm tls_config_set_key_file ,
40.Nm tls_config_set_key_mem ,
41.Nm tls_config_set_keypair_file ,
42.Nm tls_config_set_keypair_mem ,
43.Nm tls_config_set_ocsp_staple_mem ,
44.Nm tls_config_set_ocsp_staple_file ,
45.Nm tls_config_set_protocols ,
46.Nm tls_config_set_session_id ,
47.Nm tls_config_set_session_lifetime ,
48.Nm tls_config_set_verify_depth ,
49.Nm tls_config_prefer_ciphers_client ,
50.Nm tls_config_prefer_ciphers_server ,
51.Nm tls_config_clear_keys ,
52.Nm tls_config_insecure_noverifycert ,
53.Nm tls_config_insecure_noverifyname ,
54.Nm tls_config_insecure_noverifytime ,
55.Nm tls_config_ocsp_require_stapling ,
56.Nm tls_config_verify ,
57.Nm tls_config_verify_client ,
58.Nm tls_config_verify_client_optional ,
59.Nm tls_peer_cert_provided ,
60.Nm tls_peer_cert_contains_name ,
61.Nm tls_peer_cert_issuer ,
62.Nm tls_peer_cert_subject ,
63.Nm tls_peer_cert_hash ,
64.Nm tls_peer_cert_notbefore ,
65.Nm tls_peer_cert_notafter ,
66.Nm tls_ocsp_process_response ,
67.Nm tls_peer_ocsp_cert_status ,
68.Nm tls_peer_ocsp_crl_reason ,
69.Nm tls_peer_ocsp_next_update ,
70.Nm tls_peer_ocsp_response_status ,
71.Nm tls_peer_ocsp_result_msg ,
72.Nm tls_peer_ocsp_revocation_time ,
73.Nm tls_peer_ocsp_this_update ,
74.Nm tls_peer_ocsp_url ,
75.Nm tls_conn_alpn_selected ,
76.Nm tls_conn_cipher ,
77.Nm tls_conn_servername ,
78.Nm tls_conn_version ,
79.Nm tls_load_file ,
80.Nm tls_client ,
81.Nm tls_server ,
82.Nm tls_configure ,
83.Nm tls_reset ,
84.Nm tls_free ,
85.Nm tls_connect ,
86.Nm tls_connect_fds ,
87.Nm tls_connect_servername ,
88.Nm tls_connect_socket ,
89.Nm tls_connect_cbs ,
90.Nm tls_accept_fds ,
91.Nm tls_accept_socket ,
92.Nm tls_accept_cbs ,
93.Nm tls_handshake ,
94.Nm tls_read ,
95.Nm tls_write ,
96.Nm tls_close
97.Nd TLS client and server API
98.Sh SYNOPSIS
99.In tls.h
100.Ft "int"
101.Fn tls_init "void"
102.Ft "const char *"
103.Fn tls_config_error "struct tls_config *config"
104.Ft "const char *"
105.Fn tls_error "struct tls *ctx"
106.Ft "struct tls_config *"
107.Fn tls_config_new "void"
108.Ft "void"
109.Fn tls_config_free "struct tls_config *config"
110.Ft "int"
111.Fn tls_config_parse_protocols "uint32_t *protocols" "const char *protostr"
112.Ft "int"
113.Fn tls_config_add_keypair_file "struct tls_config *config" "const char *cert_file" "const char *key_file"
114.Ft "int"
115.Fn tls_config_add_keypair_mem "struct tls_config *config" "const uint8_t *cert" "size_t cert_len" "const uint8_t *key" "size_t key_len"
116.Ft "int"
117.Fn tls_config_add_ticket_key "struct tls_config *config" "uint32_t keyrev" "unsigned char *key" "size_t keylen"
118.Ft "int"
119.Fn tls_config_set_alpn "struct tls_config *config" "const char *alpn"
120.Ft "int"
121.Fn tls_config_set_ca_file "struct tls_config *config" "const char *ca_file"
122.Ft "int"
123.Fn tls_config_set_ca_path "struct tls_config *config" "const char *ca_path"
124.Ft "int"
125.Fn tls_config_set_ca_mem "struct tls_config *config" "const uint8_t *cert" "size_t len"
126.Ft "int"
127.Fn tls_config_set_cert_file "struct tls_config *config" "const char *cert_file"
128.Ft "int"
129.Fn tls_config_set_cert_mem "struct tls_config *config" "const uint8_t *cert" "size_t len"
130.Ft "int"
131.Fn tls_config_set_ciphers "struct tls_config *config" "const char *ciphers"
132.Ft "int"
133.Fn tls_config_set_dheparams "struct tls_config *config" "const char *params"
134.Ft "int"
135.Fn tls_config_set_ecdhecurve "struct tls_config *config" "const char *name"
136.Ft "int"
137.Fn tls_config_set_key_file "struct tls_config *config" "const char *key_file"
138.Ft "int"
139.Fn tls_config_set_key_mem "struct tls_config *config" "const uint8_t *key" "size_t len"
140.Ft "int"
141.Fn tls_config_set_keypair_file "struct tls_config *config" "const char *cert_file" "const char *key_file"
142.Ft "int"
143.Fn tls_config_set_keypair_mem "struct tls_config *config" "const uint8_t *cert" "size_t cert_len" "const uint8_t *key" "size_t key_len"
144.Ft "int"
145.Fn tls_config_set_ocsp_staple_mem "struct tls_config *config" "const char *staple" "size_t len"
146.Ft "int"
147.Fn tls_config_set_ocsp_staple_file "struct tls_config *config" "const char *staple_file"
148.Ft "int"
149.Fn tls_config_set_protocols "struct tls_config *config" "uint32_t protocols"
150.Ft "int"
151.Fn tls_config_set_session_id "struct tls_config *config" "const unsigned char *session_id" "size_t len"
152.Ft "int"
153.Fn tls_config_set_session_lifetime "struct tls_config *config" "int lifetime"
154.Ft "int"
155.Fn tls_config_set_verify_depth "struct tls_config *config" "int verify_depth"
156.Ft "void"
157.Fn tls_config_prefer_ciphers_client "struct tls_config *config"
158.Ft "void"
159.Fn tls_config_prefer_ciphers_server "struct tls_config *config"
160.Ft "void"
161.Fn tls_config_clear_keys "struct tls_config *config"
162.Ft "void"
163.Fn tls_config_insecure_noverifycert "struct tls_config *config"
164.Ft "void"
165.Fn tls_config_insecure_noverifyname "struct tls_config *config"
166.Ft "void"
167.Fn tls_config_insecure_noverifytime "struct tls_config *config"
168.Ft "void"
169.Fn tls_config_ocsp_require_stapling "struct tls_config *config"
170.Ft "void"
171.Fn tls_config_verify "struct tls_config *config"
172.Ft "void"
173.Fn tls_config_verify_client "struct tls_config *config"
174.Ft "void"
175.Fn tls_config_verify_client_optional "struct tls_config *config"
176.Ft "int"
177.Fn tls_peer_cert_provided "struct tls *ctx"
178.Ft "int"
179.Fn tls_peer_cert_contains_name "struct tls *ctx" "const char *name"
180.Ft "const char *"
181.Fn tls_peer_cert_issuer "struct tls *ctx"
182.Ft "const char *"
183.Fn tls_peer_cert_subject "struct tls *ctx"
184.Ft "const char *"
185.Fn tls_peer_cert_hash "struct tls *ctx"
186.Ft "time_t"
187.Fn tls_peer_cert_notbefore "struct tls *ctx"
188.Ft "time_t"
189.Fn tls_peer_cert_notafter "struct tls *ctx"
190.Ft "int"
191.Fn tls_ocsp_process_response "struct tls *ctx" "const unsigned char *response" "size_t size"
192.Ft "int"
193.Fn tls_peer_ocsp_cert_status "struct tls *ctx"
194.Ft "int"
195.Fn tls_peer_ocsp_crl_reason "struct tls *ctx"
196.Ft time_t
197.Fn tls_peer_ocsp_next_update "struct tls *ctx"
198.Ft "int"
199.Fn tls_peer_ocsp_response_status "struct tls *ctx"
200.Ft "const char *"
201.Fn tls_peer_ocsp_result_msg "struct tls *ctx"
202.Ft "time_t"
203.Fn tls_peer_ocsp_revocation_time "struct tls *ctx"
204.Ft "time_t"
205.Fn tls_peer_ocsp_this_update "struct tls *ctx"
206.Ft "const char *"
207.Fn tls_peer_ocsp_url "struct tls *ctx"
208.Ft "const char *"
209.Fn tls_conn_alpn_selected "struct tls *ctx"
210.Ft "const char *"
211.Fn tls_conn_cipher "struct tls *ctx"
212.Ft "const char *"
213.Fn tls_conn_servername "struct tls *ctx"
214.Ft "const char *"
215.Fn tls_conn_version "struct tls *ctx"
216.Ft "uint8_t *"
217.Fn tls_load_file "const char *file" "size_t *len" "char *password"
218.Ft "struct tls *"
219.Fn tls_client void
220.Ft "struct tls *"
221.Fn tls_server void
222.Ft "int"
223.Fn tls_configure "struct tls *ctx" "struct tls_config *config"
224.Ft "void"
225.Fn tls_reset "struct tls *ctx"
226.Ft "void"
227.Fn tls_free "struct tls *ctx"
228.Ft "int"
229.Fn tls_connect "struct tls *ctx" "const char *host" "const char *port"
230.Ft "int"
231.Fn tls_connect_fds "struct tls *ctx" "int fd_read" "int fd_write" "const char *servername"
232.Ft "int"
233.Fn tls_connect_servername "struct tls *ctx" "const char *host" "const char *port" "const char *servername"
234.Ft "int"
235.Fn tls_connect_socket "struct tls *ctx" "int s" "const char *servername"
236.Ft "int"
237.Fn tls_connect_cbs "struct tls *ctx" "ssize_t (*tls_read_cb)(struct tls *ctx, void *buf, size_t buflen, void *cb_arg)" "ssize_t (*tls_write_cb)(struct tls *ctx, const void *buf, size_t buflen, void *cb_arg)" "void *cb_arg" "const char *servername"
238.Ft "int"
239.Fn tls_accept_fds "struct tls *tls" "struct tls **cctx" "int fd_read" "int fd_write"
240.Ft "int"
241.Fn tls_accept_socket "struct tls *tls" "struct tls **cctx" "int socket"
242.Ft "int"
243.Fn tls_accept_cbs "struct tls *ctx" "struct tls **cctx" "ssize_t (*tls_read_cb)(struct *ctx, void *buf, size_t buflen, void *cb_arg)" "ssize_t (*tls_write_cb)(struct tls *ctx, const void *buf, size_t buflen, void *cb_arg)" "void *cb_arg"
244.Ft "int"
245.Fn tls_handshake "struct tls *ctx"
246.Ft "ssize_t"
247.Fn tls_read "struct tls *ctx" "void *buf" "size_t buflen"
248.Ft "ssize_t"
249.Fn tls_write "struct tls *ctx" "const void *buf" "size_t buflen"
250.Ft "int"
251.Fn tls_close "struct tls *ctx"
252.Sh DESCRIPTION
253The
254.Nm tls
255family of functions establishes a secure communications channel
256using the TLS socket protocol.
257Both clients and servers are supported.
258.Pp
259The
260.Fn tls_init
261function should be called once before any function is used.
262It may be called more than once, but not concurrently.
263.Pp
264Before a connection is created, a configuration must be created.
265The
266.Fn tls_config_new
267function returns a new default configuration that can be used for future
268connections.
269Several functions exist to change the options of the configuration; see below.
270.Pp
271A TLS connection is represented as a
272.Em context .
273A new
274.Em context
275is created by either the
276.Fn tls_client
277or
278.Fn tls_server
279functions.
280The context can then be configured with the function
281.Fn tls_configure .
282The same
283.Em tls_config
284object can be used to configure multiple contexts.
285.Pp
286A client connection is initiated after configuration by calling
287.Fn tls_connect .
288This function will create a new socket, connect to the specified host and
289port, and then establish a secure connection.
290The
291.Fn tls_connect_servername
292function has the same behaviour, however the name to use for verification is
293explicitly provided, rather than being inferred from the
294.Ar host
295value.
296An already existing socket can be upgraded to a secure connection by calling
297.Fn tls_connect_socket .
298Alternatively, a secure connection can be established over a pair of existing
299file descriptors by calling
300.Fn tls_connect_fds .
301Calling
302.Fn tls_connect_cbs
303allows read and write callback functions to handle data transfers.
304The specified cb_arg parameter is passed back to the functions,
305and can contain a pointer to any caller-specified data.
306.Pp
307A server can accept a new client connection by calling
308.Fn tls_accept_socket
309on an already established socket connection.
310Alternatively, a new client connection can be accepted over a pair of existing
311file descriptors by calling
312.Fn tls_accept_fds .
313Calling
314.Fn tls_accept_cbs
315allows read and write callback functions to handle data transfers.
316The specified cb_arg parameter is passed back to the functions,
317and can contain a pointer to any caller-specified data.
318.Pp
319The TLS handshake can be completed by calling
320.Fn tls_handshake .
321Two functions are provided for input and output,
322.Fn tls_read
323and
324.Fn tls_write .
325Both of these functions will result in the TLS handshake being performed if it
326has not already completed.
327.Pp
328After use, a TLS
329.Em context
330should be closed with
331.Fn tls_close ,
332and then freed by calling
333.Fn tls_free .
334When no more contexts are to be created, the
335.Em tls_config
336object should be freed by calling
337.Fn tls_config_free .
338.Sh FUNCTIONS
339The
340.Fn tls_init
341function initializes global data structures.
342It should be called once before any other functions.
343.Pp
344The following functions create and free configuration objects:
345.Bl -bullet -offset four
346.It
347.Fn tls_config_new
348allocates a new default configuration object.
349.It
350.Fn tls_config_free
351frees a configuration object.
352.El
353.Pp
354The
355.Fn tls_config_parse_protocols
356function parses a protocol string and returns the corresponding value via the
357.Ar protocols
358argument.
359This value can then be passed to the
360.Fn tls_config_set_protocols
361function.
362The protocol string is a comma or colon separated list of keywords.
363Valid keywords are tlsv1.0, tlsv1.1, tlsv1.2, all (all supported protocols),
364default (an alias for secure), legacy (an alias for all) and secure (currently
365TLSv1.2 only).
366If a value has a negative prefix (in the form of a leading exclamation mark)
367then it is removed from the list of available protocols, rather than being
368added to it.
369.Pp
370The following functions modify a configuration by setting parameters (the
371configuration options apply to both clients and servers, unless noted
372otherwise):
373.Bl -bullet -offset four
374.It
375.Fn tls_config_add_keypair_file
376adds an additional public certificate and private key from the specified files,
377used as an alternative certificate for Server Name Indication (server only).
378.It
379.Fn tls_config_add_keypair_mem
380adds an additional public certificate and private key from memory,
381used as an alternative certificate for Server Name Indication (server only).
382.It
383.Fn tls_config_add_ticket_key
384adds a key used for the encryption and authentication of TLS tickets.
385By default keys are generated and rotated automatically based on their lifetime.
386This function should only be used to synchronise ticket encryption key across
387multiple processes.
388Re-adding a known key will result in an error, unless it is the most recently
389added key.
390.It
391.Fn tls_config_set_alpn
392sets the ALPN protocols that are supported.
393The alpn string is a comma separated list of protocols, in order of preference.
394.It
395.Fn tls_config_set_ca_file
396sets the filename used to load a file
397containing the root certificates.
398.It
399.Fn tls_config_set_ca_path
400sets the path (directory) which should be searched for root
401certificates.
402.It
403.Fn tls_config_set_ca_mem
404sets the root certificates directly from memory.
405.It
406.Fn tls_config_set_cert_file
407sets file from which the public certificate will be read.
408.It
409.Fn tls_config_set_cert_mem
410sets the public certificate directly from memory.
411.It
412.Fn tls_config_set_ciphers
413sets the list of ciphers that may be used.
414Lists of ciphers are specified by name, and the
415permitted names are:
416.Pp
417.Bl -tag -width "insecure" -offset indent -compact
418.It Dv "secure" (or alias "default")
419.It Dv "compat"
420.It Dv "legacy"
421.It Dv "insecure" (or alias "all")
422.El
423.Pp
424Alternatively, libssl cipher strings can be specified.
425See the CIPHERS section of
426.Xr openssl 1
427for further information.
428.It
429.Fn tls_config_set_key_file
430sets the file from which the private key will be read.
431.It
432.Fn tls_config_set_key_mem
433directly sets the private key from memory.
434.It
435.Fn tls_config_set_keypair_file
436sets the files from which the public certificate and private key will be read.
437.It
438.Fn tls_config_set_keypair_mem
439directly sets the public certificate and private key from memory.
440.It
441.Fn tls_config_set_ocsp_staple_file
442sets a DER-encoded OCSP response to be stapled during the TLS handshake from
443the specified file.
444.It
445.Fn tls_config_set_ocsp_staple_mem
446sets a DER-encoded OCSP response to be stapled during the TLS handshake from
447memory.
448.It
449.Fn tls_config_set_protocols
450sets which versions of the protocol may be used.
451Possible values are the bitwise OR of:
452.Pp
453.Bl -tag -width "TLS_PROTOCOL_TLSv1_2" -offset indent -compact
454.It Dv TLS_PROTOCOL_TLSv1_0
455.It Dv TLS_PROTOCOL_TLSv1_1
456.It Dv TLS_PROTOCOL_TLSv1_2
457.El
458.Pp
459Additionally, the values
460.Dv TLS_PROTOCOL_TLSv1
461(TLSv1.0, TLSv1.1 and TLSv1.2),
462.Dv TLS_PROTOCOLS_ALL
463(all supported protocols) and
464.Dv TLS_PROTOCOLS_DEFAULT
465(TLSv1.2 only) may be used.
466.It
467.Fn tls_config_set_session_id
468sets the session identifier that will be used by the TLS server when
469sessions are enabled.
470By default a random value is used.
471.It
472.Fn tls_config_set_session_lifetime
473sets the lifetime to be used for TLS sessions.
474Session support is disabled if a lifetime of zero is specified, which is the
475default.
476.It
477.Fn tls_config_set_verify_depth
478limits the number of intermediate certificates that will be followed during
479certificate validation.
480.It
481.Fn tls_config_prefer_ciphers_client
482prefers ciphers in the client's cipher list when selecting a cipher suite
483(server only).
484This is considered to be less secure than preferring the server's list.
485.It
486.Fn tls_config_prefer_ciphers_server
487prefers ciphers in the server's cipher list when selecting a cipher suite
488(server only).
489This is considered to be more secure than preferring the client's list and is
490the default.
491.It
492.Fn tls_config_clear_keys
493clears any secret keys from memory.
494.It
495.Fn tls_config_insecure_noverifycert
496disables certificate verification and OCSP validation.
497Be extremely careful when using this option.
498.It
499.Fn tls_config_insecure_noverifyname
500disables server name verification (client only).
501Be careful when using this option.
502.It
503.Fn tls_config_insecure_noverifytime
504disables validity checking of certificates and OCSP validation.
505Be careful when using this option.
506.It
507.Fn tls_config_ocsp_require_stapling
508requires that a valid stapled OCSP response be provided during the TLS handshake.
509.It
510.Fn tls_config_verify
511reenables server name and certificate verification.
512.It
513.Fn tls_config_verify_client
514enables client certificate verification, requiring the client to send
515a certificate (server only).
516.It
517.Fn tls_config_verify_client_optional
518enables client certificate verification, without requiring the client
519to send a certificate (server only).
520.El
521.Pp
522The following functions return information about a TLS connection and will only
523succeed after the handshake is complete (the connection information applies
524to both clients and servers, unless noted otherwise):
525.Bl -bullet -offset four
526.It
527.Fn tls_conn_alpn_selected
528returns a string that specifies the ALPN protocol selected for use with the peer
529connected to
530.Ar ctx .
531If no protocol was selected then NULL is returned.
532.It
533.Fn tls_conn_cipher
534returns a string corresponding to the cipher suite negotiated with the peer
535connected to
536.Ar ctx .
537.It
538.Fn tls_conn_servername
539returns a string corresponding to the servername that the client connected to
540.Ar ctx
541requested by sending a TLS Server Name Indication extension (server only).
542.It
543.Fn tls_conn_version
544returns a string corresponding to a TLS version negotiated with the peer
545connected to
546.Ar ctx .
547.It
548.Fn tls_peer_cert_provided
549checks if the peer of
550.Ar ctx
551has provided a certificate.
552.It
553.Fn tls_peer_cert_contains_name
554checks if the peer of a TLS
555.Ar ctx
556has provided a certificate that contains a
557SAN or CN that matches
558.Ar name .
559.It
560.Fn tls_peer_cert_subject
561returns a string
562corresponding to the subject of the peer certificate from
563.Ar ctx .
564.It
565.Fn tls_peer_cert_issuer
566returns a string
567corresponding to the issuer of the peer certificate from
568.Ar ctx .
569.It
570.Fn tls_peer_cert_hash
571returns a string
572corresponding to a hash of the raw peer certificate from
573.Ar ctx
574prefixed by a hash name followed by a colon.
575The hash currently used is SHA256, though this
576could change in the future.
577The hash string for a certificate in file
578.Ar mycert.crt
579can be generated using the commands:
580.Bd -literal -offset indent
581h=$(openssl x509 -outform der -in mycert.crt | sha256)
582printf "SHA256:${h}\\n"
583.Ed
584.It
585.Fn tls_peer_cert_notbefore
586returns the time corresponding to the start of the validity period of
587the peer certificate from
588.Ar ctx .
589.It
590.Fn tls_peer_cert_notafter
591returns the time corresponding to the end of the validity period of
592the peer certificate from
593.Ar ctx .
594.It
595.Fn tls_ocsp_process_response
596processes a raw OCSP response in
597.Ar response
598of size
599.Ar size
600to check the revocation status of the peer certificate from
601.Ar ctx .
602A successful return code of 0 indicates that the certificate
603has not been revoked.
604.It
605.Fn tls_peer_ocsp_url
606returns the URL for OCSP validation of the peer certificate from
607.Ar ctx
608.El
609.Pp
610The following functions return information about the peer certificate from
611.Ar ctx
612that was obtained by validating a stapled OCSP response during the handshake,
613or via a previous call to
614.Fn tls_ocsp_process_response .
615.Bl -bullet -offset four
616.It
617.Fn tls_peer_ocsp_cert_status
618returns the OCSP certificate status code as per RFC 6960 section 2.2.
619.It
620.Fn tls_peer_ocsp_crl_reason
621returns the OCSP certificate revocation reason status code as per RFC 5280
622section 5.3.1.
623.It
624.Fn tls_peer_ocsp_next_update
625returns the OCSP next update time.
626.It
627.Fn tls_peer_ocsp_response_status
628returns the OCSP response status as per RFC 6960 section 2.3.
629.It
630.Fn tls_peer_ocsp_revocation_time
631returns the OCSP revocation time.
632.It
633.Fn tls_peer_ocsp_this_update
634returns the OCSP this update time.
635.El
636.Pp
637The following are TLS related utility functions:
638.Bl -bullet -offset four
639.It
640.Fn tls_load_file
641loads a certificate or key from disk into memory to be loaded with
642.Fn tls_config_set_ca_mem ,
643.Fn tls_config_set_cert_mem
644or
645.Fn tls_config_set_key_mem .
646A private key will be decrypted if the optional
647.Ar password
648argument is specified.
649.El
650.Pp
651The following functions create, prepare, and free a connection context:
652.Bl -bullet -offset four
653.It
654.Fn tls_client
655creates a new TLS context for client connections.
656.It
657.Fn tls_server
658creates a new TLS context for server connections.
659.It
660.Fn tls_configure
661readies a TLS context for use by applying the configuration
662options.
663.It
664.Fn tls_free
665frees a TLS context after use.
666.El
667.Pp
668The following functions initiate a connection and perform input and output
669operations:
670.Bl -bullet -offset four
671.It
672.Fn tls_connect
673connects a client context to the server named by
674.Fa host .
675The
676.Fa port
677may be numeric or a service name.
678If it is NULL then a host of the format "hostname:port" is permitted.
679.It
680.Fn tls_connect_fds
681connects a client context to a pair of existing file descriptors.
682.It
683.Fn tls_connect_socket
684connects a client context to an already established socket connection.
685.It
686.Fn tls_accept_fds
687creates a new context suitable for reading and writing on an existing pair of
688file descriptors and returns it in
689.Fa *cctx .
690A configured server context should be passed in
691.Fa ctx .
692.It
693.Fn tls_accept_socket
694creates a new context suitable for reading and writing on an already
695established socket connection and returns it in
696.Fa *cctx .
697A configured server context should be passed in
698.Fa ctx .
699.It
700.Fn tls_handshake
701performs the TLS handshake.
702It is only necessary to call this function if you need to guarantee that the
703handshake has completed, as both
704.Fn tls_read
705and
706.Fn tls_write
707will perform the TLS handshake if necessary.
708.It
709.Fn tls_read
710reads
711.Fa buflen
712bytes of data from the socket into
713.Fa buf .
714It returns the amount of data read.
715.It
716.Fn tls_write
717writes
718.Fa buflen
719bytes of data from
720.Fa buf
721to the socket.
722It returns the amount of data written.
723.It
724.Fn tls_close
725closes a connection after use.
726Only the TLS layer will be shut down and the caller is responsible for closing
727the file descriptors, unless the connection was established using
728.Fn tls_connect
729or
730.Fn tls_connect_servername .
731.El
732.Sh RETURN VALUES
733The
734.Fn tls_peer_cert_provided
735and
736.Fn tls_peer_cert_contains_name
737functions return 1 if the check succeeds, and 0 if it does not.
738.Pp
739Functions that return a
740.Vt time_t
741will return a time in epoch-seconds on success, and -1 on error.
742.Pp
743Functions that return a
744.Vt ssize_t
745will return a size on success, and -1 on error.
746.Pp
747The
748.Fn tls_peer_ocsp_response_status
749function returns one of
750.Ar TLS_OCSP_RESPONSE_SUCCESSFUL ,
751.Ar TLS_OCSP_RESPONSE_MALFORMED ,
752.Ar TLS_OCSP_RESPONSE_INTERNALERROR ,
753.Ar TLS_OCSP_RESPONSE_TRYLATER ,
754.Ar TLS_OCSP_RESPONSE_SIGREQUIRED ,
755or
756.Ar TLS_OCSP_RESPONSE_UNAUTHORIZED
757on success, and -1 on error.
758.Pp
759The
760.Fn tls_peer_ocsp_cert_status
761function returns one of
762.Ar TLS_OCSP_CERT_GOOD ,
763.Ar TLS_OCSP_CERT_REVOKED ,
764or
765.Ar TLS_OCSP_CERT_UNKNOWN
766on success, and -1 on error.
767.Pp
768The
769.Fn tls_peer_ocsp_crl_reason
770function returns one of
771.Ar TLS_CRL_REASON_UNSPECIFIED ,
772.Ar TLS_CRL_REASON_KEY_COMPROMISE ,
773.Ar TLS_CRL_REASON_CA_COMPROMISE ,
774.Ar TLS_CRL_REASON_AFFILIATION_CHANGED ,
775.Ar TLS_CRL_REASON_SUPERSEDED ,
776.Ar TLS_CRL_REASON_CESSATION_OF_OPERATION ,
777.Ar TLS_CRL_REASON_CERTIFICATE_HOLD ,
778.Ar TLS_CRL_REASON_REMOVE_FROM_CRL ,
779.Ar TLS_CRL_REASON_PRIVILEGE_WITHDRAWN ,
780or
781.Ar TLS_CRL_REASON_AA_COMPROMISE
782on success, and -1 on error.
783.Pp
784All other functions that return
785.Vt int
786will return 0 on success and -1 on error.
787.Pp
788Functions that return a pointer will return NULL on error or an
789out of memory condition.
790.Pp
791The
792.Fn tls_handshake ,
793.Fn tls_read ,
794.Fn tls_write ,
795and
796.Fn tls_close
797functions have two special return values:
798.Pp
799.Bl -tag -width "TLS_WANT_POLLOUT" -offset indent -compact
800.It Dv TLS_WANT_POLLIN
801The underlying read file descriptor needs to be readable in order to continue.
802.It Dv TLS_WANT_POLLOUT
803The underlying write file descriptor needs to be writeable in order to continue.
804.El
805.Pp
806In the case of blocking file descriptors, the same function call should be
807repeated immediately.
808In the case of non-blocking file descriptors, the same function call should be
809repeated when the required condition has been met.
810.Pp
811Callers of these functions cannot rely on the value of the global
812.Ar errno .
813To prevent mishandling of error conditions,
814.Fn tls_handshake ,
815.Fn tls_read ,
816.Fn tls_write ,
817and
818.Fn tls_close
819all explicitly clear
820.Ar errno .
821.Sh EXAMPLES
822The following example demonstrates how to handle TLS writes on a blocking
823file descriptor:
824.Bd -literal -offset indent
825\&...
826while (len > 0) {
827 ssize_t ret;
828
829 ret = tls_write(ctx, buf, len);
830 if (ret == TLS_WANT_POLLIN || ret == TLS_WANT_POLLOUT)
831 continue;
832 if (ret < 0)
833 err(1, "tls_write: %s", tls_error(ctx));
834 buf += ret;
835 len -= ret;
836}
837\&...
838.Ed
839.Pp
840The following example demonstrates how to handle TLS writes on a
841non-blocking file descriptor using
842.Xr poll 2 :
843.Bd -literal -offset indent
844\&...
845pfd[0].fd = fd;
846pfd[0].events = POLLIN|POLLOUT;
847while (len > 0) {
848 nready = poll(pfd, 1, 0);
849 if (nready == -1)
850 err(1, "poll");
851 if ((pfd[0].revents & (POLLERR|POLLNVAL)))
852 errx(1, "bad fd %d", pfd[0].fd);
853 if ((pfd[0].revents & (pfd[0].events|POLLHUP))) {
854 ssize_t ret;
855
856 ret = tls_write(ctx, buf, len);
857 if (ret == TLS_WANT_POLLIN)
858 pfd[0].events = POLLIN;
859 else if (ret == TLS_WANT_POLLOUT)
860 pfd[0].events = POLLOUT;
861 else if (ret < 0)
862 err(1, "tls_write: %s", tls_error(ctx));
863 else {
864 buf += ret;
865 len -= ret;
866 }
867 }
868}
869\&...
870.Ed
871.Sh ERRORS
872The
873.Fn tls_config_error
874and
875.Fn tls_error
876functions may be used to retrieve a string containing more information
877about the most recent error relating to a configuration or context.
878.\" .Sh SEE ALSO
879.Sh HISTORY
880The
881.Nm tls
882API first appeared in
883.Ox 5.6
884as a response to the unnecessary challenges other APIs present in
885order to use them safely.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-10-24 03:13:17 +0000