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

Server presents certificate allowselfsigned = yes? (connection > manager > interface > global) Accept (encrypted, NOT verified) ⚠ cafile / capath configured? custom CA vs OS trust store Verify chain against custom CA (load_verify_locations) Verify chain against OS trust store (VERIFY_PEER) Hostname matches cert? SSL_set1_host Accept ✔ Reject ✘ yes no (default) yes no chain ok chain ok (fail → reject) yes no
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:

ScopeWhereEffect
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 managerconnection-manager level (API)Programmatic override for all connections of a manager
Per connectionindividual 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

ModelConfigEncryptionAuthenticationUse for
Public CAnone (default)✔✔ OS trust store + hostnameInternet-facing links, certs from a public CA
Private CAcafile/capath✔✔ your CA + hostnameProduction grids, robot fleets, closed networks
Self-signed acceptedallowselfsigned="yes"✔✘ noneDevelopment, loopback, throwaway rigs
No SSL buildnon-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
Psyclone AIOS · CMLabs