lib/libtls/man/tls_init.3

   1 .\" $OpenBSD: tls_init.3,v 1.7 2017/05/06 21:18:48 jsing 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: May 6 2017 $
  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 should be called once before any other functions.
  49 It may be called more than once, but not concurrently.
  50 .Pp
  51 Before a connection is created, a configuration must be created.
  52 The
  53 .Fn tls_config_new
  54 function allocates, initializes, and returns a new default configuration
  55 object that can be used for future connections.
  56 Several functions exist to change the options of the configuration; see
  57 .Xr tls_config_set_protocols 3 ,
  58 .Xr tls_load_file 3 ,
  59 .Xr tls_config_ocsp_require_stapling 3 ,
  60 and
  61 .Xr tls_config_verify 3 .
  62 .Pp
  63 The
  64 .Fn tls_config_error
  65 function may be used to retrieve a string containing more information
  66 about the most recent error relating to a configuration.
  67 .Pp
  68 A TLS connection object is created by
  69 .Xr tls_client 3
  70 or
  71 .Xr tls_server 3
  72 and configured with
  73 .Xr tls_configure 3 .
  74 .Pp
  75 A client connection is initiated after configuration by calling
  76 .Xr tls_connect 3 .
  77 A server can accept a new client connection by calling
  78 .Xr tls_accept_socket 3
  79 on an already established socket connection.
  80 .Pp
  81 Two functions are provided for input and output,
  82 .Xr tls_read 3
  83 and
  84 .Xr tls_write 3 .
  85 Both automatically perform the
  86 .Xr tls_handshake 3
  87 when needed.
  88 .Pp
  89 The properties of established TLS connections
  90 can be inspected with the functions described in
  91 .Xr tls_conn_version 3
  92 and
  93 .Xr tls_ocsp_process_response 3 .
  94 .Pp
  95 After use, a TLS connection should be closed with
  96 .Xr tls_close 3
  97 and then freed by calling
  98 .Xr tls_free 3 .
  99 .Pp
 100 When no more contexts are to be configured,
 101 the configuration object should be freed by calling
 102 .Fn tls_config_free .
 103 It is safe to call
 104 .Fn tls_config_free
 105 as soon as the final call to
 106 .Fn tls_configure
 107 has been made.
 108 If
 109 .Fa config
 110 is
 111 .Dv NULL ,
 112 no action occurs.
 113 .Sh RETURN VALUES
 114 .Fn tls_init
 115 returns 0 on success or -1 on error.
 116 .Pp
 117 .Fn tls_config_new
 118 returns
 119 .Dv NULL
 120 on error or an out of memory condition.
 121 .Pp
 122 .Fn tls_config_error
 123 returns
 124 .Dv NULL
 125 if no error occurred with
 126 .Fa config
 127 at all, or if memory allocation failed while trying to assemble the
 128 string describing the most recent error related to
 129 .Fa config .
 130 .Sh SEE ALSO
 131 .Xr tls_accept_socket 3 ,
 132 .Xr tls_client 3 ,
 133 .Xr tls_config_ocsp_require_stapling 3 ,
 134 .Xr tls_config_set_protocols 3 ,
 135 .Xr tls_config_verify 3 ,
 136 .Xr tls_conn_version 3 ,
 137 .Xr tls_connect 3 ,
 138 .Xr tls_load_file 3 ,
 139 .Xr tls_ocsp_process_response 3 ,
 140 .Xr tls_read 3
 141 .Sh HISTORY
 142 The
 143 .Nm tls
 144 API first appeared in
 145 .Ox 5.6
 146 as a response to the unnecessary challenges other APIs present in
 147 order to use them safely.
 148 .Pp
 149 All functions were renamed from
 150 .Fn ressl_*
 151 to
 152 .Fn tls_*
 153 for
 154 .Ox 5.7 .
 155 .Pp
 156 .Fn tls_config_error
 157 appeared in
 158 .Ox 6.0 .
 159 .Sh AUTHORS
 160 .An Joel Sing Aq Mt jsing@openbsd.org
 161 .An Ted Unangst Aq Mt tedu@openbsd.org
 162 .Pp
 163 Many others contributed to various parts of the library; see the
 164 individual manual pages for more information.
 165 .Sh CAVEATS
 166 The function
 167 .Fn tls_config_error
 168 returns an internal pointer.
 169 It must not be freed by the application, or a double free error
 170 will occur.
 171 The pointer will become invalid when the next error occurs with
 172 .Fa config .
 173 Consequently, if the application may need the message at a later
 174 time, it has to copy the string before calling the next
 175 .Sy libtls
 176 function involving
 177 .Fa config ,
 178 or a segmentation fault or read access to unintended data is the
 179 likely result.