Install server

note

All the commands in this section need to be executed as root

As of version {revnumber}, {tm} is only supported on CentOS/Redhat 7.0. Support for CentOS/RedHat 8.0 is planned for the future.

The main {ta} dependencies are:

• A web server like Nginx
• A firewall such as firewalld
• The Clickhouse database
• (optional) The MaxMind geolocation database:
• (optional) OpenSSL for key generation

Installing pre-requisites

Installing Nginx

include::@site/common/install_nginx.adoc[]

Installing firewalld

include::@site/common/install_firewalld.adoc[]

Installing {tm}

{tc} is made available in the form of RPMs for CentOS/RedHat 7.0. The latest version is available from link: {tm-dir}{tm-file}[]

The installation consists simply of downloading and installing the RPM. [subs="attributes+"]

Grab the {ta} RPM

wget {tm-dir}{tm-file}

Install

yum -y install {tm-file}

Remove

rm {tm-file}

We need a place to put the .szip files: /var/www/ticrypt-mailbox

Create the static directory for tiCrypt REST

mkdir -p /var/www/ticrypt-mailbox
chmod a+rx /var/www/ticrypt-mailbox
chown ticrypt /var/www/ticrypt-pmailbox

The {tm} service3 need to be enabled:

systemctl enable ticrypt-mailbox

Configuration

Configurint {tm}

The configuration file for {tm} is /etc/ticrypt/mailbox.toml. The configuration options supported are:

[options="header",cols="3,2,3,8"]

Parameter	Type	Required	Description
hostname	String		Hostname to bind to
port	Int	✅	The port to bind to
baseURL	String	✅	The external URL for server
backendURL	String	✅	The URL of the {tc} server
mailbox	String	✅	Path to the application .szip file
secureCookie	Bool		Disable/enable secure cookie

Some notes on the configuration:

• hostname should be 127.0.0.1 if you deploy behind Nginx
• port should match the service port in Nginx config below
• baseURL should match the external name configured in Nginx below
• backendURL should be fully qualified and accessible from the server, e.g. https://ticrypt.example.com. To test that it works do:

wget https://ticrypt.example.com/info

And make sure you get a reply containing the system info. If that does not work, connectivity with the {tc} server is not working.

• mailbox must point to a valid inbox-....szip file that the user nginx can read.

note

To update the inbox, simply download a newer inbox....szip file and change the mailbox variable. The simply restart the service with sytemctl restart ticrypt-mailbox.

caution

secureCookie=true is only useful for debugging, assuming https cannot be used, and should never be used in production.

Configuring the firewall

If you have not done already, you need to allow external access to https port

firewall-cmd --permanent --zone=public --add-service=https
firewall-cmd --reload

Setting up Nginx

The recommended way to install the web application is to use an Nginx instance that is set up for serving flat files and deal with the TLS/SSL certificate for the respective domain. This can be accomplished by adding a file /etc/nginx/conf.d/mailbox.ticrypt.conf.

With the assumptions:

• The {tm} service runs on port 8082
• We serve the mailbox from URL: https://mailbox.example.com
• The TLS stacked certificate for the domain is stored in file /etc/pki/tls/certs/example-stacked.crt
• The TLS private key is stored in file /etc/pki/tls/private/example.pem

The configuration file can look like:

upstream tc-mailbox {
    server 127.0.0.1:8082;
}

server {
    ### Configuration based on Mozilla Configuration Tool
    listen 443 ssl;
    server_name mailbox.example.com
    root /var/www/ticrypt-mailbox

    ssl_certificate /etc/pki/tls/certs/example-stacked.crt;
    ssl_certificate_key /etc/pki/tls/private/example.pem;
    
    ssl_session_timeout 1d;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
    ssl_dhparam /etc/pki/tls/dhparam.pem;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;

    #add_header Strict-Transport-Security "max-age=63072000; includeSubdomains; preload";
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";
    add_header Content-Security-Policy "script-src 'unsafe-inline' 'unsafe-eval' 'self' https://code.getmdl.io; frame-ancestors 'self' http://127.0.0.1:*";

    #### This is critical for tiCrypt  ####
    client_max_body_size 16M;

    ssl_session_tickets off;
    location / {
        try_files $uri @proxy;
    }

    location @proxy {
        proxy_pass http://tc-mailbox;
        proxy_redirect off;
        proxy_buffering off;
        proxy_cache off;
        proxy_http_version 1.1;
        proxy_read_timeout 900s;
        proxy_connect_timeout 360s;
        proxy_send_timeout 360s;
        proxy_set_header    Host                $host;
        proxy_set_header    X-Real-IP           $remote_addr;
        proxy_set_header    X-Forwarded-Proto   https;
        proxy_set_header    X-Forwarded-Ssl     on;
        proxy_set_header    X-Forwarded-For     $proxy_add_x_forwarded_for;
    }
}

caution

Failure to set client_max_body_size to at least 16M will prevent large file uploads and will result in mysterious failures.

include::@site/common/nginx_critical.adoc[]

Wrapping up

To wrap up the installation, we simply start the {tm} service with:

systemctl start ticrypt-mailbox

and verify that the service works by navigating to the public url. You should get a message telling you that you do not have the required credentials but the page should load.

Debugging

If the application is not served correctly, check the error logs of {tm} to ensure that the mailbox file can be found and that it is correctly signed.

note

You need to update the mailbox .szip file soon after it becomes available since it might contain security patches and usability improvements.

Updating the {tm} server

The {tm} server is very simple and needs updating rarely. In the event that you need to update it, do:

• Install the new .rpm packages
• Restart the {tm} service with:

systemctl restart ticrypt-mailbox