Mutual TLS (mTLS) Client Authentication

Some Web services require clients to authenticate themselves by presenting a client certificate during the TLS handshake. This is known as mutual TLS (mTLS) because both the server and the client present certificates to each other. When the target Web service requires client certificate authentication, use the --client-cert startup option to specify the certificate file.

Supported Certificate Formats

LightWave Client accepts client certificates in two formats: PKCS12 and PEM. The format is auto-detected; you do not need to specify which format the file uses.

The --client-cert option syntax is:

TEXT

--client-cert <certificate-file> [ { <pass phrase> | +<credentials-file> } ]

PKCS12 (.pfx / .p12)

PKCS12 is a binary format that contains the client certificate, private key, and optional intermediate chain certificates in a single file. The file may optionally be passphrase-protected. Legacy cipher formats are supported for compatibility with older certificate tools.

PEM

PEM is a text-based format. The file must contain PEM-encoded blocks including a private key and at least one certificate. The private key must appear first in the file, followed by the client certificate and any intermediate chain certificates. If the private key is encrypted with a passphrase, you must supply the passphrase. If the private key is not encrypted, no passphrase is required.

Passphrase Handling

If the certificate file is not passphrase-protected (for example, a PEM file with an unencrypted private key, or a PKCS12 file created without a passphrase), no passphrase is needed. Simply specify the certificate file name.

If the certificate file is passphrase-protected, the passphrase may be supplied in two ways:

As plain text on the command line, following the certificate file name.
As an encrypted credentials file, specified as +<credentials-file>.

An invalid or unreadable credentials file is a fatal startup error and the CLIENT process will not start.

See Using Credentials Files for information on creating credentials files.

Configuration Examples

Standalone Process

PKCS12 certificate with inline passphrase

TEXT

> run CLIENT / name $lwc, nowait, term $zhome / --standalone --api myapi --base-url https://api.example.com --client-cert $vol.subvol.mycert mypassphrase

PEM certificate with credentials file

TEXT

> run CLIENT / name $lwc, nowait, term $zhome / --standalone --api myapi --base-url https://api.example.com --client-cert $vol.subvol.mypem +$vol.subvol.credfile

PEM certificate without passphrase

TEXT

> run CLIENT / name $lwc, nowait, term $zhome / --standalone --api myapi --base-url https://api.example.com --client-cert $vol.subvol.mypem

Pathway Server Class

Program options may be supplied using the STARTUP attribute with a command file or as individual PARAMs.

Using STARTUP attribute with command file

TEXT

set server startup        "@cmdfile"

EDIT file cmdfile contents:
--api myapi
--base-url https://api.example.com
--client-cert $vol.subvol.mycert +$vol.subvol.credfile

Using PARAMs

TEXT

set server param client-cert "$vol.subvol.mycert mypassphrase"