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