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 particularly recommended to use with processes which connect
  56 to many various hosts (eg. web browsers) with little correlation between domain names and IP addresses/ranges,
  57 because it makes hard for the wrapper command to find out the right SNI for a given IP.
  58 A more plausible scenario is to make autossl.so upgrade socket connections to a few, 1, 2, or 3 hosts,
  59 or to hosts of which server name is unambiguous by thier IP.
  60
  61 =head2 Error cases
  62
  63 By default, autossl does not cause exception in the caller process in
  64 error cases (eg. ip address parse error, invalid port number), rather
  65 falls back to system's connect(2) function.
  66 However if AUTOSSL_ERRNO is set, it sets errno to that value and returns
  67 -1 in the above error cases. You may set AUTOSSL_ERRNO to 5 to report
  68 IOError in such cases.
  69
  70 =head1 COMPATIBILITY
  71
  72 inet sockets (ipv4)
  73
  74 SOCK_STREAM (tcp)
  75
  76 =head1 ENVIRONMENT
  77
  78 AUTOSSL_UPGRADE_PORTS
  79
  80 AUTOSSL_UPGRADE_IPS
  81
  82 AUTOSSL_TLS_CMD
  83
  84 AUTOSSL_ERRNO
  85
  86 AUTOSSL_SILENT
  87
  88 =head1 HOW TO COMPILE
  89
  90   gcc -D_GNU_SOURCE -ldl -shared -fPIC -o autossl.so autossl.c