Installing on Linux (Ubuntu)
Tricryption installs on Ubuntu 22.04 LTS and Ubuntu 24.04 LTS (x86_64) from four
.deb packages. The qualified images are listed in the
support matrix.
| Package | Installs | Where |
|---|---|---|
tricryption-ks | the key server, tecert, tricryption-ks-provision, the tricryption-ks@.service unit | /opt/pisoft/tricryption/ks |
tricryption-re | the remote engine (rE): re-server, re-setup, and re-config.sh with its template | /opt/pisoft/tricryption/re |
tricryption-console-gateway | the Console and the REST Gateway, tricryption-tier-provision, tricryption-console.service, tricryption-gateway.service | /opt/pisoft/tricryption/console-gateway |
tricryption-node | the Node.js runtime the Console and the Gateway run on | /opt/pisoft/tricryption/node |
Each package installs its release byte for byte: nothing under /opt/pisoft/tricryption
is a configuration file, and nothing there is rewritten at install time.
dpkg --verify <package> checks every file. All state lives in /etc/pisoft/ and
/var/lib/pisoft/, and provisioning creates it, not the package install.
1. Install the packages
From the directory holding the release's packages:
sudo apt install ./tricryption-node_*.deb ./tricryption-ks_*.deb ./tricryption-re_*.deb ./tricryption-console-gateway_*.deb
Install never starts anything. Until the units are provisioned they stay disabled and
inactive, and /etc/pisoft and /var/lib/pisoft stay empty. The packages' Depends
(openssl, iproute2, python3, curl, procps) come from the Ubuntu archive. The
minimal Ubuntu cloud image is qualified too.
2. Provision the key server
sudo tricryption-ks-provision --xauth-policy
This creates instance main: the service user, the key database (a local PostgreSQL from
the Ubuntu archive unless you pass --db-host), the configuration, the key server's
setup, the instance's state in /var/lib/pisoft/ks/main/, and then it enables and starts
tricryption-ks@main.service. It checks that the process listening on the key server's
port (127.0.0.1:8893 by default) is the installed ks-server.
To put the key database on another server over TLS, name it and its CA. The password file must be readable by root only:
sudo tricryption-ks-provision --xauth-policy --bind-host <private-address> --db <database> --db-role <role> --db-host <db-host> --db-password-file <db-password-file> --db-sslmode verify-full --db-sslrootcert <db-ca.pem> --db-servername <db-host>
The database role and its empty database must exist first. This form was qualified
against Amazon RDS; see Amazon Web Services. Keep the CA file outside
/etc/pisoft (see Purge).
Both provisioning tools list every option they accept, and their usual forms:
tricryption-ks-provision --help
tricryption-tier-provision --help
Each prints a Usage: line, the examples and an Options: list, and exits 0. Neither
needs root to print it.
3. Provision the Console and the REST Gateway
sudo tricryption-tier-provision --signer-cert <signer.pem> --signer-ca <release-ca.pem> --signer-crl <release-ca.crl.der>
This runs entirely on the machine, from the installed packages. It verifies the installed release against its signature, then sets up the key server's trust anchor, enrols the Gateway's certificate identity (Butler, holding the Administrator role only), sets the revocation posture and enables the delegation layer. It registers the signed release with the key server and starts both units. Finally it proves each unit from its journal and from its readiness route.
| Service | Listens on | Ready when |
|---|---|---|
tricryption-console.service | 127.0.0.1:18090 | GET /api/ready answers 200 |
tricryption-gateway.service | 127.0.0.1:18091 | GET /api/v1/ready answers 200 |
tricryption-ks@main.service | 127.0.0.1:8893 (TLS) | the listener is the payload's ks-server |
Every Console and Gateway start re-checks the installed release against its signed
manifest. A changed file makes /api/v1/ready answer 503 BUILD_NOT_ADMITTED and names
the file. sudo apt-get install --reinstall <package> restores it. See
The Tricryption Console and
Integrating via the API for what each tier does.
All three units start again on their own after a reboot.
To let users sign in through your OpenID Connect provider, add
--oidc-config <gateway-oidc.json> --public-origin https://<host[:port]> to the same command.
The provisioner copies the file to /var/lib/pisoft/console-gateway/secrets/gateway-oidc.json
(mode 600, owned by the service account) and points the Gateway at it. The Gateway then serves
its browser login page at /oidc/?provider=<id>&binding=<id> on the public origin. A commented
example of the file is
/opt/pisoft/tricryption/console-gateway/examples/gateway-oidc.example.json. See
OpenID Connect sign-in for the file and the link.
Upgrade
Install the newer release's packages the same way:
sudo apt install ./tricryption-node_*.deb ./tricryption-ks_*.deb ./tricryption-re_*.deb ./tricryption-console-gateway_*.deb
The payload is replaced as a whole, the state in /etc/pisoft and /var/lib/pisoft is
kept, and every unit that was running is restarted by the package.
Read Upgrading before you upgrade the Console and Gateway tier.
At code-signing level 2
At code-signing level 2 ("approved release"), the key server admits a Console and Gateway
release only once that release is registered. A new release is a new manifest, so after
the upgrade the tier answers 503 BUILD_NOT_ADMITTED until you register it:
sudo tricryption-tier-provision --register-release --signer-cert <signer.pem> --signer-ca <release-ca.pem> --signer-crl <release-ca.crl.der>
The tool attests with the last release this machine registered, which it keeps under
/var/lib/pisoft/console-gateway/registered-release/, and then registers the new one.
Both readiness routes answer 200 again within seconds, without restarting a unit. At
levels 0 and 1 nothing is needed after an upgrade.
Do not re-run the full tricryption-tier-provision after an upgrade at level 2: the
key server refuses every connection from an unregistered release, the administrator's
included, so the full run stops before it registers anything.
Remove
sudo apt-get remove tricryption-console-gateway tricryption-re tricryption-ks tricryption-node
The units are stopped and the payload is removed. /etc/pisoft and /var/lib/pisoft,
which hold the configuration, the identities and the logs, are kept. Installing the
packages again picks the state up and starts again exactly the units the remove stopped.
Purge
sudo apt-get purge tricryption-console-gateway tricryption-re tricryption-ks tricryption-node
This deletes /etc/pisoft, /var/lib/pisoft and the instances' enablement links. It
deletes only what provisioning wrote under them, then each directory if it is empty: a
file you put in /etc/pisoft yourself, such as a database CA bundle, is left there, and
the directory with it.
The key database is never touched: local or remote, it is your data, and you drop it
yourself when you mean to.