A TLS context that holds configuration (trusted CAs, verification mode) and can wrap raw sockets into encrypted SslSocket connections.
@eryx/_ssl Module
JSON
TLS/SSL support for Luau, powered by Mbed TLS.
Provides encrypted communication over sockets using TLS 1.2+. Includes both client and server context creation, certificate generation, and certificate parsing utilities.
Tip
For most use cases, prefer @eryx/http which handles TLS automatically.
Use _ssl directly when you need fine-grained control over TLS
settings or are building a custom protocol.
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
_ssl.generateSelfSignedCert(options: { key: string, subject: string?, days: number?, san: { string }?, isCa: boolean? }) → string
API Reference
Classes
SslContext
Properties
SslContext:wrapSocket
Wraps an existing connected _socket.Socket into a TLS connection.
The SslSocket takes ownership of the underlying file descriptor.
For client connections, pass serverHostname to enable SNI
(Server Name Indication) and certificate hostname verification.
Parameters
sock: any
A connected _socket.Socket.
serverHostname: string?
Hostname for SNI and certificate verification.
Returns
The wrapped TLS socket.
SslContext:loadVerifyLocations
Loads a PEM-encoded CA certificate file for server certificate verification.
Call this to trust a custom CA instead of (or in addition to) the system certificate store.
SslContext:loadVerifyLocations(cafile: string) → ()
Parameters
cafile: string
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
SslSocket:send
Sends data over the encrypted connection. Returns the number of bytes actually written, which may be less than the full buffer.
SslSocket:send(data: buffer) → number
Parameters
data: buffer
The data to send.
Returns
number
Number of bytes sent.
SslSocket:sendAll
Sends all data in the buffer, retrying internally until every byte has been transmitted or an error occurs.
SslSocket:sendAll(data: buffer) → ()
Parameters
data: buffer
The data to send.
SslSocket:recv
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.
Functions
_ssl.createDefaultContext
Creates a new SslContext with sensible defaults for client mode.
The context is preconfigured with system CA certificates and requires TLS 1.2 or later. Server certificate verification is enabled by default.
local ctx = _ssl.createDefaultContext()
local ssock = ctx:wrapSocket(sock, "example.com")
Returns
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.
Parameters
certfile: string
Path to the PEM certificate chain file.
keyfile: string
Path to the PEM private key file.
password: string?
Passphrase for encrypted private keys.
Returns
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.
Parameters
certPem: string
PEM-encoded certificate chain string.
keyPem: string
PEM-encoded private key string.
password: string?
Passphrase for encrypted private keys.
Returns
A server-mode TLS context.
_ssl.wrapSocket
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)
Parameters
sock: any
A connected _socket.Socket.
hostname: string?
Hostname for SNI and certificate verification.
Returns
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)
Parameters
pem: string
PEM-encoded certificate string.
Returns
Parsed certificate fields.
Types
CertificateInfo
Structured information about an X.509 certificate, as returned by parseCertificate.
subject: string
issuer: string
validFrom: string
validTo: string
serial: string
version: number
info: string