This document is obsoleted by "A universal TLS gateway by DeleGate" which is applicable to DeleGate/9.0.1 or later upgraded with the following merits:

DeleGateLogo A universal SSL proxy by DeleGate

Yutaka Sato
April 30, 1998 (last updated June 19, 2002)

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 like follows:
1. placed following files at DGROOT/lib/ directory.

    sslway
    server-key.pem
    server-cert.pem

2. invoked DeleGate with following parameters:

    delegated \
        -P443 \
        SERVER=https \
        FCL=sslway \
        RELIABLE="*" \
        MOUNT="/* http://localhost/*" \
        REACHABLE=localhost

USAGE

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

    FMD=sslway   ... connect to upstream DeleGate with SSL

    FCL=sslway   ... accept from SSL clients (including DeleGate)
OPTIONS

    -cert file -- certificate (possibly with private key) of this SSLway to be shown to a peer
    -key file -- private key file (if not included in the -cert file)
    -pass arg -- the source of passphrase for key (pass:string or file:path) [default: keyfile.pas]

    -CAfile file -- the name of file contains a CA's certificate
    -CApath dir -- directory contains CA's certificate files hashed with c_rehash

    -Vrfy -- peer's certificate must be shown and must be authorized
    -vrfy -- peer's certificate, if shown, must be authorized
    -Auth -- peer must show its certificate, but it can be unauthorized
    -auth -- just record the peer's certificate, if exists, into log (equals to obsoleted "-client_auth")

    -co  apply SSL for the connection to the server [default for FSV]
    -ac  aplly SSL for the accepted connection from the client [default for FCL]
    -ad  accept either SSL or through by auto-detection of SSL-ClientHello
    -ss  negotiate by AUTH SSL for FTP (implicit SSL for data-connection)
    -st  accept STARTTLS (protocol is auto-detect) and SSL tunneling
    -St  require STARTTLS first (protocol is auto-detect) and PBSZ+PROT for FTP
    -{ss|st|St}/protocol enable STARTTLS for the protocol {SMTP,POP,IMAP,FTP}

Necessary files which contain certificate and key in PEM format should be placed at somewhere in LIBPATH (DGROOT/lib/ typically), otherwise the location of those files must be indicated by "-cert filename" option for the sslway command. When a key file keyfile.pem is encrypted, the passphrase must be given in a file named keyfile.pas, or by -pass argument. The certificate is mandatory when you run the sslway with FCL or when you run the sslway with FSV or FMD and the target server requires client's certificate.

EXAMPLES

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

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

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

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

    delegated -v -P1080 FSV=sslway SERVER=socks

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

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

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

    delegated -v -P8023 FCL=sslway SERVER=telnet://telnet-server
Making a bare Telnet client be a Telnet/SSL client:
    delegated -v -P8023 FSV=sslway SERVER=telnet://telnet-delegate
Making a bare POP server be a POP/SSL server:
    delegated -v -P8110 FSV=sslway SERVER=pop://pop-server
DeleGate as a POP proxy which connects to arbitrary POP servers with SSL:
    delegated -v -P8110 FSV=sslway SERVER=pop
Encrypting the communication between client/server of arbitrary protocol on TCP:
    delegated -v -P8000 FSV=sslway SERVER=tcprelay://delegate:8000
    delegated -v -P8000 FCL=sslway SERVER=tcprelay://server-host:port
Encrypting the communication between NNTP client/server with SSL:
    delegated -v -P8119 FSV=sslway SERVER=nntp://nntp-delegate:8119
    delegated -v -P8119 FCL=sslway SERVER=nntp://nntp-server
Encrypting the communication between DeleGates with SSL:
    delegated -v -P8080 FMD=sslway MASTER=delegate-host:8888
    delegated -v -P8888 FCL=sslway
Making a bare HTTP server be a HTTPS/SSL server:
    delegated -v -P8080 FCL=sslway SERVER=https MOUNT="/* http://http-server/*"
Making a NNTP/HTTP gateway server for HTTPS/SSL clients:
    delegated -v -P8080 FCL=sslway 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:FSV:https:*:*"
Apllying SSLway only for specified servers:
    delegated -v -P8023 CMAP="sslway:FSV:telent:server-list:*" SERVER=telnet
Accepting clients of FTPS (starting SSL without negotiation):
    delegated FCL=sslway SERVER=ftp 
Connecting to severs of FTPS (starting SSL without negotiation):
    delegated FSV=sslway SERVER=ftp 
Accepting clients of FTP/SSL (on-demand SSL by "AUTH TLS" negotiation):
    delegated CMAP=sslway:FCL:ftp-data CMAP="sslway -St:FCL:ftp" SERVER=ftp 
DeleGate as a SSLwrapper:
    delegated -v -P8079 FCL=sslway 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. edit SSLEAY variable in filters/Makefile.go, which is defined as SSLEAY=../../SSL by default, to point the directry which contains SSL library files (libssl.a, libcrypto.a and libRSAglue.a) of SSLeay or OpenSSL.
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://www.delegate.org/pub/DeleGate/bin/windows/latest/. Note that an executable of a DeleGate, delegated in above examples, is named with its version number like "DG6_1_18.EXE".

Making DeleGate by yourself for your platform (Unixes, OS/2 and Win32) is easy as shown in ftp://www.delegate.org/pub/DeleGate/README.MAKE. Just get a distribution package at ftp://www.delegate.org/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: Feb 15, 2000]


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