HTTPS: certificate trust and server identity

Ordinary HTTPS

An https address enables encryption, but a client also needs a trusted certificate chain and the correct server identity. A CA is a certificate authority whose certificate establishes trust in a chain. HttpRequest creates verified TlsOptions.Client by default. HttpClient must receive appropriate options or recognize the https scheme. The HttpClient example explicitly selects Client for https in its own code.

Leave CaPath empty for a server with a publicly trusted certificate. For a private CA, pass its PEM through TlsTrust. This is a public trust certificate; never copy the server private key into the game. A custom CA set replaces the default set for that connection rather than automatically extending it.

Connect your server

You need a working HTTPS API returning {"message":"text"} and a certificate matching the name/IP in its URL. Ordinary LocalHttpFixture.py serves HTTP and does not create HTTPS by itself.

1. Take HttpJsonRequest.cs from the HTTP guide; add TlsTrust.cs and TlsJsonDemo.cs.
2. Attach TlsJsonDemo to an Entity in a separate level. Set Url to your HTTPS API in the Inspector. For a private CA, add its PEM, for example asset://certs/dev-ca.pem, and set CaPath. Leave CaPath empty for default trust.
3. Build and press F6. Expect transport=Success, status=200 and a message. A CA-loading failure stops startup; the example never falls back to disabled verification.

using Reckfell;

public partial class TlsTrust : Entity
{
    public static Error LoadCustomCa(string path, out TlsOptions? options)
    {
        options = null;
        if (!FileAccess.FileExists(path)) return Error.FileNotFound;
        using var certificate = new X509Certificate();
        Error error = certificate.Load(path);
        if (error != Error.Ok) return error;
        options = TlsOptions.Client(certificate); return Error.Ok;
    }
}

using System;
using Reckfell;

public partial class TlsJsonDemo : Entity
{
    [Export] public string Url { get; set; } = "https://127.0.0.1:8766/message";
    [Export] public string CaPath { get; set; } = "";
    public override void _Ready()
    {
        if (!Uri.TryCreate(Url, UriKind.Absolute, out Uri? uri) || uri.Scheme != "https")
        { ReckfellApi.Print("HTTPS requires an https:// URL"); return; }
        TlsOptions? trust = null;
        if (CaPath.Length != 0)
        {
            Error loaded = TlsTrust.LoadCustomCa(CaPath, out trust);
            if (loaded != Error.Ok) { ReckfellApi.Print($"TLS CA: {loaded}"); return; }
        }
        var api = new HttpJsonRequest { Trust = trust }; AddChild(api);
        api.Completed += reply => ReckfellApi.Print($"HTTPS: transport={reply.Transport}, status={reply.StatusCode}, failure={reply.Failure}, message={reply.Message}");
        Error start = api.Start(Url);
        if (start != Error.Ok) ReckfellApi.Print($"HTTPS start: {start}");
    }
}

Which checks remain active

TlsOptions.Client(certificate) retains certificate and name verification. SAN is the certificate extension listing allowed names and IP addresses. A certificate for api.example.com need not match the server IP: that IP must appear in SAN. Changing hosts/routing does not establish trust in another identity.

commonNameOverride sets a different expected identity for a deliberately designed connection. It is not a generic name-error fix: never copy an arbitrary string from an error/server response. Ordinary clients should correct the URL, certificate or routing configuration.

ClientUnsafe disables name verification. Without trustedChain it also disables mandatory chain trust verification. A supplied chain is still verified, but the correct name remains unconfirmed. Published examples do not use ClientUnsafe.

Diagnose a failure

Establish the correct identity and trust first. Do not fix rejection by disabling certificate verification. A root CA alone does not replace a correctly configured server chain. Repeat client/export checks after certificate replacement or renewal.

If a named connection stalls, compare resolved IPv4/IPv6 addresses and server reachability on each. Diagnosing by IP still requires a matching IP SAN or a deliberately chosen verified identity. The Windows fixture observed localhost timeouts even for HTTP; the cause is not established and that path is not accepted as a verified connection.

Local checks use a numeric IPv4 endpoint and separate certificates with a matching IP SAN: correct trust allows a response; an untrusted chain, a wrong expected identity through commonNameOverride and an expired certificate are refused. This does not test every public CA, DNS/IPv6 connection, proxy, automatic renewal, other platforms' trust systems or an exported build. Server setup and token protection are separate; client TLS options do not create an account system.