Skip to content

Martini Runtime Server Configuration Security

Configuring encryption seed

Before you configure anything in your .properties file, make sure to change the encryption seed inside the application.properties file. This value is used as the seed to encrypt passwords in the dbxml file and triggers.

Password encryption

Passwords will only be encrypted after a restart of your Martini Runtime instance.

Running Martini with NGINX and TLS

You can run your Martini instances with NGINX to have a secure connection. This guide will help you set up your instance behind a proxy server. NGINX will act as a reverse proxy for Martini.

In this setup, the NGINX server is responsible for managing all SSL connections originating from users. Its primary role is to decrypt incoming requests to ensure they can be forwarded to the Martini server in a readable format. Once Martini processes these requests and generates responses, these responses are relayed back to the NGINX server. Here, they are encrypted before being dispatched to the client's browser. It's crucial to note that in this architecture, Martini is completely abstracted from the encryption/decryption process, focusing solely on handling the business logic and processing of the requests and responses. This delineation of responsibilities ensures a clear separation of concerns, allowing each server to specialize and optimize its designated tasks

Procedure

Note: Addresses of instance and server * NGINX Server: 10.0.0.2 * Martini Instance: 10.0.0.3 * Domain assigned to the instance: martini.example.com

  1. In your NGINX server, go to the /etc/nginx/conf.d/certs/ directory and create two directories called ssl_crt and ssl_key. Copy your SSL certificate and key in these directories respectively.
1
2
3
4
5
/etc/nginx/conf.d/certs/
├── ssl_crt
│   └── <your-ssl-certicate-here>
├── ssl_key
│   └── <your-ssl-key-here>
  1. Create the sites-available and sites-enabled directories inside the /etc/nginx/conf.d directory. NGINXconfiguration files will be stored inside the sites-available directory. Then later, a symbolic link will be created to point to the sites-enabled directory for NGINX to load the configuration.
1
2
3
/etc/nginx/conf.d
    ├── sites-available
    ├── sites-enabled

  1. Edit the file named /etc/nginx/nginx.conf and include all .conf files in the /etc/nginx/conf.d/sites-enabled. By doing this, NGINX will be prompted to load all *.conf files inside the sites-enabled folder upon start or restart of its process.

  2. Create the configuration file for martini.example.com. In this case, the configuration file is named martini.example.com.conf. It should reside in the directory /etc/nginx/conf.d/sites-available.

The content of the file should be like this: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
upstream martini {
        server 10.0.0.3:8080 fail_timeout=0;
    }

    server {
        listen 80;
        server_name martini.example.com;
        access_log /var/log/nginx/martini.example.com_access.log;
        error_log /var/log/nginx/martini.example.com_error.log;

        location / {
            return 301 https://$server_name$request_uri;

            proxy_pass http://martini;
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header X-Forwarded-Server $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Port 80;
            proxy_set_header Host $host;
            proxy_redirect off;
            proxy_connect_timeout 240;
            proxy_send_timeout 240;
            proxy_read_timeout 240;
        }

    }
    server {
        listen 443;
        server_name martini.example.com;
        access_log /var/log/nginx/martini.example.com_ssl_access.log;
        error_log /var/log/nginx/martini.example.com_ssl_error.log;
        ssl on;
        ssl_certificate <your-ssl-certicate-here>;
        ssl_certificate_key <your-ssl-key-here>;
        location / {
            proxy_pass http://martini;
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header X-Forwarded-Server $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Port 443;
            proxy_set_header X-Forwarded-Proto https;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_redirect off;
            proxy_connect_timeout 240;
            proxy_send_timeout 240;
            proxy_read_timeout 240;
        }
    }
  1. Create a symbolic link or symlink from the sites-available to the sites-enabled directory.

1
2
3
4
 ln -s /etc/nginx/conf.d/sites-available/martini example.com.conf /etc/nginx/conf.d/sites-enabled/martini.example.com.conf
 ```

Test the NGINX Configuration
nginx -t 
1
If NGINX confirms that all configurations are good to go, you can now reload NGINX using this command:
nginx -s reload 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
6. Configure your DNS. Make sure that your DNS entry points to the IP of your NGINX instance and not your Martini instance's IP address.

## Configuring Martini with HTTP and HTTPS using Tomcat

Security is one of the most important configuration you must do when using Martini. Luckily, Martini ships with Tomcat which is used to process HTTP and HTTPS requests. Using the `application.properties` file, you can configure certain parts of Tomcat in Martini. 

In default, Martini uses an HTTP connector only at port `8080`. But if you are handling sensitive data with your APIs, you can opt to use the HTTPS connector. 
> **Note**: You can change the HTTP port by setting the value of the `server.http.port` property to any other number between `80` and `65535`. 

## Configuring the HTTPS port

In Tomcat, there are two different implementations of SSL/TLS; Java Secure Socket Extension (JSSE) implementation and the Apache Portable Runtime (APR) implementation in which both implementations are available in Martini. 

!!! warning "Enabling HTTPS port"
    Enabling the HTTPS port is only a good thing to implement if you are planning to run Martini as a stand-alone web server. If you have a web server i front of your instances, it is recommended to let it do all the SSL processing. 

### JSSE implementation

Martini uses the JSSE implementation by default. JSSE uses a Java KeyStore to maintain the private key and its corresponding certificate. You'll need to generate a JKS from your keys and certificates then point Martini to its location.

Required properties for HTTPS configuration with JSSE:

* `server.https.port`

    The HTTPS port number, you can choose from any number between `80` and `65535`.

* `server.tomcat.https.keystoreFile`

    The location of your JKS file. You can set this property to the path of your JKS file.

* `server.tomcat.https.keyStorePass`

    Password of the JKS file.

After configuring everything you need for HTTPS, your `.properties` file should like this:

```properties
server.https.port=8443
server.tomcat.https.keystoreFile=martini.keystore
server.tomcat.https.keystorePass=AN3HeVoLybR6S89Eg7

APR Implementation

For APR protocol, you only need to configure the path of your SSL certificate and SSL key.

Required properties for HTTPS with APR:

  • server.https.port

    The HTTPS port number, you can choose from any number between 80 and 65535.

  • server.tomcat.https.protocol

    Set the value of this property to org.apache.coyote.http11.Http11AprProtocol to command Martini to use the APR library.

  • server.tomcat.https.SSLCertificateFile

    Set the value of this property to the path of the SSL certificate.

  • server.tomcat.https.SSLCertificateKeyFile

    Set the value of this property to the path of the SSL key.

After configuring everything you need for HTTPS, your .properties file should like this:

1
2
3
4
server.tomcat.https.protocol=org.apache.coyote.http11.Http11AprProtocol
server.https.port=8443
server.tomcat.https.SSLCertificateFile=/usr/local/ssl/server.crt
server.tomcat.https.SSLCertificateKeyFile=/usr/local/ssl/server.pem

SSL certificate storage

You should store your SSL certificates in another location besides <martini-home> to prevent accidental deletion when upgrading Martini to the latest version.

HTTP Strict Transport Security (HSTS)

HSTS is another way to secure your Martini instances againsts attacks. Enabling HSTS adds a header named Strict-Transport-Security to the responses from your server. When a user receives a response with this header, it will automatically be converted from HTTP to HTTPS. This upgrade will serve as a defense mechanism against man-in-the-middle attacks by ensuring that data transmitted between client and the server remains encrypted.

Required properties for HSTS:

  • hsts.enabled

    Set to true to let Martini add the Strict-Transport-Security header.

  • hsts.include-subdomains

    Set to true if all present and future sub-domains will be using HTTPS.

  • hsts.preload

    Set to true if the site owner would like their domain to be included in the HSTS preload list maintained by Chrome (and used by Firefox and Safari).

  • hsts.max-age

    The maximum time, in seconds, that a site is only to be accessed using HTTPS.

After configuring everything you need for HSTS, your .properties file should like this:

1
2
3
4
hsts.enabled=true
hsts.include-subdomains=false
hsts.preload=false
hsts.max-age=31536000