Configuring ticrypt-auth

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

ticrypt-auth config

Main configuration structure

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

mongodb	Section	Required	See more...
users	Section	✅	See auth-users
sessions	Section	✅	See auth-sessions
mfa	Section		See mfa
services	Section	✅	See auth-services
security.xss	Section	✅	See auth-xss
mailboxes	Section		See mailboxes
server-assisted-auth	Section		See split-cred
akka.remote.netty.tcp.hostname	Section		See auth-akka
akka.remote.netty.tcp.port	Section		See auth-akka

Configuration Sections

users section

Parameter	Type	Required	Description
allow-self-registration	on, off		Can users self-register?
self-registration-token	String	✅	Registration token
self-registration-reason	String		Message for user before activation
default-permissions	ArrString		Permissions 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

Parameter	Type	Required	Description
session-idle-ttl	Duration		Max amount of inactivity before close
challenge-ttl	Duration		How long is the challenge valid?
temporary-ttl	Duration		How long is a signed message valid?
subsession-max-ttl	Duration		How long is a subsession valid?
banned-permissions	ArrString		Permissions 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 supervision.

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

security.xss section

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

Parameter	Type	Required	Description
kill-session	Bool		Should the session be terminated
lock-user	Bool		Should the account get locked
lock-user-reason	String		Message 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

The mailboxes feature allows external users to provide a safe, end-to-end encrypted, data path to tiCrypt users. Most installations would want to turn this feature on.

Parameter	Type	Required	Default	Description
enabled	Bool		false	Enable 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 to recover a user’s private key.

Some use cases for enabling the Key Escrow subsystem are:

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

Configuration

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

Parameter	Type	Required	Default	Description
enabled	Bool		false	Enable the key escrow feature?
min-keys	Int		3	How many recovery keys, and thus escrow groups, are needed to allow enrolling keys.
site-key-path	String	If Enabled	None	Path to the signed site key

caution

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 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 public site-key is directly signed by a Tera Insights key, for which the certificate is backed into the tiCrypt server software. This acts as the root of the chain of trust, and the private site-key is used to sign certificates that perform administrative tasks such as adding or removing Escrow users and managing Escrow groups.

The private site-key is normally kept on a machine separated from the rest of the system, ideally on an air-gapped computer. The private site-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 is 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 been permitted to add Escrow users, 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 users 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, by 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 can 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.

Configuration

Parameter	Type	Required	Default	Description
token-salt	String	✅		Salt for mfa. Must be random.
num-factors-required	Int		0	If 0, mfa disabled.
enabled-factors	ArrString		[]	Which of the declared factors are enabled.
default-token-ttl	Duration		2 days	Default MFA token valid.
default-cert-ttl	Duration		30 minutes	Default lifetime of MFA certificates.
factors	Section		Empty	The factors section.

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

Parameter	Type	Required	Default	Description
public-key	String	✅		Path to factor public key.
url	String	✅		The URL that hosts the factor page.
token-ttl	Duration		MFA default	How long the token is valid.
cert-ttl	Duration		MFA default	Lifetime 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:

Field	Type	Required	Description
payload	String	✅	JSON encoded signed payload object.
authorizer	String	✅	Factor ID, which must match one of the factors in the ticrypt-auth config file.
algo	String	✅	Signature algorithm used. See [mfa-sig-algos] for acceptable signature algorithms.
signature	String	✅	Base64-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.

Field	Type	Required	Description
email	String	✅	The tiCrypt username of the user, normally their email address.
sourceIP	String	✅	The source IP of the user as seen by the factor.
timestamp	String or Int	✅	The date and time at which the user is 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\": \"user@example.com\", \"sourceIP\": \"192.168.1.2\", \"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:

ALGO_NAME[#param1=value[,param2=value,...]]

The following algorithms are supported:

RSA-PSS-SHA256

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:

Parameter	Type	Required	Default	Description
saltLen	Int		4	The length of the salt used in bytes.

The recommended salt length to use for PSS signatures is the size of the hash. Using SHA256 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.

RSA-PKCS1-SHA256

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.

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

RSA-PKCS1-SHA1

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.

Split-credentials

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 user's 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.

Configuration

Parameter	Type	Required	Default	Description
enabled	Bool		false	Enable the split-credential feature?
required	Bool		true	Require 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 can verify themselves using the additional authentication factor(s).

In this way, neither the client nor the server has 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 can steal a user’s private key would have to also defeat the additional authentication factor or the tiCrypt server itself 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 before the feature is 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 are enabled during a password change.