# 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 ???

users

Section

Required

See [auth-users]

sessions

Section

Required

mfa

Section

Optional

See [mfa]

services

Section

Required

security.xss

Section

Required

See [auth-xss]

mailboxes

Section

Optional

See [mailboxes]

server-assisted-auth

Section

Optional

See [split-cred]

akka.remote.netty.tcp.hostname

See ???

akka.remote.netty.tcp.port

See ???

## Configuration Sections​

### users section ​

ParameterTypeRequiredDescription

allow-self-registration

on, off

Optional

Can users self-register?

self-registration-token

String

Required

Registration token

self-registration-reason

String

Optional

Message for user before activation

default-permissions

ArrString

Optional

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 ​

ParameterTypeRequiredDescription

session-idle-ttl

Duration

Optional

Max amount of inactivity before close

challenge-ttl

Duration

Optional

How long is the challenge valid?

temporary-ttl

Duration

Optional

How long is a signed message valid?

subsession-max-ttl

Duration

Optional

How long is a subsession valid?

banned-permissions

ArrString

Optional

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 the supervision.

ParameterTypeRequiredDescription

check-ping-frequency

Duration

Optional

How often to check on services

timeout

Duration

Optional

How long before a service is considered offline

### security.xss section ​

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

ParameterTypeRequiredDescription

kill-session

Bool

Optional

Should the session be terminated

lock-user

Bool

Optional

Should the account get locked

lock-user-reason

String

Optional

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 ​

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.

ParameterTypeRequiredDefaultDescription

enabled

Bool

Optional

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 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.

## Configuration​

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

ParameterTypeRequiredDefaultDescription

enabled

Bool

Optional

false

Enable the key escrow feature?

min-keys

Int

Optional

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

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 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 that 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 seprate 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 be encrypted using each of its members' 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 prviate key.

## Configuration​

ParameterTypeRequiredDefaultDescription

token-salt

String

Required

Salt for mfa. Must be random

num-factors-required

Int

Optional

0

If 0, mfa disabled.

enabled-factors

ArrString

Optional

[]

Which of declared factors are enabled

default-token-ttl

Duration

Optional

2 days

Default MFA token valid

default-cert-ttl

Duration

Optional

30 minutes

factors

Section

Optional

Empty

The factors section

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

ParameterTypeRequiredDefaultDescription

public-key

String

Required

Path to factor public key

url

String

Required

The URL that hosts the factor page

token-ttl

Duration

Optional

MFA default

How long the token is valid

cert-ttl

Duration

Optional

MFA default

## 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:

Multi-Factor Authentication Success Schema
FieldTypeRequiredDescription

payload

String

Required

authorizer

String

Required

Factor ID, which must match one of the factors in the ticrypt-auth config file.

algo

String

Required

Signature algorithm used. See [mfa-sig-algos] for acceptable signature algorithms.

signature

String

Required

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.

FieldTypeRequiredDescription

email

String

Required

sourceIP

String

Required

The source IP of the user as seen by the factor.

timestamp

String or Int

Required

The date and time at which the user as authorized, as either an ISO-8601 datetime string or a millisecond-precision UNIX timestamp.

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:

ParameterTypeRequiredDefaultDescription

saltLen

Int

Optional

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, 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.

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.

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.

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 itself 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.

## Configuration​

ParameterTypeRequiredDefaultDescription

enabled

Bool

Optional

false

Enable the split-credential feature?

required

Bool

Optional

true

Require split-credentials for new users?

required should virtually always kept 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).