preload/autossl/autossl.so.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 autossl.so - LD_PRELOAD-able library to upgrade plain transport channels to enrypted ones without the client software's knowledge
   6
   7 =head1 USAGE
   8
   9 LD_PRELOAD=.../autossl.so AUTOSSL_UPGRADE_PORTS="80 8080" AUTOSSL_TLS_CMD=stunnel.sh wget ...
  10
  11 LD_PRELOAD=.../autossl.so AUTOSSL_UPGRADE_PORT=80 AUTOSSL_UPGRADE_IPS="192.0.2.1 192.0.2.2" AUTOSSL_TLS_CMD=s_client.sh wget ...
  12
  13 =head1 DESCRIPTION
  14
  15 This shared library extends connect(2) standard library function adding
  16 SSL/TLS layer on the socket transparently.
  17 Doing it by invoking a wrapper command and passing the caller process
  18 traffic through its STDIO.
  19 On each connect() calls, it checks that the destination port is one of
  20 those from B<AUTOSSL_UPGRADE_PORTS> environment variable and the
  21 destination IP is one of the IPs in B<AUTOSSL_UPGRADE_IPS> (if it's set).
  22
  23 AUTOSSL_UPGRADE_PORTS and AUTOSSL_UPGRADE_IPS are space-delimited list
  24 of port numbers and IPs respectively.
  25 If you don't know the IP(s) prior, leave AUTOSSL_UPGRADE_IPS unset, then
  26 any connection on AUTOSSL_UPGRADE_PORTS ports to any host will be
  27 upgraded.
  28
  29 If the criteria above are satisfied, starts I<AUTOSSL_TLS_CMD> expecting
  30 it to connect to the right TLS endpoint.
  31 I<AUTOSSL_TLS_CMD> is invoked with 2 arguments: the original IP and port
  32 the caller process wanted to connect, so it can find out where to open
  33 the TLS channel if the caller possibly connects to more than 1 endpoints
  34 during runtime.
  35
  36 In the I<AUTOSSL_TLS_CMD> wrapper command, run stunnel(8) or openssl
  37 s_client(1SSL) or other command to open a TLS channel connected to the
  38 STDIO, eg:
  39
  40   stunnel -f -c -r mail.example.net:993
  41
  42   openssl s_client -connect $1:443 -servername example.net -quiet
  43
  44 If you dont want to upgrade a particular connection to TLS, simply run
  45 something like C<unset AUTOSSL_UPGRADE_PORTS; netcat $1 $2>.
  46
  47 =head2 SNI concerns
  48
  49 Currently the domain name which the caller process wants to connect to
  50 is not known by autossl.so, because programs get the hostname resolved
  51 to IP address(es) before connect(2) is called and does not pass the
  52 prior known hostname to it.
  53 Therefore the wrapper command has to be creative in terms of what to
  54 send in SNI to the TLS endpoint.
  55 Autossl is not particular recommended to use in processes which connects
  56 to many various hosts (eg. web browsers) with little domain name -- IP
  57 range corelation, because it makes hard for the wrapper command to find
  58 out the right SNI for a given IP.
  59 A more plausible scenario to have autossl.so upgrade socket connections
  60 to a few, 1, 2, or 3 hosts, or to hosts whiches server name is
  61 unambiguous by thier IP provided in order to have correct SNI.
  62
  63 =head2 Error cases
  64
  65 By default, autossl does not cause exception in the caller process in
  66 error cases (eg. ip address parse error, invalid port number), rather
  67 falls back to system's connect(2) function.
  68 However if AUTOSSL_ERRNO is set, it sets errno to that value and returns
  69 -1 in the above error cases. You may set AUTOSSL_ERRNO to 5 to report
  70 IOError in such cases.
  71
  72 =head1 COMPATIBILITY
  73
  74 inet sockets (ipv4)
  75
  76 SOCK_STREAM (tcp)
  77
  78 =head1 ENVIRONMENT
  79
  80 AUTOSSL_UPGRADE_PORTS
  81
  82 AUTOSSL_UPGRADE_IPS
  83
  84 AUTOSSL_TLS_CMD
  85
  86 AUTOSSL_ERRNO
  87
  88 AUTOSSL_SILENT
  89
  90 =head1 HOW TO COMPILE
  91
  92   gcc -D_GNU_SOURCE -ldl -shared -fPIC -o autossl.so autossl.c