OPC UA Security in PHP: Policies, Certificates, and Trust

We've already covered why OPC UA needs sessions instead of stateless HTTP calls — sessions answer who is talking to whom, for how long. They say nothing about whether anyone else on the wire can read or rewrite what's being said. That's a different problem, and out of the box php-opcua/opcua-client leaves it wide open: no encryption, no certificate checks, any server's word taken at face value. That's a deliberate default — it's what lets composer require and three lines of code reach a fresh dev server with zero setup — but it's not a configuration to bring anywhere near a real PLC.

This is the other half of connecting safely: the ten security policies the client speaks, where certificates come from, how the client decides whether to trust a server, and the three ways a session can prove who it is.

Two independent decisions: channel and identity

OPC UA security is not one knob, it's two. The first is channel security: how the bytes between client and server are protected in transit — a SecurityPolicy (which algorithms) paired with a SecurityMode (None, Sign, or SignAndEncrypt). The second is authentication: who the session claims to be, carried as an identity token — anonymous, a username and password, or an X.509 certificate.

The two combine freely, which is easy to use well and just as easy to misuse. A backend that only reads published metrics might open a fully encrypted channel and authenticate as anonymous — the data in transit is protected, nobody is impersonating an operator, and that's fine. A client could just as easily open an unencrypted channel and send a username and password over it — the spec allows the combination, this library allows it, and you shouldn't: the password crosses the wire in plain text either way.

Before reaching for an algorithm, it's worth answering a few questions honestly:

1. 01

   Is the network trusted?

   Inside an air-gapped plant LAN, None might be defensible. Anything crossing a switch you don't control needs SignAndEncrypt — no exceptions, no debate.

2. 02

   Who is the user?

   A backend reading published metrics can stay anonymous. An operator issuing writes needs at least a username, ideally a certificate.

3. 03

   Does the server enforce roles?

   If it does, identity is meaningful and credentials must map to the right server-side permissions. If it doesn't, identity is audit-only, and channel encryption is doing the real work.

4. 04

   Is the server certificate trusted out of band?

   If yes, configure fingerprint or full-chain validation. If no, you're on a Trust-On-First-Use posture — covered later in this article.

Here's the full sequence those two decisions play out in, from the first packet to a live session:

The client discovers what the server offers, the two sides agree on a policy and mode, certificates change hands and get judged, and only then does the session get an identity. The rest of this article follows that order.

Choosing a security policy and mode

SecurityPolicy and SecurityMode are independent enums that combine into one negotiated pair. The mode is the simple half:

The policy decides which algorithms do that signing and encrypting. php-opcua/opcua-client implements all ten policies defined by the specification: None, five built on RSA, and four newer ones built on elliptic curves.

RSA policies

Basic128Rsa15 and Basic256 carry the OPC Foundation's own deprecated marker: SHA-1 has known collision weaknesses and RSA-1.5 padding has a documented oracle-attack history. They're implemented for one reason — some servers still in the field only speak them.

ECC policies, and why to wait

Four more policies run over elliptic curves instead of RSA: EccNistP256, EccNistP384, EccBrainpoolP256r1, and EccBrainpoolP384r1, pairing NIST or Brainpool curves with AES and SHA-256/384.

Picking a pair

A short decision order, in priority:

1. If anything between you and the server crosses hardware you don't control, the answer is SignAndEncrypt. There's no second-best here.
2. If the server only advertises one policy/mode combination — common with PLC vendors — use whatever getEndpoints() says it accepts, regardless of what else the spec allows.
3. If CPU is tight on a small embedded server, AES-128 (Basic128Rsa15, Aes128Sha256RsaOaep) costs less than AES-256. The cryptographic margin on both is still large; this is a bandwidth/CPU trade, not a security one.
4. If you're bound by a regulatory framework: Brainpool curves are called out by some European standards, NIST curves are the U.S. federal default — but see the ECC warning above before committing to either against real hardware.
5. Otherwise: Basic256Sha256 + SignAndEncrypt. No deprecated primitives, universally supported, the default for a reason.

Configuring the pair is two builder calls plus a certificate:

use PhpOpcua\Client\ClientBuilder;
use PhpOpcua\Client\Security\SecurityPolicy;
use PhpOpcua\Client\Security\SecurityMode;

$client = ClientBuilder::create()
    ->setSecurityPolicy(SecurityPolicy::Basic256Sha256)
    ->setSecurityMode(SecurityMode::SignAndEncrypt)
    ->setClientCertificate('/etc/opcua/client.pem', '/etc/opcua/client.key')
    ->connect('opc.tcp://plc.local:4840');

Anything above None needs a client certificate — which is exactly where the next section picks up. After connect(), the negotiated pair is recoverable from getEndpoints() or by listening for the SecureChannelOpened event, which carries the channel id, policy URI, and mode.

Certificates and trust

Every secured channel involves two X.509 certificates: one proves the client's identity to the server, the other proves the server's identity to the client. Same mechanism, opposite directions, worth handling separately.

The client certificate

Point the builder at PEM files — DER is auto-detected too, though passphrase-protected keys aren't currently supported:

$client = ClientBuilder::create()
    ->setSecurityPolicy(SecurityPolicy::Basic256Sha256)
    ->setSecurityMode(SecurityMode::SignAndEncrypt)
    ->setClientCertificate(
        certPath: '/etc/opcua/client.pem',
        keyPath:  '/etc/opcua/client.key',
        caCertPath: '/etc/opcua/ca.pem',   // optional, for chain validation
    )
    ->connect('opc.tcp://plc.local:4840');

No certificate handy? OpenSSL on the command line covers it end to end:

openssl req -x509 -newkey rsa:2048 -nodes \
    -keyout ca.key -out ca.pem \
    -subj "/CN=opcua-internal-ca" -days 3650

# client certificate signed by that CA
openssl req -new -newkey rsa:2048 -nodes \
    -keyout client.key -out client.csr \
    -subj "/CN=opcua-client/O=integrations"

openssl x509 -req -in client.csr \
    -CA ca.pem -CAkey ca.key -CAcreateserial \
    -out client.pem -days 730 \
    -extfile <(printf '%s\n' \
        "subjectAltName=URI:urn:opcua-client,DNS:opcua.internal" \
        "extendedKeyUsage=clientAuth,serverAuth")

Two extensions matter more than the rest of the flags. subjectAltName: URI has to carry the Application URI the server will check the certificate against — urn:opcua-client is this library's own default, so override it when you generate a real one. And extendedKeyUsage needs both clientAuth and serverAuth, or plenty of servers reject the handshake outright. For ECC, swap the key-generation step for openssl ecparam with a curve matching the chosen policy (prime256v1, secp384r1, brainpoolP256r1, brainpoolP384r1) — a P-256 certificate against an EccNistP384 policy is a configuration error, not a fallback. Certificate identity itself is a SHA-256 fingerprint of the DER bytes, lowercased hex — use that everywhere identity gets logged, never the Common Name or subject string; see RFC 5280 for the X.509 fields behind all of this.

The auto-generated fallback

Configure a non-None policy and skip setClientCertificate(), and the builder quietly generates a self-signed certificate on first connect — 2048-bit RSA or a matching curve, 365-day validity. Genuinely convenient for a one-off script. It's also regenerated on every process restart, which means the fingerprint changes every time, which means the server sees a brand-new, never-seen-before client every time your application boots.

Trusting the server certificate

The client receives the server's certificate during discovery. What happens next is the trust store's call — and by default, there isn't one:

ClientBuilder::setTrustPolicy

FileTrustStore is the shipped implementation: DER certificates on disk, one file per certificate, named by fingerprint, split into accepted and refused:

trust/
├── trusted/
│   ├── 2d1f5b8a....der
│   └── a47c80a3....der
└── rejected/
    └── ff03c2a7....der

For a PKI you already run, TrustPolicy::Full plus a CA bundle is the whole job. Without one, pinning by fingerprint is the pragmatic middle ground. And for first contact with a fleet of devices you can't provision one by one, there's Trust-On-First-Use:

ClientBuilder::autoAccept

use PhpOpcua\Client\TrustStore\FileTrustStore;
use PhpOpcua\Client\TrustStore\TrustPolicy;

$client = ClientBuilder::create()
    ->setTrustStore(new FileTrustStore('/var/lib/opcua/trust'))
    ->setTrustPolicy(TrustPolicy::FingerprintAndExpiry)
    ->autoAccept(true, force: false)   // record unknown certs, then enforce
    ->connect('opc.tcp://plc.local:4840');

The same decisions are reachable from the terminal via opcua-cli:

opcua-cli trust opc.tcp://plc.local:4840    # download and trust on the spot
opcua-cli trust:list                         # list everything currently trusted
opcua-cli trust:remove AB:CD:12:34:...       # revoke a fingerprint

Five PSR-14 events fire on every trust decision (ServerCertificateTrusted, ServerCertificateAutoAccepted, ServerCertificateRejected, and two more for manual management) — wiring a listener to record them is the only audit trail of certificate decisions outside the filesystem itself.

Authenticating the session

Channel security and authentication are independent, so the identity token is a separate decision layered on top of whatever policy and mode got picked above. The library supports the three the specification defines:

$client = ClientBuilder::create()
    ->setSecurityPolicy(SecurityPolicy::Basic256Sha256)
    ->setSecurityMode(SecurityMode::SignAndEncrypt)
    ->connect('opc.tcp://plc.local:4840');

$client = ClientBuilder::create()
    ->setSecurityPolicy(SecurityPolicy::Basic256Sha256)
    ->setSecurityMode(SecurityMode::SignAndEncrypt)
    ->setUserCredentials('operator', getenv('OPCUA_PASSWORD'))
    ->connect('opc.tcp://plc.local:4840');

$client = ClientBuilder::create()
    ->setSecurityPolicy(SecurityPolicy::Basic256Sha256)
    ->setSecurityMode(SecurityMode::SignAndEncrypt)
    ->setClientCertificate('/etc/opcua/app.pem', '/etc/opcua/app.key')
    ->setUserCertificate(
        certPath: '/etc/opcua/users/ci-bot.pem',
        keyPath:  '/etc/opcua/users/ci-bot.key',
    )
    ->connect('opc.tcp://plc.local:4840');

One more wrinkle worth knowing about. Each identity token a server advertises comes with a policyId string, and outside a handful of conventions ("anonymous", "username", "certificate") there's no real standard for what that string is — open62541 and several PLC vendors publish their own. Automatic discovery of these IDs Changed in v4.3.1 now covers all three token types; earlier releases only discovered the anonymous one and hardcoded the rest, which is worth checking if you're running an older version against a non-standard server.

When authentication fails

All five surface from ActivateSession as a ServiceException carrying the status code — the same shape as the channel-negotiation failures from the policy section above.

Wrapping up

One table, collapsing everything above into the decision you actually have to make:

Two things worth flagging that didn't fit neatly into a section above. First, the defaults are deliberately wide open — None policy, no trust store — specifically so a fresh composer require works against a fresh dev server with zero configuration. That's exactly backwards for anything production-facing, and dialing it in is on you, explicitly, every time. Second, if browse or metadata results are going through a PSR-16 cache, this library no longer calls unserialize() on cached values — payloads pass through a JSON-only codec gated by a type allowlist, which matters if that cache is writable by anything other than the client itself. See Cache path hardening for the detail.

The Security section of the docs goes further on every axis covered here — the complete trust-store API, every certificate validity rule, and the full cipher table for all ten policies. And if sessions themselves are still the fuzzy part underneath all of this, the sessions vs. HTTP APIs article covers the layer this one builds on.