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.

mongodb	Section	Required	See ???
users	Section	Required	See [auth-users]
sessions	Section	Required	See [auth-sessions]
mfa	Section	Optional	See [mfa]
services	Section	Required	See [auth-services]
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

Parameter	Type	Required	Description
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

Parameter	Type	Required	Description
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.

Parameter	Type	Required	Description
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.

Parameter	Type	Required	Description
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.

Parameter	Type	Required	Default	Description
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.

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

Parameter	Type	Required	Default	Description
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	Default lifetime of MFA certificates
factors	Section	Optional	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	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	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:

Multi-Factor Authentication Success Schema

Field	Type	Required	Description
payload	String	Required	JSON encoded signed payload object.
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.

Multi-Factor Authentication Payload Schema

Field	Type	Required	Description
email	String	Required	The tiCrypt username of the user, normally their email address.
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.

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

Parameter	Type	Required	Default	Description
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).

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