#TLS / SSL configuration

qjs-lws inherits libwebsockets's TLS stack. Server and client roles share the same LWSContext info object. Option parsing is implemented in lws-tls.c (tls_creation_info_fromobj, tls_connect_info_fromobj), called from lws-context.c.

#Server certificates

Each cert / key / CA can be supplied either as a file path string or as an ArrayBuffer holding the PEM (or DER) bytes. The str_or_buf_property() helper in js-utils.c picks the right field — file path or *_mem + *_mem_len.

import { createServer, LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT, LWS_SERVER_OPTION_CREATE_VHOST_SSL_CTX } from 'lws';

createServer({
  port: 443,
  options: LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT |
           LWS_SERVER_OPTION_CREATE_VHOST_SSL_CTX,
  serverSslCert:       'localhost.crt',
  serverSslPrivateKey: 'localhost.key',
  serverSslCa:         'ca.crt',
  sslPrivateKeyPassword: 'pass',
  sslCipherList: 'HIGH:!aNULL:!MD5',
  tls13PlusCipherList: 'TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256',
  protocols: [/* ... */],
});

In-memory form:

import { readFileSync } from 'fs';
import { createServer } from 'lws';

createServer({
  serverSslCert: readFileSync('localhost.crt'),       // ArrayBuffer
  serverSslPrivateKey: readFileSync('localhost.key'), // ArrayBuffer
});

#Client certificates

new LWSContext({
  clientSslCa:                'ca.crt',
  clientSslCert:              'client.crt',
  clientSslPrivateKey:        'client.key',
  clientSslPrivateKeyPassword: 'pw',
  clientSslCipherList:        'HIGH:!aNULL',
  clientTls13PlusCipherList:  'TLS_AES_256_GCM_SHA384',
});

Same dual-mode (file path or ArrayBuffer).

#Server options

Common options flags for TLS server contexts (OR them together):

#Client connection flags (ssl_connection)

Used per outbound ctx.clientConnect() via the sslConnection or ssl info property. All LCCSCF_* constants are exported:

Quick form: supplying ssl: true in clientConnect() is shorthand for `LCCSCF_USE_SSL | LCCSCF_ALLOW_SELFSIGNED | LCCSCF_ALLOW_INSECURE | LCCSCF_ALLOW_EXPIRED | LCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK` (see client_connect_info_fromobj).

ctx.clientConnect('https://self-signed.example/', {
  ssl: true,                            // permissive
  // or:
  // sslConnection: LCCSCF_USE_SSL,    // strict
});

#Generating a self-signed certificate

import { generateSelfSignedCert } from 'lws';

const { cert, key } = generateSelfSignedCert({
  commonName: 'localhost',        // default: 'localhost'
  altNames: ['localhost', '127.0.0.1'], // optional; falls back to commonName
  days: 825,                      // default: 825
  keyBits: 2048,                  // default: 2048
});
// cert, key: PEM-encoded ArrayBuffer, pass straight to serverSslCert / serverSslPrivateKey

Plain OpenSSL API use (RSA + SHA-256), not an lws facility. Only built against the OpenSSL TLS backend; on other backends it throws `InternalError("generateSelfSignedCert: not supported by this build's TLS backend")`.

#Verification hook

You can override the certificate check with a JS callback:

{
  name: 'http',
  onOpensslPerformServerCertVerification(wsi, cert, tlsSocket, preverifyOk) {
    console.log(cert.subject, cert.fingerprint256, preverifyOk);

    if(!preverifyOk && cert.checkHost('example.com'))
      cert.error = 0;       // X509_V_OK - overrule an otherwise-failing check

    return 0;                // 0 accepts, non-zero rejects
  },
}

Two reasons fire this shape of callback:

cert is an X509Certificate and tlsSocket a TLSSocket — both described below. preverifyOk is OpenSSL's own verification result (0 or 1) going into the callback; returning 0 from the handler accepts the certificate regardless (matching lws' own "return 0 to mean the cert is OK" convention), but to actually overrule an OpenSSL-detected error (rather than merely ignoring it) you must also set cert.error = 0 — see X509_STORE_CTX_set_error()'s role in SSL_CTX_set_verify(3).

#X509Certificate

Wraps OpenSSL's X509*, modeled closely on Node's crypto.X509Certificate. Implemented in lws-tls.c. Constructible directly, not just from the verification hook:

import { X509Certificate } from 'lws';

const cert = new X509Certificate(pemStringOrDerArrayBuffer);

Every wrapped certificate is reference-counted (X509_up_ref()) and freed by its finalizer, so — unlike the raw X509_STORE_CTX*/SSL* libwebsockets hands the verification callback — an X509Certificate is safe to keep around past the callback that produced it.

#Properties

#Methods

#TLSSocket

A minimal, non-owning wrapper around the SSL* libwebsockets hands to the verification hook — unlike X509Certificate it is not safe to retain past that callback. Implemented in lws-tls.c.