use tls
TLS/SSL secure socket operations. Provides encryption layer on top of TCP sockets using OpenSSL. Error codes: Ok=0 (success); error codes start at 2
Constants
| Name | Value | Description |
|---|---|---|
ErrAccept |
4 |
TLS handshake failed (server mode). |
ErrCertificate |
5 |
The peer's certificate did not verify, or ours could not be loaded. |
ErrClosed |
8 |
Connection closed by peer, on a send. A receive reports a clean close as "" and 0. |
ErrConnect |
3 |
TLS handshake failed (client mode). |
ErrInit |
2 |
TLS initialization failed. |
ErrInvalidArg |
10 |
Invalid argument provided. |
ErrMemory |
9 |
Memory allocation failed. |
ErrRead |
6 |
TLS read operation failed. |
ErrWrite |
7 |
TLS write operation failed. |
Functions
fn accept
Wrap a TCP socket with TLS encryption (server mode). Loads certificate and key, then performs TLS handshake.
Signature: (socket:i64 cert_path:str key_path:str -- conn:ptr)!
| Parameter | Type | Description |
|---|---|---|
socket |
i64 |
TCP socket from net::accept |
cert_path |
str |
Path to PEM certificate file |
key_path |
str |
Path to PEM private key file |
| Output | Type | Description |
|---|---|---|
conn |
ptr |
TLS connection handle |
Example:
client_sock "/path/cert.pem" "/path/key.pem" tls::accept! // conn
fn close
Close TLS connection and free resources. Performs TLS shutdown handshake. Does NOT close underlying socket. Call net::close separately to close the socket.
Signature: (conn:ptr -- )
| Parameter | Type | Description |
|---|---|---|
conn |
ptr |
TLS connection handle |
Example:
conn tls::close sock net::close
fn connect_mtls
Wrap a TCP socket with TLS encryption using client certificate (mTLS). Performs TLS handshake with client certificate authentication.
Signature: (socket:i64 hostname:str cert_path:str key_path:str -- conn:ptr)!
| Parameter | Type | Description |
|---|---|---|
socket |
i64 |
TCP socket from net::connect |
hostname |
str |
Server hostname for SNI and certificate verification |
cert_path |
str |
Path to PEM client certificate file |
key_path |
str |
Path to PEM client private key file |
| Output | Type | Description |
|---|---|---|
conn |
ptr |
TLS connection handle |
Example:
sock "api.example.com" "/path/client.crt" "/path/client.key" tls::connect_mtls! // conn
fn connect
Wrap a TCP socket with TLS encryption (client mode). Performs TLS handshake and certificate verification, against the system's CA certificates or those the SSL_CERT_FILE and SSL_CERT_DIR environment variables name.
Signature: (socket:i64 hostname:str -- conn:ptr)!
| Parameter | Type | Description |
|---|---|---|
socket |
i64 |
TCP socket from net::connect |
hostname |
str |
Server hostname for SNI and certificate verification |
| Output | Type | Description |
|---|---|---|
conn |
ptr |
TLS connection handle |
| Error | Description |
|---|---|
tls::ErrCertificate |
The certificate is untrusted, expired, or for another name |
tls::ErrConnect |
The handshake failed for another reason |
Example:
"example.com" 443 net::connect! "example.com" tls::connect! // conn
fn receive
Receive data from TLS connection. Data is decrypted after reception. When the peer has closed the session cleanly, the data is "" and bytes_read 0, as for net::receive.
Signature: (conn:ptr max_bytes:i64 -- data:str bytes_read:i64)!
| Parameter | Type | Description |
|---|---|---|
conn |
ptr |
TLS connection handle |
max_bytes |
i64 |
Maximum bytes to receive, from 1 to 1048576 |
| Output | Type | Description |
|---|---|---|
data |
str |
Received and decrypted data |
bytes_read |
i64 |
Actual bytes received |
| Error | Description |
|---|---|
tls::ErrRead |
The read failed, or the connection ended without a TLS close |
Example:
conn 4096 tls::receive! // data n
fn send
Send data over TLS connection. Data is encrypted before transmission. All of it is sent; a peer that has gone fails the send rather than ending the program with SIGPIPE.
Signature: (conn:ptr data:str -- bytes_sent:i64)!
| Parameter | Type | Description |
|---|---|---|
conn |
ptr |
TLS connection handle |
data |
str |
Data to send |
| Output | Type | Description |
|---|---|---|
bytes_sent |
i64 |
Number of bytes sent |
Example:
conn "GET / HTTP/1.1\r\n\r\n" tls::send! // n