Manual Page: tlsproxy.8

NAME

tlsproxy - TLS/SSL helper for Archiveopteryx.

SYNOPSIS

/usr/local/archiveopteryx/sbin/tlsproxy [-f] [-c configfile]

DESCRIPTION

The Archiveopteryx tlsproxy is a separate process which performs TLS and SSLv3 processing on behalf of archiveopteryx(8). TLS processing is kept separate from these other servers for architectural reasons:

TLS occasionally causes processing delays, for example while regenerating keys. Since most of Archiveopteryx is event-driven, these delays would block other users.

Further, there is a lot of code in cryptlib, which we prefer not to link into all of our servers.

tlsproxy should always be running when Archiveopteryx is in use, but you should never need to interact with it directly.

OPTIONS

-c filename

Read configuration variables from filename instead of from /usr/local/archiveopteryx/archiveopteryx.conf.

-f

Fork into background during startup.

CONFIGURATION

tlsproxy is configured using archiveopteryx.conf(5).

The configuration variables specific to this server are use-tls, tls-certificate, tls-certificate-label, tls-certificate-secret, tlsproxy-address, and tlsproxy-port. Other variables may be consulted to determine how to connect to the log server, how to secure the server, and so on.

tlsproxy uses a private key and certificate from a PKCS #15 key file. The location of the key file is specified by tls-certificate. The key is uniquely identified by the tls-certificate-label, and encrypted with the tls-certificate-secret.

The default configuration enables the use of TLS with an automatically-generated, self-signed certificate. This certificate is generated once at startup, stored in /usr/local/archiveopteryx/lib/automatic-key.p15 by default (using the hostname as a certificate label), and reused on subsequent occasions. If the certificate expires, or becomes unusable for any reason (e.g. the hostname changes), it will be regenerated the next time tlsproxy starts up.

DEPENDENCIES

On startup, tlsproxy needs to be able to connect to logd.

DIAGNOSTICS

In case of error, tlsproxy exits with exit code 1, an error message on stderr and (usually more detailed) information in the log file.

CERTIFICATE HANDLING

Tlsproxy can use a proper certificate signed by a CA, as usual. If you do not have one, tlsproxy will generate a self-signed certificate at startup. No clients trust this certificate, but we think it's better to have a self-signed certificate than to not use TLS.

Oryx strongly recommends getting a proper signed certificate. Using the dynamically generated certificate preserves some of the advantages of TLS, but far from all.

If you have a private key in OpenSSL format, you can convert it to a PKCS #15 key file that tlsproxy can use with the pemtrans program, available from http://www.oryx.com/ams/pemtrans.html.

FILES

/usr/local/archiveopteryx/lib/automatic-key.p15

is used to store the automatically generated key and certificate.

AUTHOR

The Archiveopteryx developers, info@oryx.com.

VERSION

This man page covers Archiveopteryx version 2.09, released 2008-05-12, http://www.archiveopteryx.org/2.06