From 47cbbb1619ace4013856843ef8f7d68279c74faa Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sun, 22 Nov 2020 00:16:06 +0000 Subject: Add documentation, fix tiny privdrop bug --- doc/s6-tlsc.html | 197 +++++++++++++------------------------------------------ 1 file changed, 44 insertions(+), 153 deletions(-) (limited to 'doc/s6-tlsc.html') diff --git a/doc/s6-tlsc.html b/doc/s6-tlsc.html index 1237460..c2e7521 100644 --- a/doc/s6-tlsc.html +++ b/doc/s6-tlsc.html @@ -20,21 +20,12 @@

s6-tlsc is a program that establishes a TLS or SSL -client connection over an existing TCP connection, then spawns -an application. It is meant to make network communications +client connection over an existing TCP connection, then execs +into an application. It is meant to make network communications secure even for applications that do not natively support TLS/SSL.

-

- s6-networking does not include -cryptographic software. All the crypto used in s6-tlsc -is provided by the chosen SSL backend: -BearSSL or -LibreSSL, depending on -the options given when configuring s6-networking. -

-

Interface 

@@ -45,60 +36,25 @@ the options given when configuring s6-networking.
  
  •  s6-tlsc expects to have an open TCP connection it
 can talk to on its (by default) descriptors 6 (for reading)
 and 7 (for writing). 
    • 
- 
  •  It spawns prog... as a child process,
-interposing itself between it and the network. 
    • 
- 
  •  It initiates a TLS/SSL handshake over the
-network connection, expecting a TLS/SSL server on the other
-side. 
    • 
- 
  •  It manages the encryption/decryption of all the
-messages between prog and the server.
-prog speaks plaintext, but only ciphertext is sent
-on the network. 
    • 
- 
  •  When prog exits, s6-tlsc exits.
+ 
  •  It spawns a s6-tlsc-io
+child process that will initiate the TLS connection, perform the
+handshake (expecting a TLS server on the other side of the
+network) and maintain the TLS tunnel. 
    • 
+ 
  •  When notified by s6-tlsc-io
+that the handshake has completed, s6-tlsc execs into
+prog.... 
    • 
 
 
 
     Exit codes 
    
 
 
 
 
    
- If the TLS/SSL connection closes cleanly, s6-tlsc
-waits for prog to exit, then exits with an
-approximation
-of prog's exit code.
-
    
-
-
     Protocol version and parameters 
    
-
-
    
- During the TLS/SSL handshake, s6-tlsc tries
-every version of the protocol that is supported by the
-backend, with all supported algorithms and cipher suites;
-the backend normally ensures that the most secure combination
-is tried first, with slow degradation until the client and
-the server agree.
-
    
-
-
-
-
    
- As a client, it is better for s6-tlsc to adapt to as many servers
-as possible, that's why it adopts a liberal approach to protocol
-versions.
+ If everything goes smoothly, s6-tlsc does not exit, but execs
+into prog... instead.
 
    
 
 
     Environment variables 
    
@@ -106,110 +62,44 @@ versions.
 
     Read 
    
 
 
    
- s6-tlsc expects to have one of the
-CADIR or CAFILE environment variables set.
-It will refuse to run if both are unset. If both are set,
-CADIR has priority. The value of that variable is:
+ s6-tlsc does not expect to have any particular
+environment variables, but it spawns a
+s6-tlsc-io program that does.
+So it should pay attention to the following variables:
 
    
 
 
 
-
    
- If you are using client certificates, s6-tlsc also reads
-two more environment variables: KEYFILE contains
-the path to a file containing the private key, DER- or
-PEM-encoded; and CERTFILE contains the path to
-a file containing the client certificate, DER- or
-PEM-encoded.
-
    
-
-
    
- If s6-tlsc is run as root, it can also read two
-other environment variables, TLS_UID and TLS_GID,
-which contain a numeric uid and a numeric gid; s6-tlsc
-then drops its root privileges to this uid/gid after spawning
-prog.... This ensures that the TLS/engine and the
-application run with different privileges. Note that prog...
-should drop its own root privileges by its own means: the
-s6-applyuidgid
-program is a way of doing it.
-
    
-
 
     Written 
    
 
 
    
- Unless the -Z option has been given to
-s6-tlsc, prog... is run with all the
-TLS/SSL variables unset: CADIR, CAFILE,
-KEYFILE, CERTFILE, TLS_UID and TLS_GID. The goal is
-for s6-tlsc to be, by default, as invisible
-as possible.
-
    
-
-
     Server name determination for SNI 
    
-
-
    
- The -k servername option is important to
-s6-tlsc: it tells it to send servername
-as the name to require a certificate for.
-Not setting this option allows s6-tlsc to
-proceed without SNI,
-which may be a security risk.
+ By default, prog... is run with all these
+variables unset: CADIR, CAFILE,
+KEYFILE, CERTFILE, TLS_UID and TLS_GID. They're passed to
+the s6-tlsc-io child but
+not to prog....
+The -Z option prevents that behaviour.
 
    
 
 
    
- The s6-tlsclient program can
-automatically craft a -k option for s6-tlsc
-if the host argument that is given to it is a
-host name. But if you're invoking s6-tlsc directly,
-do not forget to give it this option.
-
    
-
-
     SSL close handling 
    
-
-
    
- If prog initiates the end of the session by sending
-EOF, there are two ways for the TLS/SSL layer to handle it.
+ However, prog... is run with the following additional
+environment variables:
 
    
 
 
 
-
    
- Nowadays (2017), most protocols are auto-terminated, so
-it is not dangerous anymore to use EOF tranmission, and that
-is the default for s6-tlsc. Nevertheless, by
-using the -S option, you can
-force it to use the close_notify method if your
-application requires it to be secure.
-
    
-
-
     s6-tlsc options 
    
+
     Options 
    
 
 
 
 
     Notes