Update release date.
[aox:aox.git] / doc / tlsproxy.man
1 .\" Copyright 2009 The Archiveopteryx Developers <info@aox.org>
2 .TH tlsproxy 8 2009-07-13 aox.org "Archiveopteryx Documentation"
3 .SH NAME
4 tlsproxy - TLS/SSL helper for Archiveopteryx.
5 .SH SYNOPSIS
6 .B $SBINDIR/tlsproxy [-f] [-c configfile]
7 .SH DESCRIPTION
8 .nh
9 .PP
10 The Archiveopteryx
11 .B tlsproxy
12 is a separate process which performs TLS and SSLv3 processing on behalf of
13 .BR archiveopteryx (8).
14 TLS processing is kept separate from these other servers for
15 architectural reasons:
16 .PP
17 TLS occasionally causes processing delays, for example while
18 regenerating keys. Since most of Archiveopteryx is event-driven, these
19 delays would block other users.
20 .PP
21 Further, there is a lot of code in cryptlib, which we prefer not to
22 link into all of our servers.
23 .PP
24 .B tlsproxy
25 should always be running when Archiveopteryx is in use, but you should
26 never need to interact with it directly.
27 .SH OPTIONS
28 .IP "-c filename"
29 Read configuration variables from
30 .I filename
31 instead of from
32 .IR $CONFIGDIR/archiveopteryx.conf .
33 .IP -f
34 Fork into background during startup.
35 .SH CONFIGURATION
36 .B tlsproxy
37 is configured using
38 .BR archiveopteryx.conf (5).
39 .PP
40 The configuration variables specific to this server are
41 .IR use-tls ,
42 .IR tls-certificate ,
43 .IR tls-certificate-label ,
44 .IR tls-certificate-secret ,
45 .IR tlsproxy-address ,
46 and
47 .IR tlsproxy-port .
48 Other variables may be consulted to determine how to connect to the log
49 server, how to secure the server, and so on.
50 .PP
51 .B tlsproxy
52 uses a private key and certificate from a PKCS #15 key file. The
53 location of the key file is specified by
54 .IR tls-certificate .
55 The key is uniquely identified by the
56 .IR tls-certificate-label ,
57 and encrypted with the
58 .IR tls-certificate-secret .
59 .PP
60 The default configuration enables the use of TLS with an
61 automatically-generated, self-signed certificate. This certificate is
62 generated once at startup, stored in
63 .I $LIBDIR/automatic-key.p15
64 by default (using the hostname as a certificate label), and reused on
65 subsequent occasions. If the certificate expires, or becomes unusable
66 for any reason (e.g. the hostname changes), it will be regenerated the
67 next time tlsproxy starts up.
68 .SH DEPENDENCIES
69 On startup,
70 .B tlsproxy
71 needs to be able to connect to
72 .BR logd .
73 .SH DIAGNOSTICS
74 In case of error,
75 .B tlsproxy
76 exits with exit code 1, an error message on stderr and (usually more
77 detailed) information in the log file.
78 .SH "CERTIFICATE HANDLING"
79 .B Tlsproxy
80 can use a proper certificate signed by a CA, as usual. If you
81 do not have one,
82 .B tlsproxy
83 will generate a self-signed certificate at startup. No clients trust
84 this certificate, but we think it's better to have a self-signed
85 certificate than to not use TLS.
86 .PP
87 We strongly recommend that you get a proper signed certificate. Using
88 the dynamically generated certificate preserves some of the advantages
89 of TLS, but far from all.
90 .PP
91 If you have a private key in OpenSSL format, you can convert it to a
92 PKCS #15 key file that
93 .B tlsproxy
94 can use with the
95 .I pemtrans
96 program, available from
97 .IR http://toroid.org/ams/pemtrans .
98 .SH FILES
99 .IP $LIBDIR/automatic-key.p15
100 is used to store the automatically generated key and certificate.
101 .SH AUTHOR
102 The Archiveopteryx Developers, info@aox.org.
103 .SH VERSION
104 This man page covers Archiveopteryx version 3.1.2, released 2009-07-13,
105 http://www.archiveopteryx.org/3.1.2
106 .SH SEE ALSO
107 .BR archiveopteryx (8),
108 .BR archiveopteryx.conf (5),
109 .BR deliver (8),
110 .BR logd (8),
111 http://www.archiveopteryx.org