Auth Service (ticrypt-auth)

Last updated: May 29, 2026Latest Frontend Version: 2.16.20

The ticrypt-auth service is the most complex backend service. It handles authentication, authorization, user management, and supervises all other services.

Configuration File

/etc/ticrypt/ticrypt-auth.conf — All options in the ticrypt.auth section.

Main Configuration Structure

Parameter	Type	Required	Description
mongodb	Section	✅	Database connection. See mongodb.
users	Section	✅	User registration settings. See Users.
sessions	Section	✅	Session management. See Sessions.
mfa	Section		Multi-factor authentication. See MFA.
services	Section	✅	Service supervision. See Services.
security.xss	Section	✅	XSS attack response. See XSS Security.
mailboxes	Section		Mailbox feature toggle. See Mailboxes.
key-escrow	Section		Key escrow subsystem. See Key Escrow.
server-assisted-auth	Section		Split-credential hardening. See Split Credentials.
akka.remote.netty.tcp.hostname			See Akka
akka.remote.netty.tcp.port			See Akka

---

Users

Parameter	Type	Required	Description
allow-self-registration	on, off		Allow users to register their own accounts
self-registration-token	String	✅	Anti-spam token required for self-registration
self-registration-reason	String		Message shown to users before account activation
default-permissions	ArrString		Default permission set for new accounts

tip

Generate self-registration-token with a random value to prevent server spamming if self-registration is enabled:

openssl rand -base64 32

---

Sessions

Parameter	Type	Description
session-idle-ttl	Duration	Maximum inactivity before a session is closed
challenge-ttl	Duration	How long a login challenge remains valid
temporary-ttl	Duration	How long a signed message remains valid
subsession-max-ttl	Duration	Maximum lifetime of a subsession
banned-permissions	ArrString	Permissions banned from all sessions

warning

Long durations (over 1 hour) for challenge-ttl and temporary-ttl can introduce security vulnerabilities. Keep these values short.

---

Services

ticrypt-auth supervises all other tiCrypt services, monitoring their health via periodic pings.

Parameter	Type	Description
check-ping-frequency	Duration	How often to check service health
timeout	Duration	How long before a service is considered offline

---

XSS Security

Controls the response to detected Cross-Site Scripting (XSS) attacks.

Parameter	Type	Description
kill-session	Bool	Terminate the session on XSS detection
lock-user	Bool	Lock the user account on XSS detection
lock-user-reason	String	Message shown to the locked user

warning

At minimum, kill-session should be true. Setting lock-user to true is strongly recommended to prevent repeated attack attempts.

---

Mailboxes

The mailboxes feature provides an end-to-end encrypted data path from external users to tiCrypt users.

Parameter	Type	Default	Description
enabled	Bool	false	Enable the mailbox feature

---

Key Escrow

The key escrow subsystem allows a user's private key to be cryptographically placed into escrow, requiring collaboration between multiple individuals to recover it. This supports compliance requirements such as court-ordered data access.

Configuration

The ticrypt.auth.key-escrow section:

Parameter	Type	Required	Default	Description
enabled	Bool		false	Enable the key escrow feature
min-keys	Int		3	Minimum number of escrow groups required before key enrollment
site-key-path	String	If enabled		Path to the signed site key file

caution

Do not enable key escrow without a signed site key. New users will be unable to register.

How It Works

The key escrow system uses a chain of trust with three tiers:

Site Key The root key pair for the escrow subsystem. The public key is signed by a Tera Insights certificate baked into the server software, establishing the chain of trust. The private site key signs certificates for administrative actions (adding/removing escrow users and groups). The private site key should be kept on an air-gapped machine.

Escrow Users Identified by RSA key pairs, with public keys signed by the site key (or by another authorized escrow user). Escrow users have dedicated accounts separate from normal tiCrypt accounts. It is recommended that escrow users are not regular tiCrypt users.

Escrow Groups Groups of escrow users that each receive one shard of the recovery key. All members of a group receive the same shard, providing redundancy. At least min-keys groups must exist before escrow enrollment is possible.

The Escrow Mechanism

When a tiCrypt administrator marks a user account as requiring escrow, the user's next login triggers a restricted session that performs the following:

1. Pull escrow group information (group membership and public keys) from the server.
2. Generate a separate AES-256 Recovery Key Shard for each escrow group.
3. Combine all shards into a single AES-256 Recovery Key.
4. Encrypt the user's private key with the Recovery Key. The Recovery Key is then discarded.
5. Encrypt each group's shard with every member's public key.
6. Send the encrypted private key and encrypted shards to the server.

Recovery requires representatives from every escrow group to collaborate, each contributing their shard to reconstruct the Recovery Key.

---

Multi-Factor Authentication

MFA adds one or more additional authentication factors beyond the user's private key. See the MFA Setup page for the MFA server interface contract and integration patterns.

Configuration

Parameter	Type	Required	Default	Description
token-salt	String	✅		Random salt for MFA tokens
num-factors-required	Int		0	Number of required factors. 0 disables MFA.
enabled-factors	ArrString		[]	IDs of active factors from the factors section
default-token-ttl	Duration		2 days	Default MFA token validity period
default-cert-ttl	Duration		30 minutes	Default MFA certificate lifetime
factors	Section			Factor definitions (see below)

Factor Definition

Each factor in the factors section defines a sub-section:

Parameter	Type	Required	Default	Description
public-key	String	✅		Path to the factor's public key file
url	String	✅		URL of the factor's authentication page
token-ttl	Duration		MFA default	How long the MFA token is valid
cert-ttl	Duration		MFA default	Lifetime of the MFA certificate

How It Works

When a user logs in with MFA enabled:

1. The server responds with a list of factor URLs the user must authenticate with.
2. The tiCrypt frontend opens each URL in a frame.
3. The factor's web page performs authentication and sends a signed message back to the frontend via window.postMessage().
4. The frontend collects all MFA tokens and submits them with the standard login challenge.
5. The server validates all tokens and grants a session only if all factors pass.

Signature Algorithms

The signature algorithm string format is: ALGO_NAME[#param1=value[,param2=value,...]]

RSA-PSS-SHA256 (Recommended) RSA with Probabilistic Signature Scheme and SHA-256. Built-in salt and improved padding over PKCS1.

Parameter	Type	Default	Description
saltLen	Int	4	Salt length in bytes. Recommended: 32 (SHA-256 hash size).

tip

Always specify saltLen=32 when using RSA-PSS-SHA256. The default of 4 is kept for compatibility but is weaker than recommended.

RSA-PKCS1-SHA256 RSA with PKCS1 v1.5 and SHA-256. Use only when PSS signatures are unavailable. Include your own salt in the payload, as the algorithm does not generate one.

RSA-PKCS1-SHA1 (Deprecated) RSA with PKCS1 v1.5 and SHA-1. Present only for legacy compatibility. SHA-1 has known weaknesses and this algorithm will be removed in a future release.

---

Split Credentials

Split credentials harden user private keys against offline attacks. If a user's device containing their encrypted private key is stolen, split credentials prevent decryption without also compromising the server or the MFA factor.

note

Split credentials require MFA to be enabled with at least one active factor. The feature automatically disables itself if no additional authentication factors are configured.

Configuration

Parameter	Type	Default	Description
enabled	Bool	false	Enable split credentials
required	Bool	true	Require split credentials for new users

tip

Keep required at true in nearly all cases. Only set to false if some users absolutely cannot use additional authentication factors.

How It Works

To decrypt a tiCrypt private key, four pieces of information are needed:

1. The AES-encrypted private key data
2. The AES Initialization Vector (IV)
3. The user's password
4. The password salt

Normally, the IV and salt are stored alongside the encrypted key in the private key file. With split credentials enabled, the IV and salt are stored on the server instead and only returned after successful MFA verification.

This means neither the client nor the server alone has enough information to recover the private key. An attacker who steals the key file must also defeat the MFA factor or compromise the server.

Split credentials only apply to users who register (or change their password) after the feature is enabled. Existing users can enroll by changing their private key password, which triggers the frontend to store the IV and salt on the server.