Configuration.connectTLS()

Description

Appends a connectTLS filter to the current pipeline layout.

A connectTLS filter implements TLS protocol on the client side.

INPUT - Data stream to send to the server via TLS.
OUTPUT - Data stream received from the server via TLS.
SUB-INPUT - TLS-encrypted Data stream to send to the server.
SUB-OUTPUT - TLS-encrypted Data stream received from the server.

A connectTLS filter does the following:

First, it initiates and carries out a TLS handshake with the server via a newly created sub-pipeline
After the handshake is done, it goes on reading and encrypting Data stream from the filter's input and pumping the encrypted Data stream to the sub-pipeline
The sub-pipeline's output, which is encrypted Data stream received from the server, is decrypted before coming out from the filter's output

SNI

As the client side in a TLS communication, you can specify the SNI server name by option sni in the options parameter. It can be a string or a function that returns a string.

ALPN

ALPN is supported by specifying protocols the client side prefers in alpn option of the options parameter. It can be a string or an array of strings.

Mutual TLS

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

The certificate option in the options parameter is also required on the client side if mutual TLS is being used. It can be an object with the following properties, or a function that returns that object:

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

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()
  .connectTLS().to(
    subPipelineLayout
  )

pipy()
  .pipeline('example')
  .connectTLS({
    certificate: {
      cert, // crypto.Certificate or crypto.CertificateChain
      key,  // crypto.PrivateKey
    },
    trusted: [
      ...trustedCerts // array of crypto.Certificate
    ],
    verify: (ok, cert) => onVerifyPeerCertificate(cert),
    sni: () => getServerName(),
    alpn: [...requestedProtocols],
    handshake: (chosenProtocol) => onHandshakeComplete(chosenProtocol),
  })

Parameters

connectTLS(options?)

options?

Options including:

certificate - (optional) An object containing cert and key or a function that returns such an object. 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 server 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.
sni - (optional) SNI server name or a function that returns it
alpn - (optional) Requested protocol name or an array of preferred protocol names
handshake - (optional) A callback function that receives the negotiated protocol name after handshake.

Return Value

The same Configuration object.

Example

pipy()

  // Start a one-shot task
  .task()
  // Throw together a simple HTTP request: GET /hello
  .onStart(
    () => new Message(
      {
        method: 'GET',
        path: '/hello',
        headers: {
          host: 'example.com:443',
        },
      }
    )
  )
  .muxHTTP().to(
    $=>$.connectTLS().to(
      $=>$.connect('example.com:443') // Connect to the target with TCP
    )
  )
  .print() // Print out the response as plain text