NAME

tlstunnel -- Forward TLS/DTLS connections as TCP/UDP/SCTP, and vice versa.

SYNOPSIS

tlstunnel -c|-s [-u|-t|-x #|-y #] -l id [-r id] [-S path] inaddr inport fwaddr fwport

DESCRIPTION

The tlstunnel command wraps TLS around connections that are otherwise
plaintext.  This cannot used for protocols that do STARTTLS in the
course of their protocol interactions; it is purely meant to support
protocols that iniatiate TLS immediately over newly established
connections; for example, a HTTPS connection wraps TLS around a plain
HTTP connection.

The tunnel can be built up using either TLS or DTLS, the latter of which
is the datagram variety of normal, stream-oriented TLS.  When relaying
a TCP connection, TLS is the only available option; when relaying a
UDP connection, DTLS is the only available option; when relaying an
SCPT connection, both varieties are possible but DTLS is advised for
efficiency reasons.

The tunnel runs in either client or server mode.  Used as a client, the
service listens for plain text connections made to address inaddr and
port inport, wraps them in TLS as a client and forwards the connection
to address fwaddr and fwport.  When used as a server, the same thing
is done, however the wrapping of TLS is changed to unwrapping of TLS.
Addresses are written as IPv6 addresses, with backward compatibility to
IPv4 through the prefixing of :: in front of an IPv4 address.  It is
not required that inaddr and fwaddr are of the same IP version.

The end points authenticate, and are authorized, as configured in the
system-wide TLS Pool configuration settings.  These settings ensure a
consistent default behaviour for all TLS Pool connections.  These
settings include certificate capabilities and visibilities.


OPTIONS

-c | --client

        Run the TLS Tunnel as a client, meaning that it is connected to by
        a plaintext connection and forwarded as a TLS-wrapped variety.

        Client authentication and authorization are implemented as specified
        in the TLS Pool configuration.  This includes choice of certificates
        and settings about their visibility.

-s | --server

        Run the TLS Tunnel as a server, meaning that it is connected to by
        a TLS-wrapped connection and forwarded as a plaintext variety.

        Client authentication and authorization are implemented as specified
        in the TLS Pool configuration.  This includes choice of certificates
        and settings about their visibility.

-t | --tcp | --tcp-tls

        Listen to, and forward as, TCP connection.  The secure wrapping
        is implemented through stream-oriented TLS.

        This is also the default option, selected when none of --tcp-tls,
        --udp-dtls, --sctp-tls or --sctp-dtls has been supplied.

-u | --udp | --udp-dtls

        THIS FEATURE IS NOT IMPLEMENTED.  The semantics cannot be clearly
        defined, because UDP has no notion of a connection, while TLS does
        need it to keep state.  Rather than implementing guesses here and
        load it with configuration options such as timeouts, it is advised
        to implement DTLS directly in the UDP application.

-x stream | --sctp-dtls stream

        Listen to, and forward as, SCTP.  The secure wrapping
        is implemented through frame-oriented DTLS, as advised for
        SCTP because that retains the indepent delivery that SCTP offers.

        The stream is the number of the stream withing SCTP over which the
        DTLS negotiations are made.

-y stream | --sctp-tls stream

        Listen to, and forward as, SCTP.  The secure wrapping
        is implemented through stream-oriented TLS, which is not advised for
        SCTP but which may nonetheless be used by a protocol implementation.

        The stream is the number of the stream withing SCTP over which the
        TLS negotiations are made.

-L id | --local-id id

        Set the local identity.  This should be of the form of a domain
        name, or user@domainname.  This paramater is required.

-R id | --remote-id id

        Constrain the remote identity.  This should be of the form of a domain
        name, or user@domainname.  This parameter is optional.

-S path | --tlspool-socket-path path

        Override the built-in default path for the socket pool.  This can be
        used to address a specific instance of the TLS Pool, for instance one
        that is run under a personal account, accessing a personally held
        PKCS #11 token.


LIMITATIONS

The TLS Pool can handle various options when connecting to a remote site.
These options have not yet been implemented as commandline switches, so
this level of refinement cannot be added when using a TLS Tunnel.

The TLS Pool usually negotiates local and remote identities as part of
the authentication and authorization procedures.  These procedures do not
interface optimally with the TLS Tunnel, because there is no place to
leave this information.  What has been implemented is the mandatory
-l option that sets the local identifier to use, and an optional -r option
tp constrain the remote identity.

Note that the TLS Tunnel does not implement a PIN entry interface; this
is a function that is separately coordinated with the TLS Pool, so it can
bring up a dialog in a trusted environment, making it easier to secure than
any per-command PIN entry dialog.

Where TLS and even DTLS have a notion of connection state, necessary for the
management of things like session keys, there is no concept of a connection
for UDP transmission.  For this reason, the UDP variant of this tool has not
been implemented; it would involve close-to-NAT practices that can easily
lead to confusion.

AUTHOR

Written by Rick van Rein of OpenFortress.

SEE ALSO

tlspool