minssl
Software
www.skarnet.org

The minssl program

minssl turns a clear communication channel into an encrypted one, together with minssld. minssl is the client-side program.

minssl is a UCSPI client proxy application: it runs as a UCSPI client application and execs into another UCSPI client application.

Interface

     minssl prog...

• minssl speaks with the network on file descriptors 6 (for reading) and 7 (for writing).
• It expects to read a public host key, a public session key, and a digital signature, in binary form, from a remote minssld server program.
• It sets the MINSSLREMOTEHOSTPUBKEY environment variable to the public host key.
• If the MINSSL_KEY_MANAGER environment variable is set, then:
  • minssl spawns a child that runs the $MINSSL_KEY_MANAGER program
  • minssl waits for that child to exit. If the child's exit code is not 0, then it dies with the same exit code.
  
  The program named by $MINSSL_KEY_MANAGER should follow the minssl key manager interface; the minssl-keymgr-dir program is suitable as a minssl key manager. You should always be using a key manager.
• minssl checks the digital signature against the public host key. If it cannot assert the validity of the signature, it dies.
• The server is now authenticated. minssl performs a Diffie-Hellman exchange on the NIST P-224 elliptic curve to share a secret with the remote minssld process.
• minssl spawns a prog... child.
• minssl execs into minssl-tunnel, which takes care of the network connection. If the MINSSL_TIMEOUT environment variable is set, minssl passes its value to minssl-tunnel as timeout. If minssl runs as root, it tries to drop its privileges before executing minssl-tunnel. The user it runs as is set at compile-time: it is MINSSL_TUNNEL_USER in src/tunnel/minssl.h.
• What prog writes on its descriptor 7 is fed to minssl-tunnel, which turns it to ciphertext and writes it to the network. What arrives on the network is read by minssl-tunnel, which deciphers it and feeds it to prog on descriptor 6.

The details of data exchange between minssl and minssld are described in the protocol description.

Common use

minssl does not contact the network itself. It is designed to be run under some UCSPI client such as tcpclient. For instance, the command line

     tcpclient host port minssl prog...

establishes a secure connection to host:port then runs prog.... The minsslclient program is an easy way of combining tcpclient with minssl.