TLS/SSL support for Luau, powered by OpenSSL.

Provides encrypted communication over sockets using TLS 1.2+. Includes both client and server context creation, certificate generation, and certificate parsing utilities.

:::note Optional capability This module is a typed facade over an optional native backend. In builds without TLS/cryptography support, require("@eryx/_ssl") fails immediately with a clear capability error. :::

local _socket = require("@eryx/_socket")
local _ssl    = require("@eryx/_ssl")

local sock = _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM)
sock:connect("example.com", 443)

local ctx  = _ssl.createDefaultContext()
local ssock = ctx:wrapSocket(sock, "example.com")
ssock:sendAll(buffer.fromstring("GET / HTTP/1.0\r\nHost: example.com\r\n\r\n"))
local data = ssock:recv(4096)
print(buffer.tostring(data))
ssock:close()

Summary

Classes

Functions

API Reference

Classes

SslContext

A TLS context that holds configuration (trusted CAs, verification mode) and can wrap raw sockets into encrypted SslSocket connections.

Properties

SslContext:wrapSocket

⚠ Yields

Wraps an existing connected _socket.Socket into a TLS connection.

The SslSocket takes ownership of the underlying file descriptor. For verified client connections, serverHostname is required to enable SNI (Server Name Indication) and certificate hostname verification.

SslContext:wrapSocket(sock: any, serverHostname: string?) → SslSocket

Parameters

sock: any

A connected _socket.Socket.

serverHostname: string?

Hostname for SNI and certificate verification.

Returns

SslSocket

The wrapped TLS socket.

SslContext:loadVerifyLocations

Loads a PEM-encoded CA certificate file for server certificate verification.

Call this to switch the context from system certificate store verification to the supplied custom CA bundle.

SslContext:loadVerifyLocations(cafile: PathLike) → ()

Parameters

cafile: PathLike

Path to a PEM file containing one or more CA certificates.

SslContext:setVerify

Sets the certificate verification mode.

Use _ssl.VERIFY_REQUIRED (the default for contexts created with createDefaultContext) to require a valid, trusted server certificate. Use _ssl.VERIFY_NONE to skip verification (not recommended for production).

SslContext:setVerify(mode: number) → ()

Parameters

mode: number

Verification mode - VERIFY_NONE or VERIFY_REQUIRED.

SslSocket

An encrypted socket wrapping an underlying TCP connection.

Provides the same send/recv/close interface as _socket.Socket, but all data is transparently encrypted and decrypted via TLS.

Properties

readable: true

Stream capability tag.

writable: true

Stream capability tag.

closed: boolean?

true if the socket has been closed.

SslSocket:send

⚠ Yields

Sends data over the encrypted connection. Returns the number of bytes actually written, which may be less than the full buffer.

SslSocket:send(data: string | buffer) → number

Parameters

data: string | buffer

The data to send.

Returns

number

Number of bytes sent.

SslSocket:sendAll

⚠ Yields

Sends all data in the buffer, retrying internally until every byte has been transmitted or an error occurs.

SslSocket:sendAll(data: string | buffer) → ()

Parameters

data: string | buffer

The data to send.

SslSocket:recv

⚠ Yields

Receives up to bufsize bytes from the encrypted connection.

Returns a buffer containing the received data. An empty buffer (length 0) indicates the remote end has closed the connection.

SslSocket:recv(bufsize: number) → buffer

Parameters

bufsize: number

Maximum number of bytes to receive.

Returns

buffer

The received data.

SslSocket:close

Performs a TLS shutdown and closes the underlying socket, releasing all associated resources.

SslSocket:close() → ()

SslSocket:getPeerName

Returns the remote address and port of the connected peer.

SslSocket:getPeerName() → (string, number)

Returns

string

The remote IP address.

number

The remote port.

SslSocket:getSockName

Returns the local address and port the socket is bound to.

SslSocket:getSockName() → (string, number)

Returns

string

The local IP address.

number

The local port.

SslSocket:fileNo

Returns the underlying OS file descriptor number for the socket. Useful for advanced I/O multiplexing.

SslSocket:fileNo() → number

Returns

number

The file descriptor.

SslSocket:read

Stream-compatible aliases

SslSocket:read(size: number) → buffer

SslSocket:readSync

SslSocket:readSync(size: number) → buffer

SslSocket:readBuffer

SslSocket:readBuffer(size: number) → buffer

SslSocket:readBufferSync

SslSocket:readBufferSync(size: number) → buffer

SslSocket:write

SslSocket:write(data: string | buffer) → number

SslSocket:writeSync

SslSocket:writeSync(data: string | buffer) → number

SslSocket:closeSync

SslSocket:closeSync() → ()

Functions

_ssl.createDefaultContext

Creates a new SslContext with sensible defaults for client mode.

The context is preconfigured for system CA verification and requires TLS 1.2 or later. Server certificate verification is enabled by default. When verification is enabled, wrapSocket requires a hostname.

local ctx = _ssl.createDefaultContext()
local ssock = ctx:wrapSocket(sock, "example.com")

_ssl.createDefaultContext() → SslContext

Returns

SslContext

A client-mode TLS context.

_ssl.createServerContext

Creates a new SslContext configured for server mode by loading a certificate chain and private key from PEM files on disk.

_ssl.createServerContext(certfile: PathLike, keyfile: PathLike, password: string?) → SslContext

Parameters

certfile: PathLike

Path to the PEM certificate chain file.

keyfile: PathLike

Path to the PEM private key file.

password: string?

Passphrase for encrypted private keys.

Returns

SslContext

A server-mode TLS context.

_ssl.createServerContextPem

Creates a new SslContext configured for server mode from PEM strings rather than files. Useful when certificates are generated at runtime or stored in memory.

_ssl.createServerContextPem(certPem: string, keyPem: string, password: string?) → SslContext

Parameters

certPem: string

PEM-encoded certificate chain string.

keyPem: string

PEM-encoded private key string.

password: string?

Passphrase for encrypted private keys.

Returns

SslContext

A server-mode TLS context.

_ssl.wrapSocket

⚠ Yields

Convenience function that creates a default client context and wraps a socket in a single call.

Equivalent to:

local ctx = _ssl.createDefaultContext()
local ssock = ctx:wrapSocket(sock, hostname)

_ssl.wrapSocket(sock: any, hostname: string?) → SslSocket

Parameters

sock: any

A connected _socket.Socket.

hostname: string?

Hostname for SNI and certificate verification. Required when verification is enabled.

Returns

SslSocket

The wrapped TLS socket.

_ssl.generateKey

Generates a new private key and returns it as a PEM string.

local rsa_key = _ssl.generateKey("rsa", 4096)
local ec_key  = _ssl.generateKey("ec")

_ssl.generateKey(type: ("rsa" | "ec")?, bits: number?) → string

Parameters

type: ("rsa" | "ec")?

Key type - "rsa" (default) or "ec" (secp256r1).

bits: number?

Key size in bits. Defaults to 2048 for RSA, 256 for EC.

Returns

string

PEM-encoded private key.

_ssl.generateSelfSignedCert

Generates a self-signed X.509 certificate and returns it as a PEM string.

local key  = _ssl.generateKey()
local cert = _ssl.generateSelfSignedCert({
    key     = key,
    subject = "CN=localhost,O=Dev",
    days    = 365,
    san     = { "localhost", "127.0.0.1" },
})

_ssl.generateSelfSignedCert(options: { key: string, subject: string?, days: number?, san: { string }?, isCa: boolean? }) → string

Parameters

options: { key: string, subject: string?, days: number?, san: { string }?, isCa: boolean? }

Certificate generation options.

Returns

string

PEM-encoded certificate.

_ssl.parseCertificate

Parses a PEM-encoded certificate string and returns structured information about it.

local info = _ssl.parseCertificate(certPem)
print(info.subject, info.validFrom, info.validTo)

_ssl.parseCertificate(pem: string) → CertificateInfo

Parameters

pem: string

PEM-encoded certificate string.

Returns

CertificateInfo

Parsed certificate fields.

Types

CertificateInfo

Structured information about an X.509 certificate, as returned by parseCertificate.

type CertificateInfo = { subject: string, issuer: string, validFrom: string, validTo: string, serial: string, version: number, info: string }

subject: string

issuer: string

validFrom: string

validTo: string

serial: string

version: number

info: string

Constants

• Verification mode constants
• _ssl.VERIFY_NONE = 0
• _ssl.VERIFY_REQUIRED = 2