DeleGateLogo A universal SSL proxy by DeleGate

Yutaka Sato
April 30, 1998

Various TCP based application protocols relayable by DeleGate (HTTP, NNTP, POP, Telnet, Socks, etc.) now can be encrypted with SSL. Mediated by DeleGate, non-SSL clients can talk to SSL servers, and non-SSL servers can talk with SSL clients.

SSL encryption and decryption is achieved at external filter attached to DeleGate so that DeleGate itself has nothing to do with SSL. Because SSL is a bi-directional protocol, bi-directional type filters of DeleGate (FCL, FSV, and FMD) are used. FCL-filter may be inserted between SSL-clients and DeleGate to accept a SSL connection. FSV-filter may be inserted between DeleGate and SSL-servers to establish a SSL connection. Communication on an application protocol is decrypted or encrypted when it passes through these filters. Communication bound for DeleGate is decrypted whereas communication comes from DeleGate is encrypted.

sslway-structure

This SSL encryption/decryption filter for DeleGate is named SSLway. SSLway is invoked by DeleGate as a bi-directional filter. The bi-directional external-filter mechanism and SSLway filter program have been applicable to Win32 and OS/2 as well as Unix since DeleGate/5.3.2.

SSLeayLogo SSLway is made on the top of SSLeay.

DEMO

The gateway is configured with following parameters:
HERE=`pwd`
export SSL_SERVER_KEY_FILE; SSL_SERVER_KEY_FILE=$HERE/server-key.pem
export SSL_SERVER_CERT_FILE; SSL_SERVER_CERT_FILE=$HERE/server-cert.pem
delegated \
        -P443 \
        RELIABLE="*" \
        REACHABLE=localhost \
        SERVER=https \
        MOUNT="/* http://localhost/*" \
        FCL="$HERE/sslway -ac"

USAGE

To make DeleGate work with SSLway, specify it in FSV or FCL parameter of DeleGate. Basically, there are two ways of SSLway usage:
    FSV="sslway -co"   ... SSLway to connect to SSL servers

    FCL="sslway -ac"   ... SSLway to accept from SSL clients
The location of files which contain certificate and key in PEM format must be indicated in environment variable "SSL_CERT_FILE=filename" or "-cert filename" command line option. This will be mandatory when you run the sslway with "-ac", or when you run the sslway with "-co" and the target server requires client's certificate.
You might need to specify cipher list with "SSL_CIPHER=cipher-list" environment or "-cipher cipher-list" option. If you wish to see client's certificate in SSLway with "-ac" option, specify "-client_auth" option.

EXAMPLES

DeleGate as a Telnet proxy which connects to arbitrary servers with SSL:
    delegated -v -P8023 FSV="sslway -co" SERVER=telnet REMITTABLE=telnet

DeleGate as a HTTPS server which relayes from POP server to the client:

    delegated -v -P8080 FCL="sslway -ac" SERVER=https MOUNT="/* pop://popserver/*"

DeleGate as a SocksV4 server which connects to arbitrary servers with SSL:

    delegated -v -P1080 FSV="sslway -co" SERVER=socks

DeleGate as a Telnet proxy which connects to servers via Socks with SSL:

    delegated -v -P8023 FSV="sslway -co" SERVER=telnet CONNECT=socks SOCKS=socks-server

Making a bare Telnet server be a Telnet/SSL server:

    delegated -v -P8023 FCL="sslway -ac" SERVER=telnet://telnet-server
Making a bare Telnet client be a Telnet/SSL client:
    delegated -v -P8023 FSV="sslway -co" SERVER=telnet://telnet-delegate
Making a bare POP server be a POP/SSL server:
    delegated -v -P8110 FSV="sslway -ac" SERVER=pop://pop-server
DeleGate as a POP proxy which connects to arbitrary POP servers with SSL:
    delegated -v -P8110 FSV="sslway -co" SERVER=pop
Encrypting the communication between client/server of arbitrary protocol on TCP:
    delegated -v -P8000 FSV="sslway -co" SERVER=tcprelay://delegate:8000
    delegated -v -P8000 FCL="sslway -ac" SERVER=tcprelay://server-host:port
Encrypting the communication between NNTP client/server with SSL:
    delegated -v -P8119 FSV="sslway -co" SERVER=nntp://nntp-delegate:8119
    delegated -v -P8119 FCL="sslway -ac" SERVER=nntp://nntp-server
Encrypting the communication between DeleGates with SSL:
    delegated -v -P8080 FMD="sslway -co" MASTER=delegate-host:8888
    delegated -v -P8888 FCL="sslway -ac"
Making a bare HTTP server be a HTTPS/SSL server:
    delegated -v -P8080 FCL="sslway -ac" SERVER=https MOUNT="/* http://http-server/*"
Making a NNTP/HTTP gateway server for HTTPS/SSL clients:
    delegated -v -P8080 FCL="sslway -ac" SERVER=https MOUNT="/* nntp://nntp-server/*"
DeleGate as a http proxy which make a bare HTTP client be a HTTPS/SSL client:
    delegated -v -P8080 CMAP="sslway -co:FSV:https:*:*"
Apllying SSLway only for specified servers:
    delegated -v -P8023 CMAP="sslway -co:FSV:telent:server-list:*" SERVER=telnet
DeleGate as a SSLwrapper:
    delegated -v -P8079 FCL="sslway -ac" SERVER=exec XCOM=/usr/etc/in.fingerd

HOW TO MAKE SSLWAY

1. do "make" at DeleGate's directory (you will get src/delegated and lib/lib*.a)
2. copy SSLeay's ssl.o and crypto.o to filters/ directory of DeleGate.
3. do "make -f Makefile.go sslway" at filters/ directory.

Then you will get an executable file of sslway at the directory.

Executables of DeleGate and SSLway for Win32 will be available at ftp://wall.etl.go.jp/pub/DeleGate/bin/windows/latest/. Note that an executable of a DeleGate, delegated in above examples, is named with its version number like "DG5_3_2.EXE".

Making DeleGate by yourself for your platform (Unixes, OS/2 and Win32) is easy as shown in ftp://wall.etl.go.jp/pub/DeleGate/README. Just get a distribution package at ftp://wall.etl.go.jp/pub/DeleGate/, unpack it, then say "make".

DEVELOPING SSLWAY BY YOURSELF

You can develop your own SSLway or other external filters (SSHway for example :-). The external filter of DeleGate is a kind of simple API to add functional extension to DeleGate. There are two types of external filters; one-way filters (FFROMCL, FTOCL, FTOSV, FFROMSV, FTOMD and FFROMMD) and bi-directional filters (FCL, FSV and FMD).

A bi-directional filter like SSLway is given two sockets which are assigned file descriptor number 0 and 1. The descriptor 0 is bound for the client side socket, and number 1 is bound for the server side. On platforms such as Win32 and OS/2 where socket cannot be inherited or treated as standard I/O in child process, the CFI_init() function must be called at the beginning of filter programs. You must link library.a and libsubst.a under lib/ directory of DeleGate to use this function. The Makefile, sslway.c and bdtee.c under filters/ directory may be helpful to understand how to make bi-directional filter programs.

Similarly, one-way filters are given two file descriptors assigned number 0 and 1 bound for its input and output respectively. On platforms where socket cannot be inherited or treated as standard I/O in child process, these descriptors are redirected to pipe bound for DeleGate which relays it to socket. Therefore, any existing filter programs can be attached to DeleGate as is.

These external filters will be given information about connection to the client in environment variables REMOTE_HOST, REMOTE_ADDR and REMOTE_IDENT which is defined in CGI specification.

You may wish to select filters to be applied on specific condition. There are two ways to do such a conditional filter application. A set of CMAP parameters shown in the above example is a way; each CMAP parameter specifies a filter to be applied based on circuit-level information. Another way is the CFI script which describes filter selection based on information in (MIME based) message headers of the application protocol. The CFI is uniformly applicable to application protocols which have a message format based on MIME or RFC822 such as HTTP, NNTP, SMTP and POP. There is a half done document on CFI usage, but only in Japanese ;-)

[Last updated: May 12, 1998]


figure-of-frog Yutaka Sato <ysato@etl.go.jp> Electrotechnical Laboratory (ETL), AIST, MITI, Japan