lib/libtls/man/tls_accept_socket.3

   1 .\" $OpenBSD: tls_accept_socket.3,v 1.3 2017/01/28 00:59:36 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2015 Ted Unangst <tedu@openbsd.org>
   4 .\" Copyright (c) 2015 Joel Sing <jsing@openbsd.org>
   5 .\" Copyright (c) 2016 Brent Cook <bcook@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: January 28 2017 $
  20 .Dt TLS_ACCEPT_SOCKET 3
  21 .Os
  22 .Sh NAME
  23 .Nm tls_accept_socket ,
  24 .Nm tls_accept_fds ,
  25 .Nm tls_accept_cbs
  26 .Nd accept an incoming client connection in a TLS server
  27 .Sh SYNOPSIS
  28 .In tls.h
  29 .Ft int
  30 .Fo tls_accept_socket
  31 .Fa "struct tls *tls"
  32 .Fa "struct tls **cctx"
  33 .Fa "int socket"
  34 .Fc
  35 .Ft int
  36 .Fo tls_accept_fds
  37 .Fa "struct tls *tls"
  38 .Fa "struct tls **cctx"
  39 .Fa "int fd_read"
  40 .Fa "int fd_write"
  41 .Fc
  42 .Ft int
  43 .Fo tls_accept_cbs
  44 .Fa "struct tls *tls"
  45 .Fa "struct tls **cctx"
  46 .Fa "ssize_t (*tls_read_cb)(struct tls *ctx,\
  47  void *buf, size_t buflen, void *cb_arg)"
  48 .Fa "ssize_t (*tls_write_cb)(struct tls *ctx,\
  49  const void *buf, size_t buflen, void *cb_arg)"
  50 .Fa "void *cb_arg"
  51 .Fc
  52 .Sh DESCRIPTION
  53 After creating a TLS server context
  54 .Fa tls
  55 with
  56 .Xr tls_server 3
  57 and configuring it with
  58 .Xr tls_configure 3 ,
  59 a server can accept a new client connection by calling
  60 .Fn tls_accept_socket
  61 on an already established socket connection.
  62 .Pp
  63 Alternatively, a new client connection can be accepted over a pair of existing
  64 file descriptors by calling
  65 .Fn tls_accept_fds .
  66 .Pp
  67 Calling
  68 .Fn tls_accept_cbs
  69 allows read and write callback functions to handle data transfers.
  70 The specified
  71 .Fa cb_arg
  72 parameter is passed back to the functions,
  73 and can contain a pointer to any caller-specified data.
  74 .Pp
  75 All these functions create a new context suitable for reading and writing
  76 and return it in
  77 .Fa *cctx .
  78 .Sh RETURN VALUES
  79 These functions return 0 on success or -1 on error.
  80 .Sh SEE ALSO
  81 .Xr tls_close 3 ,
  82 .Xr tls_config_set_session_id 3 ,
  83 .Xr tls_configure 3 ,
  84 .Xr tls_connect 3 ,
  85 .Xr tls_init 3 ,
  86 .Xr tls_server 3
  87 .Sh HISTORY
  88 .Fn tls_accept_socket
  89 appeared in
  90 .Ox 5.6
  91 and got its final name in
  92 .Ox 5.7 .
  93 .Pp
  94 .Fn tls_accept_fds
  95 appeared in
  96 .Ox 5.8
  97 and
  98 .Fn tls_accept_cbs
  99 in
 100 .Ox 6.1 .
 101 .Sh AUTHORS
 102 .An Joel Sing Aq Mt jsing@openbsd.org
 103 .Pp
 104 .An -nosplit
 105 .Fn tls_accept_cbs
 106 was written by
 107 .An Tobias Pape Aq Mt tobias@netshed.de .