HTTPS / TLS

Spectranext treats TCP port 443 as HTTPS/TLS. Your Z80 program opens a normal socket, connects to port 443, and uses send / recv (or stream I/O) as usual. The co-processor performs the TLS handshake, certificate checks, and encryption on your behalf.

No special syscall is required — connecting to port 443 is enough to trigger TLS offload.

For a longer development-oriented guide (BASIC and assembly examples, buffer notes, and next steps), see TLS/HTTPS Sockets.

How it works (simple view)

1. Your program talks to the socket API (socket APIs) as if it were plain TCP.
2. Spectranext detects destination port 443 and opens a TLS client session to the server.
3. The co-processor runs the TLS handshake and validates the server certificate (see Certificate validation below).
4. After the handshake succeeds, every byte you send is encrypted before it leaves the device, and every byte you receive is decrypted before it reaches your program.

The TLS wire protocol (ClientHello, cipher suites, encrypted records) never appears on the Z80 side. From your program’s perspective the socket carries plain application data — typically an HTTP request and response.

Fully transparent (unlike SSH)

SSH offload injects a short line-oriented control protocol before the shell session (TRUST?, USER?, CONNECTED, and so on). HTTPS has no equivalent control lines.

	HTTPS (port 443)	SSH (port 22)
Trigger	Connect to port 443	Connect to port 22
Z80-visible setup	None — handshake is invisible	Control lines ending in \r\n
After setup	Plain application bytes (e.g. HTTP)	Raw terminal I/O after CONNECTED
User prompts on socket	No	Yes (trust, username, password)

If TLS setup fails (bad certificate, handshake error, unreachable host), connect() fails or the socket closes with an error — there is no ERROR …\r\n text protocol on the socket.

What you send and receive

Once connected, use the socket like unencrypted TCP. For a typical HTTPS website:

GET / HTTP/1.1
Host: www.example.com

You write that request with send; the co-processor encrypts it. The response body and headers you read with recv are already decrypted.

The TLS/HTTPS Sockets page shows the same pattern from BASIC and assembly — connect to port 443, then read and write normally.

What the co-processor does

When you connect to port 443, Spectranext automatically (details in the development guide):

1. Detects port 443 — recognises an HTTPS destination
2. Establishes a TLS handshake — negotiates TLS 1.2 with the server
3. Verifies the certificate — checks chain, expiry, and hostname (SNI)
4. Encrypts and decrypts — all subsequent socket I/O

The step-by-step flow (TCP first, then TLS detection, handshake, validation, then encrypted traffic) is described in How it works.

Certificate validation

On port 443, the co-processor:

1. Receives the server’s SSL certificate
2. Validates the chain against the built-in CA store
3. Checks the certificate has not expired
4. Verifies the certificate matches the hostname (SNI)
5. Only completes connect() if validation succeeds

If validation fails, the TLS session is rejected. Your program sees a failed connection, not HTTP error text.

Full validation behaviour: Certificate validation.

Trusted CA certificates

Spectranext ships a curated CA bundle for server validation. Roots include Let’s Encrypt (ISRG X1/X2), DigiCert, Google Trust Services, Amazon, GlobalSign, USERTrust, Microsoft, Entrust, and Baltimore CyberTrust — covering most public HTTPS sites.

The complete list and notes on coverage: Included CA certificates.

Minimal C sketch

#include <socket.h>

/* Pseudocode — same socket API as plain TCP */
int s = socket(AF_INET, SOCK_STREAM, 0);
connect(s, &addr, sizeof(addr));   /* addr.sin_port = 443 */

send(s, "GET / HTTP/1.1\r\nHost: example.com\r\n\r\n", ...);
recv(s, buf, sizeof(buf), 0);    /* decrypted HTTP response */

Working CMake projects:

• HTTPS Request — fetch a URL with httplib
• HTTPS Download — download files over HTTPS

HTTPS filesystem mounts (https:// URLs on a VFS mount) use the same TLS stack but are documented separately: HTTPS filesystem.

See also

• TLS/HTTPS Sockets — primary guide: BASIC/assembly examples, CA list, validation, limitations
• SSH — port 22 offload with a control-line protocol
• Socket APIs — socket, connect, send, recv, poll_fd
• Memory — paging and buffer considerations for network code