CMLabs · Psyclone AIOS

# 5. Security & SSL

Secure by default: certificate verification with SSL_VERIFY_PEER, the allowselfsigned escape hatch at four scopes, hostname verification, and custom CAs via cafile/capath.

## Secure by default Shipped

SSL-enabled Psyclone builds now verify the remote certificate on every client connection: connections use `SSL_VERIFY_PEER` against the OS/CA trust store, and the presented certificate's identity is checked against the hostname being connected to (via `SSL_set1_host`, with SNI sent on connect). No configuration means secure: a spec that says nothing about SSL policy gets full verification.

Note. This replaces the historical behaviour (encrypted but unverified TLS: `SSLv23_method()` with `VERIFY_NONE`). Any older documentation implying “SSL just works with self-signed certificates” is obsolete — self-signed certs now fail unless you explicitly opt out of verification or trust your own CA.

## The verification decision

The SSL client verification flow. Only an explicit `allowselfsigned="yes"` bypasses verification; otherwise the chain is verified against the custom CA (if configured) or the OS trust store, then the hostname is checked.

## allowselfsigned: the explicit escape hatch

The `allowselfsigned` flag (default FALSE) loosens verification so self-signed certificates are accepted. Loosening is always a deliberate, visible spec entry — it can never happen by accident. The flag exists at four scopes with clear precedence:

Scope | Where | Effect
--- | --- | ---
Global | `<psySpec allowselfsigned="yes">` | Blanket policy for all SSL client connections (dev rigs, loopback testing)
Per interface | `<interface ... allowselfsigned="yes">` | Overrides the global setting for that interface's connections — either way (an interface can also say `no` to re-tighten under a loose global)
Per manager | connection-manager level (API) | Programmatic override for all connections of a manager
Per connection | individual connection (API) | Finest-grained override

Precedence is most-specific-wins: connection > manager > interface > global. Accepted true values are `yes`/`true`/`1`; anything else is false.

    <!-- dev rig: accept self-signed everywhere -->
    <psySpec allowselfsigned="yes">
      ...
      <!-- but this externally-reachable interface stays strict -->
      <interface name="Public" port="8443" protocol="HTTP"
                 service="MyWebService" allowselfsigned="no" />
    </psySpec>

Warning. `allowselfsigned="yes"` gives you encryption without authentication: traffic is unreadable to passive eavesdroppers, but an active man-in-the-middle can present its own certificate. Use it for development and closed lab networks only; production setups with self-minted certs should use a custom CA instead (below).

## Custom CA: cafile and capath

To get real verification with your own self-minted certificates — no certificate purchase needed — mint a private CA, sign your node/server certificates with it, and point Psyclone at the CA instead of the OS trust store. The attributes map to OpenSSL's `SSL_CTX_load_verify_locations`:

    <!-- global: trust our private CA for all SSL client connections -->
    <psySpec cafile="/etc/psyclone/ca/rootCA.pem">

    <!-- or a directory of CA certs (c_rehash format) -->
    <psySpec capath="/etc/psyclone/ca/">

    <!-- per-interface override -->
    <interface name="GridLink" port="10443" protocol="Message"
               service="GridService" cafile="/etc/psyclone/ca/gridCA.pem" />

`cafile` is a PEM bundle; `capath` is a hashed directory of CA certificates. Both are available globally on `<psySpec>` and per `<interface>` (interface values inherit from global when unset). With a custom CA configured, full chain and hostname verification still apply — issue your certificates with correct hostnames/SANs.

## Trust models compared

Model | Config | Encryption | Authentication | Use for
--- | --- | --- | --- | ---
Public CA | none (default) | ✔ | ✔ OS trust store + hostname | Internet-facing links, certs from a public CA
Private CA | `cafile`/`capath` | ✔ | ✔ your CA + hostname | Production grids, robot fleets, closed networks
Self-signed accepted | `allowselfsigned="yes"` | ✔ | ✘ none | Development, loopback, throwaway rigs
No SSL build | non-SSL binary | ✘ | ✘ | Trusted single-host / air-gapped setups only

## Building the SSL variant

SSL support is a build variant of both Psyclone and CMSDK:

    # Linux (requires OpenSSL development libraries: -lssl -lcrypto)
    make ssl        # release
    make ssldebug   # debug

On Windows, select the Release SSL / Debug SSL configurations in the Visual Studio solution; the projects expect the OpenSSL headers and libraries under the `_libs/OpenSSL` tree referenced by the project files. SSL-enabled CMSDK link libraries carry `SSL` in their names (e.g. `CMSDKSSLDebug2015.lib`).

Note. The reference manual's OpenSSL 1.0.2g paths reflect its era; build against a current OpenSSL and update the project/Makefile paths accordingly.

## Hardening checklist

- Run the SSL build in any deployment that crosses a network you do not fully control.
- Leave `allowselfsigned` unset (secure default); use a private CA via `cafile`/`capath` for self-minted certificates.
- Issue certificates with correct hostnames/SANs — hostname verification is enforced.
- Disable the Telnet Console and, if unused, the PsyProbe HTTP interface on exposed ports (chapter 4).
- Remember that interface `<authentication>` and encryption attributes are parsed-but-stubbed Stub — do not count them as controls.
- Firewall the main port; PsyProbe, the Console and node traffic all ride on it by default.

PreviousCustom Interfaces NextDebugging & Traces