Skip to main content

Configuring ticrypt-auth

The configuration of ticrypt-auth service is significantly more complex that most other services. We dedicate this chapter to this topic.

ticrypt-auth config

Main configuration structure

All options of this service must be in section ticrypt.auth.

mongodbSectionRequiredSee ???
usersSectionSee auth-users
sessionsSectionSee auth-sessions
mfaSectionSee mfa
servicesSectionSee auth-services
security.xssSectionSee auth-xss
mailboxesSectionSee mailboxes
server-assisted-authSectionSee split-cred
akka.remote.netty.tcp.hostnameSectionSee ???
akka.remote.netty.tcp.portSectionSee [???] (http://localhost:3000/docs/Server%20Cheat%20Sheet/backend/ticrypt-auth#akka)

Configuration Sections

users section

allow-self-registrationon, offCan users self-register?
self-registration-tokenStringRegistration token
self-registration-reasonStringMessage for user before activation
default-permissionsArrStringPermissions for default account

The self-registration-token needs to be randomly generated to prevent server spamming with account requests if self-registration is enabled. To generate the registration string, you can use:

openssl rand -base64 32

sessions section

session-idle-ttlDurationMax amount of inactivity before close
challenge-ttlDurationHow long is the challenge valid?
temporary-ttlDurationHow long is a signed message valid?
subsession-max-ttlDurationHow long is a subsession valid?
banned-permissionsArrStringPermissions banned from all sessions

Long durations (more than 1 hour) for challenge-ttl and temporary-ttl parameters can result in security problems.

services section

ticrypt-auth supervises all other tiCrypt services. The goal of this section is to provide parameters that control the supervision.

check-ping-frequencyDurationHow often to check on services
timeoutDurationHow long before a service is considered offline

security.xss section

This section controls the Cross-Site-Scripting attack detection and reaction of tiCrypt.

kill-sessionBoolShould the session be terminated
lock-userBoolShould the account get locked
lock-user-reasonStringMessage for locked user

At a minimum, kill-session should be set to true. It is highly recommended that lock-user is set to true as well.

mailboxes section

Mailboxes feature allows external users to provide in a safe, end-to-end encrypted, way data to tiCrypt users. Most installations would want to turn this feature on.

enabledBoolfalseEnable the mailbox feature?

Key Escrow

The Key Escrow subsystem allows for user’s private keys to be cryptographically placed into escrow, such that it requires collaboration between multiple individuals in order to recover a user’s private key.

Some use cases for enabling the Key Escrow subsystem are:

  • Automated backups of users' private keys so they can be recovered if lost.

  • Complying with court orders for access to a user’s data.


The ticrypt.auth.key-escrow section controls the key escrow mechanism.

enabledBoolfalseEnable the key escrow feature?
min-keysInt3How many recovery keys, and thus escrow groups, are needed to allow enrolling keys.
site-key-pathStringIf EnabledNonePath to the signed site key

Do not enable the key escrow subsystem if you do not have a signed site key. New users will be prevented from registering their accounts.

How it works

Escrow Users

The Key Escrow subsystem has its own set of users, separated from the normal tiCrypt user accounts. These user accounts are dedicated to managing and recovering escrowed user keys, and users of the Key Escrow subsystem do not need to have normal tiCrypt user accounts. In most cases, it is actually recommended to have the Escrow users be persons who are not users of the main tiCrypt system.

Escrow users interact with the system using the Escrow component of the tiCrypt interface, which can be reached via an option on the tiCrypt login screen.

The Escrow account system uses a chain of trust and is structured as such:

Site Key
The primary public-private key pair is used to manage the Key Escrow subsystem. The Site public key is directly signed by a Tera Insights key, for which the certificate is baked into the tiCrypt server software. This acts as the root of the chain of trust, and the Site private key is used to sign certificates that perform administrative tasks such as adding or removing Escrow users and managing Escrow groups.

The Site private key is normally kept on a machine separated from the rest of the system, ideally on an air-gapped computer. The Site private key is mostly used to sign certificate signing requests, producing certificates that can be entered into the tiCrypt system by an administrator to execute the specified action.

Escrow User
A user of the Key Escrow subsystem, identified by an RSA key pair. The user’s public key must be signed by the Site key, or the key of another Escrow user who has has been given permission to add Escrow users, in order for them to be registered as an active Escrow user. The Escrow user has a set of permissions that dictate what actions they are allowed to perform.

Escrow Group
A group of Escrow users receives one of the recovery key shards when a user’s private key is placed into escrow. As all members of a group receive the same shard, they act as backups for one another in case certain members are unavailable when a key recovery is needed. Not all Escrow need to be part of a group, only those that will automatically receive recovery key shards during the escrow procedure.

The Escrow Mechanism

When the Key Escrow subsystem is enabled, a tiCrypt administrator can mark a user’s account as requiring escrow. In this state, the next time the user logs in, they will be given a restricted session that only allows them to place their key into escrow using the mechanism described below. Once that is done, their account will return to normal and they will be allowed to obtain a normal session with the full set of permissions available to them.

The escrow procedure will fail if there are not at least as many Escrow Groups configured as the min-keys setting in the configuration. Additionally, each Escrow Group must have at least one member.

When the tiCrypt interface receives the limited session, it will then perform the following operations:

  1. Pull information about the escrow subsystem from the tiCrypt server. This will include the configured Escrow Groups along with the public keys of all of their members.

  2. Generate a separate AES-256 key for each Escrow Group. This is called a Recovery Key Shard.

  3. Combine all of the Recovery Key Shards into a single AES-256 key, called the Recovery Key.

  4. Encrypt the user’s private key using the Recovery Key. The Recovery Key is discarded after this step.

  5. For each escrow group, the group’s Recovery Key Shard is to be encrypted using each of its member's public keys, essentially giving each member of the group a copy of the group’s Recovery Key Shard.

  6. The encrypted user private key and the encrypted Recovery Key Shards are sent to the server for storage.

Since the Recovery Key is discarded as part of the procedure, only by members of each of the different groups collaborating can the Recovery Key Shards be re-combined to retrieve the Recovery Key, which is able to decrypt the user’s private key.

Multi-factor authentication

Multi-factor authentication allows for adding a requirement during login for the user to prove their identity via one or more additional authentication factors in addition to proving they control their private key.


token-saltStringSalt for mfa. Must be random
num-factors-requiredInt0If 0, mfa disabled.
enabled-factorsArrString[]Which of declared factors are enabled
default-token-ttlDuration2 daysDefault MFA token valid
default-cert-ttlDuration30 minutesDefault lifetime of MFA certificates
factorsSectionEmptyThe factors section

Each factor in the factors section defines a sub-section with the factor name and the parameters:

public-keyStringPath to factor public key
urlStringThe URL that hosts the factor page
token-ttlDurationMFA defaultHow long the token is valid
cert-ttlDurationMFA defaultLifetime of MFA certificate


How it works

When a user attempts to log in and MFA is enabled, the server will respond with a list of URLs for additional factors the user needs to authenticate with in addition to the standard challenge. For each factor, the tiCrypt interface will open the URL in a frame. The web server at that URL can then perform any necessary authentication, whether that be a simple username and password check, a push notification to a phone, or otherwise.

If the user successfully authenticates with the factor, the web page inside the frame needs to use the window.postMessage() JavaScript function provided by the browser to send a message back to the tiCrypt interface. This message must be an object with the following fields:

payloadStringJSON encoded signed payload object.
authorizerStringFactor ID, which must match one of the factors in the ticrypt-auth config file.
algoStringSignature algorithm used. See [mfa-sig-algos] for acceptable signature algorithms.
signatureStringBase64-encoded signature of the payload using the factor’s private key.

Multi-Factor Authentication Success Schema

The object encoded in the payload field must have at least the following fields, although the factor is permitted to add additional fields.

emailStringThe tiCrypt username of the user, normally their email address.
sourceIPStringThe source IP of the user as seen by the factor.
timestampString or IntThe date and time at which the user as authorized, as either an ISO-8601 datetime string or a millisecond-precision UNIX timestamp.

Multi-Factor Authentication Payload Schema

The MFA response will be forwarded to the tiCrypt server, which will perform the following steps:

  1. The factor configuration will be looked up using the value of the authorizer field. If no authentication factor is found in the configuration for that authorizer, the request is rejected.

  2. The signature field is decoded from Base64. If this decoding fails, the request is rejected.

  3. The authentication factor’s configured public key is used to validate the signature on the payload field using the signature algorithm specified in algo. If the signature algorithm is invalid or the signature itself does not match, the request is rejected.

  4. The payload field is decoded using JSON. The decoded value must be an object with at least the fields specified above, or the request is rejected.

  5. The timestamp field is checked to ensure that:

    1. It is not in the future.

    2. It is not older than the cert-ttl configured for the authentication factor.

  6. The user is looked up using the email field of the payload.

  7. A check is made to see if this MFA response has been previously submitted. The request is rejected if so.

  8. A new MFA token is generated with a validity duration determined by the factor’s token-ttl parameter. This token is returned to the user.

If there are additional factors, the tiCrypt interface will go through the same process with all of them.

Finally, the interface will submit its standard challenge along with all of the MFA tokens it has acquired. The server will check to ensure that all of the MFA tokens are valid and match the user that is attempting to log in. Only then will the user be granted an active session.

"payload": "{\"email\": \"\", \"sourceIP\": \"\", \"timestamp\": \"2020-05-25 01:38:44.915046+00:00\"}",
"authorizer": "my_authorizer",
"algo": "RSA-PSS-SHA256#saltLen=32",
"signature": "fXfuC9D4/+..."

Signature Algorithms

This section describes the signature algorithms that are accepted by the tiCrypt server for Multi-Factor Authentication.

The signature algorithm string has the following format, where elements inside brackets ([]) are optional:


The following algorithms are supported:

Authenticate using RSA keys via the Probabilistic Signature Scheme with SHA-256 as the hash function. This is the recommended signature algorithm, as it has a built-in salt and improved padding compared to PKCS1 signatures.

The standard MGF1 is used as the mask generation function.

This algorithm supports the following parameters:

saltLenInt4The length of the salt used in bytes.

The recommended salt length to use for PSS signatures is the size of the hash. Using SHA256, this means a salt length of 32 is recommended.

It is recommended to always specify the salt length. The current default is fairly weak for compatibility reasons, and will likely be increased in the near future.

Authenticate using RSA keys via the PKCS1 v1.5 signature scheme, with SHA-256 as the hash function. This method is recommended only for systems that are unable to generate PSS signatures.

If using this signature algorithm, it is recommended to include your own salt in the payload, as the signature algorithm does not include a salt of its own.

Authenticate using RSA keys via the PKCS1 v1.5 signature scheme, with SHA1 as the hash function. This method is not recommended as the SHA1 hash algorithm has been significantly weakened by recent attacks. It is only present for compatibility with legacy systems.

This signature algorithm is deprecated and will be removed in the future.


The goal of this section is to control the split-credentials feature of tiCrypt.

The split-credentials feature can only be enabled if [mfa] is also enabled. Split credentials will force themselves off if at least one additional authentication factor is not enabled, regardless of the settings below.

This feature allows for additional hardening of users' private keys against offline attacks. For example, if a user’s laptop containing their encrypted private key was stolen, the split credentials feature would significantly reduce the risk of the key being decrypted and their account being breached.


enabledBoolfalseEnable the split-credential feature?
requiredBooltrueRequire split-credentials for new users?

required should virtually always keep to the default true value. It should only be modified if there are some users for which using additional authentication factors is completely impossible.

How it works

In tiCrypt, the following things are required to obtain a user’s private key in a usable state:

  • The AES-encrypted private key data.

  • The AES Initialization Vector (IV).

  • The user’s password.

  • The password salt.

The IV and Salt are 128-bit numbers that are randomly generated during the initial private key generation procedure and are re-generated whenever the user changes the password on their key.

Normally, the IV and Salt are stored alongside the AES-encrypted private key data in the private key file, as they are not generally considered secret. However, if MFA is enabled, we can store these on the server instead and only return them to the user if they are able to verify themselves using the additional authentication factor(s).

In this way, neither the client nor the server have enough information to recover the user’s private key on their own. The Salt and IV are useless by themselves, and the private key data is effectively impossible to decrypt without the Salt and IV. This means that an attacker that is able to steal a user’s private key would have to also defeat the additional authentication factor or the tiCrypt server itself in order to even have a chance at attacking the private key.

Due to the split-credentials feature working by storing the IV and Salt on the server instead of the private key file, enabling this feature will only affect users that register after the feature is enabled. It will not retroactively affect users that registered prior to the feature being enabled.

Keys can be enrolled into split credentials after the fact by changing the password on the private key. The tiCrypt interface will automatically store the IV and Salt on the server instead of the private key file if split-credentials is enabled during a password change.