lib/libtls/man/tls_init.3

   1 .\" $OpenBSD: tls_init.3,v 1.13 2018/07/09 19:47:20 tb Exp $
   2 .\"
   3 .\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org>
   4 .\" Copyright (c) 2016 Joel Sing <jsing@openbsd.org>
   5 .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
   6 .\"
   7 .\" Permission to use, copy, modify, and distribute this software for any
   8 .\" purpose with or without fee is hereby granted, provided that the above
   9 .\" copyright notice and this permission notice appear in all copies.
  10 .\"
  11 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  12 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  13 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  14 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  15 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  16 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  17 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  18 .\"
  19 .Dd $Mdocdate: July 9 2018 $
  20 .Dt TLS_INIT 3
  21 .Os
  22 .Sh NAME
  23 .Nm tls_init ,
  24 .Nm tls_config_new ,
  25 .Nm tls_config_free ,
  26 .Nm tls_config_error
  27 .Nd initialize TLS client and server API
  28 .Sh SYNOPSIS
  29 .In tls.h
  30 .Ft int
  31 .Fn tls_init void
  32 .Ft struct tls_config *
  33 .Fn tls_config_new void
  34 .Ft void
  35 .Fn tls_config_free "struct tls_config *config"
  36 .Ft const char *
  37 .Fn tls_config_error "struct tls_config *config"
  38 .Sh DESCRIPTION
  39 The
  40 .Nm tls
  41 family of functions establishes a secure communications channel
  42 using the TLS socket protocol.
  43 Both clients and servers are supported.
  44 .Pp
  45 The
  46 .Fn tls_init
  47 function initializes global data structures.
  48 It is no longer necessary to call this function directly,
  49 since it is invoked internally when needed.
  50 It may be called more than once, and may be called concurrently.
  51 .Pp
  52 Before a connection is created, a configuration must be created.
  53 The
  54 .Fn tls_config_new
  55 function allocates, initializes, and returns a new default configuration
  56 object that can be used for future connections.
  57 Several functions exist to change the options of the configuration; see
  58 .Xr tls_config_set_protocols 3 ,
  59 .Xr tls_load_file 3 ,
  60 .Xr tls_config_ocsp_require_stapling 3 ,
  61 and
  62 .Xr tls_config_verify 3 .
  63 .Pp
  64 The
  65 .Fn tls_config_error
  66 function may be used to retrieve a string containing more information
  67 about the most recent error relating to a configuration.
  68 .Pp
  69 A TLS connection object is created by
  70 .Xr tls_client 3
  71 or
  72 .Xr tls_server 3
  73 and configured with
  74 .Xr tls_configure 3 .
  75 .Pp
  76 A client connection is initiated after configuration by calling
  77 .Xr tls_connect 3 .
  78 A server can accept a new client connection by calling
  79 .Xr tls_accept_socket 3
  80 on an already established socket connection.
  81 .Pp
  82 Two functions are provided for input and output,
  83 .Xr tls_read 3
  84 and
  85 .Xr tls_write 3 .
  86 Both automatically perform the
  87 .Xr tls_handshake 3
  88 when needed.
  89 .Pp
  90 The properties of established TLS connections
  91 can be inspected with the functions described in
  92 .Xr tls_conn_version 3
  93 and
  94 .Xr tls_ocsp_process_response 3 .
  95 .Pp
  96 After use, a TLS connection should be closed with
  97 .Xr tls_close 3
  98 and then freed by calling
  99 .Xr tls_free 3 .
 100 .Pp
 101 When no more contexts are to be configured,
 102 the configuration object should be freed by calling
 103 .Fn tls_config_free .
 104 It is safe to call
 105 .Fn tls_config_free
 106 as soon as the final call to
 107 .Fn tls_configure
 108 has been made.
 109 If
 110 .Fa config
 111 is
 112 .Dv NULL ,
 113 no action occurs.
 114 .Sh RETURN VALUES
 115 .Fn tls_init
 116 returns 0 on success or -1 on error.
 117 .Pp
 118 .Fn tls_config_new
 119 returns
 120 .Dv NULL
 121 on error or an out of memory condition.
 122 .Pp
 123 .Fn tls_config_error
 124 returns
 125 .Dv NULL
 126 if no error occurred with
 127 .Fa config
 128 at all, or if memory allocation failed while trying to assemble the
 129 string describing the most recent error related to
 130 .Fa config .
 131 .Sh SEE ALSO
 132 .Xr tls_accept_socket 3 ,
 133 .Xr tls_client 3 ,
 134 .Xr tls_config_ocsp_require_stapling 3 ,
 135 .Xr tls_config_set_protocols 3 ,
 136 .Xr tls_config_verify 3 ,
 137 .Xr tls_conn_version 3 ,
 138 .Xr tls_connect 3 ,
 139 .Xr tls_load_file 3 ,
 140 .Xr tls_ocsp_process_response 3 ,
 141 .Xr tls_read 3
 142 .Sh HISTORY
 143 The
 144 .Nm tls
 145 API first appeared in
 146 .Ox 5.6
 147 as a response to the unnecessary challenges other APIs present in
 148 order to use them safely.
 149 .Pp
 150 All functions were renamed from
 151 .Fn ressl_*
 152 to
 153 .Fn tls_*
 154 for
 155 .Ox 5.7 .
 156 .Pp
 157 .Fn tls_config_error
 158 appeared in
 159 .Ox 6.0 .
 160 .Sh AUTHORS
 161 .An Joel Sing Aq Mt jsing@openbsd.org
 162 .An Ted Unangst Aq Mt tedu@openbsd.org
 163 .Pp
 164 Many others contributed to various parts of the library; see the
 165 individual manual pages for more information.
 166 .Sh CAVEATS
 167 The function
 168 .Fn tls_config_error
 169 returns an internal pointer.
 170 It must not be freed by the application, or a double free error
 171 will occur.
 172 The pointer will become invalid when the next error occurs with
 173 .Fa config .
 174 Consequently, if the application may need the message at a later
 175 time, it has to copy the string before calling the next
 176 .Sy libtls
 177 function involving
 178 .Fa config ,
 179 or a segmentation fault or read access to unintended data is the
 180 likely result.