Configuration.acceptTLS()

Description

Appends an acceptTLS filter to the current pipeline layout.

An acceptTLS filter implements TLS protocol on the server side.

INPUT - TLS-encrypted Data stream received from the client.
OUTPUT - TLS-encrypted Data stream to send to the client.
SUB-INPUT - Data stream received from the client after TLS decryption.
SUB-OUTPUT - Data stream to send to the client before TLS encryption.

An acceptTLS filter does the following:

First, it handles a TLS handshake by reading handshake messages from the client via its input and sending messages back to the client via its output
After the handshake is done, it goes on reading and decrypting the Data stream from the filter's input and pumping the decrypted Data stream to a newly created sub-pipeline
Output from that sub-pipeline will be encrypted and sent back to the client via the filter's output

Certificate and private key

The certificate option in the options parameter is required for this filter. It can be an object with two properties:

cert - a crypto.Certificate or crypto.CertificateChain
key - a crypto.PrivateKey

It can also be a function that returns the above object. In this case, the function will have a serverName parameter as its input, by which you get to provide different certificates for different SNI names.

Mutual TLS

To enable mTLS, give an array of crypto.Certificate objects to the trusted option in the options parameter. Only clients holding a certificate presented in that list are allowed in the handshake process.

ALPN

You can provide a callback function to the alpn option in the options parameter. During TLS handshake, this function gets called with an array of protocol names offered by the client and is expected to return the index of the selected protocol in that array.

For example,

pipy()
  .listen(8443)
  .acceptTLS({
    certificate: {
      // ...
    },
    // Select HTTP/2 if requested, or HTTP/1.1
    alpn: names => (
      ((names.indexOf('h2')+1) || (names.indexOf('http/1.1')+1)) - 1
    )
  }).to('tls-offloaded')

You can also simply give an array of strings to this option, telling what protocols should be accepted during TLS handshake.

pipy()
  .listen(8443)
  .acceptTLS({
    certificate: {
      // ...
    },
    alpn: ['http/1.1', 'h2']
  }).to('tls-offloaded')

If nothing is provided, or the callback function returns an invalid index, the first protocol requested by the client side would be chosen.

Handshake callback

A handshake callback function can be given to the handshake option in the options parameter. This function will be called after handshake completes. The protocol that is chosen after protocol negotiation is passed as a string parameter to the callback.

Syntax

pipy()
  .pipeline()
  .acceptTLS({
    certificate: {
      cert, // crypto.Certificate or crypto.CertificateChain
      key,  // crypto.PrivateKey
    },
    trusted: [
      ...trustedCerts // array of crypto.Certificate
    ],
    verify: (ok, cert) => onVerifyPeerCertificate(cert),
    alpn: [...allowedProtocols],
    handshake: (chosenProtocol) => onHandshakeComplete(chosenProtocol),
  }).to(
    subPipelineLayout
  )

Parameters

acceptTLS(options?)

options?

Options including:

certificate - (required) An object containing cert and key or a function that returns such an object after receiving sni for the requested server name. In both cases, cert can be a crypto.Certificate or a crypto.CertificateChain and key must be a crypto.PrivateKey.
trusted - (optional) An array of crypto.Certificate objects for allowed client certificates.
verify - (optional) A callback function that gets called for each certificate in the peer's certificate chain. It receives 2 arguments: ok and cert, where ok is a boolean indicating whether pre-verification is fine, and cert is the Certificate object being verified. It is expected to return true if verification should go on, or false if the TLS connection should be rejected.
alpn - (optional) An array of allowed protocol names, or a function that receives an array of client-preferred protocol names and returns the index of the server-chosen protocol in that array.
handshake - (optional) A callback function that receives the negotiated protocol name after handshake.

Return Value

The same Configuration object.

Example

pipy()

  .listen(8443)
  .acceptTLS({
    certificate: {
      // Suppose we have server-cert.pem and server-key.pem in 'secret' folder
      cert: new crypto.Certificate(pipy.load('secret/server-cert.pem')),
      key: new crypto.Certificate(pipy.load('secret/server-key.pem')),
    }
  }).to(
    $=>$.serveHTTP(
      new Message('Hello, TLS!\n')
    )
  )