doc/socat-openssltunnel.html

   1 <!-- $Revision: 1.1 $ $Date: 2007/03/06 20:54:43 $ -->
   2 <html><head>
   3 <title>Securing Traffic Between two Socat Instances Using SSL</title>
   4 <link rel="stylesheet" type="text/css" href="dest-unreach.css">
   5 </head>
   6
   7 <body>
   8
   9 <h1>Securing Traffic Between two Socat Instances Using SSL</h1>
  10
  11 <h2>Introduction</h2>
  12 <p>
  13 When you want to connect two socat processes running on different machines and
  14 feel that you need to protect the connection against unauthorized access,
  15 sniffing, data manipulation etc., you might want to encrypt the communications.
  16 </p>
  17 <p>
  18 For this purpose socat integrates the OpenSSL library and provides SSL client
  19 and server features.
  20 </p>
  21 <p>
  22 SSL is a complex protocol that provides much more features than required for
  23 protecting a single connection; in this document we present only a simple
  24 scenario that provides just the basic security requirements.
  25 </p>
  26
  27 <!-- discussion -->
  28 <h2>Configuring OpenSSL in socat</h2>
  29 <p>
  30 This section shows how the SSL addresses can be configured in socat.
  31 In this docu we only use self signed certificates for the sake of simplicity.
  32 </p>
  33 <p>We assume that the server host is called <tt>server.domain.org</tt> and the
  34 server process uses port 4433. To keep it simple, we use a very simple server
  35 funtionality that just echos data (<tt>echo</tt>), and <tt>stdio</tt> on the
  36 client.</p>
  37 <h3>Generate a server certificate</h3>
  38
  39 <p>Perform the following steps on a trusted host where OpenSSL is
  40 installed. It might as well be the client or server host themselves.</p>
  41 <p>Prepare a basename for the files related to the server certificate:</p>
  42 <span class="frame"><span class="shell">FILENAME=server</span></span>
  43
  44 <p>Generate a public/private key pair:</p>
  45 <span class="frame"><span class="shell">openssl genrsa -out $FILENAME.key 1024</span></span>
  46
  47 <p>Generate a self signed certificate:</p>
  48 <span class="frame"><span class="shell">
  49 openssl req -new -key $FILENAME.key -x509 -days 3653 -out $FILENAME.crt</span></span>
  50 <p>You will be prompted for your country code, name etc.; you may quit all prompts
  51 with the enter key.</p>
  52 <p>Generate the PEM file by just appending the key and certificate files:<p>
  53 <span class="frame"><span class="shell">cat $FILENAME.key $FILENAME.crt &gt;$FILENAME.pem</span></span>
  54
  55 <p>The files that contain the private key should be kept secret, thus adapt
  56 their permissions:<p>
  57 <span class="frame"><span class="shell">chmod 600 $FILENAME.key $FILENAME.pem</span></span>
  58
  59 <p>Now bring the file <tt>server.pem</tt> to the SSL server, e.g. to directory
  60 <tt>$HOME/etc/</tt>, using a secure channel like USB memory stick or SSH. Keep
  61 tight permissions on the file even on the target host, and remove all other
  62 instances of <tt>server.key</tt> and <tt>server.pem</tt>.
  63 </p>
  64 <p>Copy the trust certificate server.crt to the SSL client host, e.g. to directory
  65 <tt>$HOME/etc/</tt>; a secure channel is not required here, and the permissions
  66 are not critical.
  67 </p>
  68
  69 <h3>Generate a client certificate</h3>
  70 <p>First prepare a different basename for the files related to the client certificate:</p>
  71 <span class="frame"><span class="shell">FILENAME=client</span></span>
  72
  73 <p>Repeat the procedure for certificate generation described above.
  74 Copy <tt>client.pem</tt> to the SSL client, and <tt>client.crt</tt> to the
  75 server.</p>
  76
  77 <h3>OpenSSL Server</h3>
  78
  79 <p>Instead of using a tcp-listen (tcp-l) address, we use openssl-listen (ssl-l)
  80 for the server, <tt>cert=...</tt> tells the program to the file containing its
  81 ceritificate and private key, and <tt>cafile=...</tt> points to the file
  82 containing the certificate of the peer; we trust clients only if they can proof
  83 that they have the related private key (OpenSSL handles this for us):<p>
  84 <span class="frame"><span class="shell">socat openssl-listen:4433,reuseaddr,cert=$HOME/etc/server.pem,cafile=$HOME/etc/client.crt echo</span></span>
  85 <p>After starting this command, socat should be listening on port 4433, but
  86 will require client authentication.</p>
  87
  88 <h3>OpenSSL Client</h3>
  89 <p>Substitute your <tt>tcp-connect</tt> or <tt>tcp</tt> address keyword with
  90 <tt>openssl-connect</tt> or just <tt>ssl</tt> and here too add the
  91 <tt>cert</tt> and <tt>cafile</tt> options:<p>
  92 <span class="frame"><span class="shell">socat stdio openssl-connect:server.domain.org:4433,cert=$HOME/etc/client.pem,cafile=$HOME/etc/server.crt</span></span>
  93 <p>This command should establish a secured connection to the server
  94 process.</p>
  95
  96 <h3>TCP/IP version 6</h3>
  97
  98 <p>If the communication is to go over IPv6, the above described commands have
  99 to be adapted; <tt>ip6name.domain.org</tt> is assumed to resolve to the IPv6
 100 address of the server:</p>
 101 <p>Server:</p>
 102 <span class="frame"><span class="shell">socat
 103 openssl-listen:4433,<b style="color:yellow">pf=ip6</b>,reuseaddr,cert=$HOME/etc/server.pem,cafile=$HOME/etc/client.crt echo</span></span>
 104
 105 <p>Client:</p>
 106 <span class="frame"><span class="shell">socat stdio openssl-connect:<b style="color:yellow">ip6name</b>.domain.org:4433,cert=$HOME/etc/client.pem,cafile=$HOME/etc/server.crt</span></span>
 107
 108 <h2>Troubleshooting</h2>
 109
 110 <h3>Test OpenSSL Integration</h3>
 111 <p>
 112 If you get error messages like this:</p>
 113 <table border="1" bgcolor="#e08080"><tr><td><tt>... E unknown device/address "openssl-listen"</tt></td></tr></table>
 114 <p>your socat executable probably does not have the OpenSSL library linked in.
 115 Check socat's compile time configuration with the following command:</p>
 116 <span class="frame"><span class="shell">socat -V |grep SSL</span></span>
 117 <p>Positive output:
 118 <tt>#define WITH_OPENSSL 1</tt><br>
 119 Negative output:
 120 <tt>#undef WITH_OPENSSL</tt><br>
 121 </p>
 122 <p>
 123 In the latter case, make sure you have OpenSSL and its development package
 124 (include files) installed, and check the run of the configure script.
 125 </p>
 126
 127
 128 <h2>History</h2>
 129 <p>
 130 A first OpenSSL client was implemented in socat 1.2.0; it did not support
 131 client certificates and could not verify server certificates. It was rather
 132 considered as a tool for probing typical SSL secured Internet services.
 133 </p>
 134 <p>
 135 From version 1.4.0 on, socat provided experimental support for SSL client and
 136 SSL server, implemented using the OpenSSL libraries. Only TCP/IPv4 transport
 137 was supported. With both SSL client and server, trust certificates for checking
 138 the peers authentication, and certificates for authentication could be
 139 specified. This allowed for non interactive secure connection establishing.
 140 The features were considered experimental; like most Internet sites, socat
 141 server did not require the client to present a certificate per default, but the
 142 client required a server certificate.
 143
 144 </p>
 145 <p>
 146 DSA certificate support is implemented since version 1.4.2.
 147 </p>
 148 <p>
 149 Socat version 1.5.0 extended SSL to TCP/IPv6 transports.
 150 </p>
 151 <p>
 152 With socat version 1.6.0, the SSL server per default requires the client to
 153 present a trusted certificate. socat's OpenSSL implementation still does not
 154 check the contents of a certificate like host name or host address.
 155 </p>
 156
 157 <p>This document was last modified in March 2007.</p>
 158
 159 <h2>More info about socat OpenSSL</h2>
 160
 161 <h3>Links regarding this tutorial</h3>
 162 <a href="socat.html#ADDRESS_OPENSSL_CONNECT">address openssl-connect</a><br>
 163 <a href="socat.html#ADDRESS_OPENSSL_LISTEN">address openssl-listen</a><br>
 164 <a href="socat.html#OPTION_OPENSSL_CERTIFICATE">option cert</a><br>
 165 <a href="socat.html#OPTION_OPENSSL_CAFILE">option cafile</a><br>
 166
 167 <h3>More socat options for OpenSSL addresses</h3>
 168 <a href="socat.html#GROUP_OPENSSL">OpenSSL options</a><br>
 169 <a href="socat.html#GROUP_TCP">TCP options</a><br>
 170 <a href="socat.html#GROUP_IP">IP options</a><br>
 171 <a href="socat.html#GROUP_SOCKET">socket options</a><br>
 172 <a href="socat.html#GROUP_FD">file descriptor options</a><br>
 173 <a href="socat.html#GROUP_RETRY">retry options</a><br>
 174 <p>For openssl-listen only:</p>
 175 <a href="socat.html#GROUP_LISTEN">listen options</a><br>
 176 <a href="socat.html#GROUP_CHILD">child options</a><br>
 177 <a href="socat.html#GROUP_RANGE">range options</a><br>
 178
 179 <h2>References</h2>
 180 <a href="http://www.dest-unreach.org/socat">socat home page</a><br>
 181 <a href="socat.html">socat man page</a><br>
 182 <a href="http://www.openssl.org/">OpenSSL home page</a><br>
 183 <a href="http://www.stunnel.org/">stunnel home page</a><br>
 184 <a href="http://en.wikipedia.org/wiki/Secure_Sockets_Layer">secure sockets layer on Wikipedia</a><br>
 185
 186 <p>
 187 <small>Copyright: Gerhard Rieger 2007</small><br>
 188 <small>License: <a href="http://www.fsf.org/licensing/licenses/fdl.html">GNU Free Documentation License (FDL)</a></small>
 189 </p>
 190
 191 </body>
 192 </html>