Security

Server Certificates

Enterprise ships a self-signed server certificate, so any client that validates certificates refuses to connect until you replace it or explicitly trust it. This page covers the server-side task of replacing it, which is done once per deployment; trusting a certificate in a particular client is covered on that client's page.

Why This Is Needed

TLS is enabled out of the box, so the first connection to a new instance meets that certificate. A validating client, which is most of them, needs both of the following, or it refuses the connection:

1. To trust the certificate. It is self-signed, so no certificate authority vouches for it and the client has to be told to trust it explicitly.
2. A certificate name that matches the host. If the certificate carries no Subject Alternative Name matching the host in the URL, the client rejects it with a hostname mismatch, typically ERR_TLS_CERT_ALTNAME_INVALID, even after it has been trusted. Trusting alone is not enough.

Neither condition stops AmiCore from starting, and neither produces a server-side error. The failure is entirely client-side, which is why it often looks like a broken deployment rather than a certificate problem.

Contact support for the specifics of your build

The certificate and keystore that ship with a given build are not documented here. Contact 3forge support for the details that apply to your version.

Which Listener Uses Which Keystore

The Web listener and the native listeners read different keystores, so check which one you are replacing:

Listener	Property	Shipped value
Web HTTPS	https.keystore.file	keys/3forge.pem
Center, JDBC, Relay, Gateway	ami.keyfile	keys/3forge.jks

Both keystores are JKS, whatever the extension

keys/3forge.pem is a Java KeyStore in JKS format, not a PEM certificate, despite its extension. Pass -storetype JKS when you point keytool at it. The keys/*.pub files beside the keystores are ssh-rsa public keys used for the mutual-TLS allowlist, not the X.509 certificate a TLS client needs to trust, so you export that yourself as described below.

Every listener keystore password resolves from ami.keypass by default, https.keystore.password included, and each can be overridden independently. Override them in config/local.properties rather than editing config/defaults.properties. See Security Defaults for the full contents of keys/.

Option 1: Regenerate the Keystore With a Matching SAN

Suitable for development and for internal deployments where a private certificate authority is not available. Reissue the certificate with a SAN covering every name and address clients will use:

keytool -genkeypair -alias 3forge -keyalg RSA -keysize 2048 \
  -dname "CN=your-host.example.com" \
  -ext "SAN=dns:your-host.example.com,dns:localhost,ip:127.0.0.1" \
  -validity 1000 -storetype JKS -keystore keys/3forge.pem \
  -storepass <your ami.keypass value> -keypass <your ami.keypass value>

Both extra flags matter

keytool defaults to PKCS12 on Java 9 and later, while the keystores Enterprise ships are JKS, so -storetype JKS keeps the output the same whichever JDK is on your path. -keypass keeps the command non-interactive: without it keytool stops and prompts for a key password.

Clients must still be told to trust the result, because it is still self-signed. Restart the instance after replacing a keystore: the server builds its SSL context at startup.

Option 2: Install a CA-Signed Certificate

Recommended for production. Point https.keystore.file and https.keystore.password at a keystore whose certificate is issued by a certificate authority your clients already trust, for the real hostname. Both requirements above are then satisfied by the CA chain and the certificate's own SAN, and no per-client trust configuration is needed.

Trusting the Certificate in a Client

Where replacing the certificate is not an option, each client has to be configured to trust it. A client trusts the public certificate, never the keystore, which holds the private key and must not be distributed. The per-client steps, including exporting the certificate to a PEM, live with each client:

• AI Agent Access (MCP) -> transport security: exporting the certificate, and trusting it in a Node-based or JVM-based MCP client.
• Mandatory Mutual TLS: the separate, client-side requirement on the Center, JDBC, Relay, and Gateway listeners, where the client must also present its own certificate.

Related

• Security Defaults: what ships in keys/, and the rest of the shipped security posture.
• Installation: where the install tree and config/local.properties live.