IMPORTANT: 

• This article is targeted at IT admins!
• NEW: SSLing of the built-in Jetty web server has changed with the Release of v7.1!
• NEW: Ensure you only have "OpenJDK" HotSpot v17 LTS installed on your host machine, more info here.
• Do not copy from this solution article, as it may introduce wrong characters on your side, due to potentially hidden characters!
• IMPORTANT: information in this article was publicly available and should not get used on your side! I.e. use a different and secure password than in our example!

The farmerswife (fw) Server app uses two different sets of certificates:

• SSLing your farmerswife server
• SSLing your Web Client and Mobile Web Client

  
  

The farmerswife system gets shipped, with the fw Server app being deployed with our own self-signed certificates. These are only used for the communication between the fw Client desktop app and the iOS fw app with the fw Server app.

These self-signed certificates are not in use for the Web Client and Mobile Web Client, as this would lead to complications, because your web browser would still complain about the connection not being secure due to self-signed certs being in use. 

This article explains how you can implement your own SSL certs for your farmerswife Web Client and Mobile Web Client, as well as how to exchange our self-signed certs with your own for the fw Client desktop app and the iOS fw app.

You can achieve "SSLing farmerswife" using two different approaches: 

1. SSLing your actual farmerswife Server app (this is covered here), or
2. by using a third party service as proxy, e.g. using NGINX as the third-party service (covered here).

By default farmerswife uses a set of five different ports, three of them using HTTP protocol, and the other two only using TCP.

• Server Port: 22000 - TCP over TLS by default *
• File Transfer Port: 24000 - TCP
• iOS fw app / API Port: 25000 - XML over HTTPS *
• Web Client (& Mobile Web Client ) > Port: 26000 - HTTP
• WebCal / HTTP Port: 27000 - HTTP

* Using the self-signed certificate by default.

SSLing your farmerswife server app

In order to be able to apply your own SSL certs on your farmerswife system you need the certificate.crt and certificate.key of your own domain/subdomain. Below you will see an example of how they start and finish:

certificate.crt:

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

certificate.key:

-----BEGIN PRIVATE KEY-----
-----END PRIVATE KEY-----

More on "optioning" your SSL certs

If you don't have any certificate at all yet:

Choose your Certificate Provider or Certificate Authority (CA).

Follow the instructions of YOUR CA on how to create a Certificate Signing Request (CSR) from the host machine of the fw server app. This will make it later possible, to export the private key.

For a manual CSR ... go here:
Due to recent support cases, here the "solution article" from DigiCert (no affiliation):
https://www.digicert.com/support/tools/certificate-utility-for-windows

SSLing your Web Client and Mobile Web Client

Step 1: 

On Windows: 

Place a copy of your certificate.crt and certificate.key inside the following folder located inside your farmerswife Server app installation, typically in: C:\Program Files\farmerswife Server\lib\openssl\..

On macOS: 

Since "LibreSSL" is pre-installed on macOS; "openssl" commands work just fine. Create a folder, place the copy of certificate.crt and certificate.key inside and start the following commands in Terminal from this folder.

On Linux Ubuntu:

Ensure "OpenSSL" is installed. Create a folder, place the copy of certificate.crt and certificate.key inside and start the following commands in Terminal from this folder.

Step 2: 

Execute the following command to start creating a keychain:

Windows: C:\Program Files\farmerswife Server\lib\openssl>openssl.exe pkcs12 -export -name servercert -in certificate.crt -inkey certificate.key -out myp12keystore.p12

macOS and Linux Ubuntu: openssl pkcs12 -export -name servercert -in certificate.crt -inkey certificate.key -out myp12keystore.p12

You will be asked to set a password for your certificate chain, which will be needed on the next step and for the configuration of the bundled-in web server.

Step 3:

Once done you have to copy the file myp12keystore.p12 to the following folder:

On Windows: C:\Program Files\Java\jre_installedversion\bin\

macOS and Linux Ubuntu: Simply move on to the next step.

Now execute the following command:

On Windows: C:\Program Files\Java\jre_installedversion\bin>keytool.exe -importkeystore -destkeystore keystore.p12 -srckeystore myp12keystore.p12 -srcstoretype pkcs12 -alias servercert

macOS and Linux Ubuntu: keytool -importkeystore -destkeystore keystore -srckeystore myp12keystore.p12 -srcstoretype pkcs12 -alias servercert

IMPORTANT: Remember which password you used in this step, as it will be needed to configure the Web Client / Mobile Web Client.

Step 4:

Now grab the file named keystore.p12 and move it to the following folder:

On Windows: C:\Program Files\farmerswife Server\lib\jetty\jetty-base\etc\

On macOS: /path/to/your/farmerswife Server/Contents/lib/jetty/jetty-base/etc/

On Linux Ubuntu: /path/to/your/farmerswife Server/lib/jetty/jetty-base/etc/

NOTE: The "lib > jetty > jetty-base > etc" folder already contains the default "jetty-bundled-in" keystore.p12 file. You are going to over-write / replace this file with your own keystore.p12 file! 

VERY IMPORTANT: 

On Windows: Set this keystore.p12 file as "Read Only" and ensure you have a safe copy of this keystore.p12 file!

When upgrading the fw Server app to a new version, ensure you use the "Ignore" option when the Installation Wizard stops on this Read Only file, to NOT overwrite this file!

On macOS and Linux Ubuntu: ensure you have a safe copy of this keystore.p12 file! And after the upgrade, ensure you are copying it back into the new fw Server app package.

Step 5:

You now need to edit 3 files which are all located  ...

on Windows: C:\Program Files\farmerswife Server\lib\jetty\jetty-base\start.d\

on macOS: /path/to/your/farmerswife Server/Contents/lib/jetty/jetty-base/start.d/

on Linux Ubuntu: /path/to/your/farmerswife Server/lib/jetty/jetty-base/start.d/

a) On "ssl.ini" apply these two changes:

a1) In line 6 change:

From this: "# --modules=ssl" ... to this: "--modules=ssl" to enable this module.

a2) In line 83 change:

From this: "jetty.sslContext.keyStorePassword=secret123" ... to this: "jetty.sslContext.keyStorePassword=YourOwnKeystore.p12-password"

VERY IMPORTANT: 

On Windows: Set this ssl.ini file as "Read Only" and ensure you have a safe copy of this ssl.ini file!

When upgrading the fw Server app to a new version, ensure you use the "Ignore" option when the Installation Wizard stops on this Read Only file, to NOT overwrite this file!

On macOS and Linux Ubuntu: ensure you have a safe copy of this ssl.ini file! And after the upgrade, ensure you are copying it back into the new fw Server app package.

b) On "https.ini apply this change on line 5:

From this: "# --modules=https" ... to this: "--modules=https" to enable this module.

VERY IMPORTANT: 

On Windows: Set this https.ini file as "Read Only" and ensure you have a safe copy of this https.ini file!

When upgrading the fw Server app to a new version, ensure you use the "Ignore" option when the Installation Wizard stops on this Read Only file, to NOT overwrite this file!

On macOS and Linux Ubuntu: ensure you have a safe copy of this https.ini file! And after the upgrade, ensure you are copying it back into the new fw Server app package.

c) On "http.ini apply this change on line 6:

From this: "--modules=http" ... to this: "# --modules=http" to disable this module.

VERY IMPORTANT: 

On Windows: Set this http.ini file as "Read Only" and ensure you have a safe copy of this http.ini file!

When upgrading the fw Server app to a new version, ensure you use the "Ignore" option when the Installation Wizard stops on this Read Only file, to NOT overwrite this file!

On macOS and Linux Ubuntu: ensure you have a safe copy of this http.ini file! And after the upgrade, ensure you are copying it back into the new fw Server app package.

SSLing your fw Client desktop app / iOS fw app access to use your OWN SSL certs:

Step 1:

Copy your certificate.crt and certificate.key to the following folder:

On Windows: 

C:\Program Files\farmerswife Server\html_templates\http_session\ssl_certs\

On mac and Linux Ubuntu: 

/path/to/your/farmerswife Server/html_templates/http_session/ssl_certs/

Step 2:

Rename the already existing server.pem and skey.pem to server.pem.old and skey.pem.old in order to rename: 

certificate.crt to server.pem 

and certificate.key to skey.pem

VERY IMPORTANT: 

On Windows: Set both of these files "server.pem" and "skey.pem" as "Read Only" and ensure you have a safe copy of them!

When upgrading the fw Server app to a new version, ensure you use the "Ignore" option when the Installation Wizard stops on these Read Only files, to NOT overwrite these files!

On macOS and Linux Ubuntu: ensure you have a safe copy of these "server.pem" and "skey.pem" files! And after the upgrade, ensure you copy them back into the new fw Server app package, to replace the ones that are already there.

Modifying farmerswife server config to add https to the URL’s

To automatically add "https" to the URL’s generated by the farmerswife server you need to add one parameter to the server through the optional file "server.cfg", which must be located inside the "system" folder of your farmerswife Server app installation:

Windows: C:\Program Files\farmerswife Server\system\

Mac and Linux: /path/to/your/farmerswife Server/system/

Get more info from here on how to work with the optional "server.cfg" file. On this file you need to modify the following variable to contain the correct domain name used for your certs:

HTTP_HOME https://farmerswife.example.com

Troubleshooting

In case something fails during the process please check the following logs, the following are the logs of the farmerswife server application:

Windows: C:\Program Files\farmerswife Server\system\log.txt

Mac and Linux: /path/to/your/farmerswife Server/system/log.txt

And this one is for the Web Client / Mobile Web Client:

Windows: C:\Program Files\farmerswife Server\system\web_logs\yyyy_mm_dd.stderrout.log

Mac: /path/to/your/farmerswife Server/Contents/system/web_logs/yyyy_mm_dd.stderrout.log

Linux: /path/to/your/farmerswife Server/system/web_logs/yyyy_mm_dd.stderrout.log

How to upgrade your SSLed farmerswife system

Before upgrading your farmerswife server ensure you have a backup of the following files:

• keystore.p12 (which is located in > lib > jetty > jetty-base > etc > )
• ssl.ini (which is located in > lib > jetty > jetty-base > start.d > )
• https.ini (which is located in > lib > jetty > jetty-base > start.d > )
• http.ini (which is located in > lib > jetty > jetty-base > start.d > )
• * server.pem (which is located in > html_templates > http_session > ssl_certs >
• * skey.pem (which is located in > html_templates > http_session > ssl_certs >
  * You only need to backup these 2 files, if you are also here using your own certs.

The reason is that the fw server app installation process for the upgrade will try to overwrite those files as mentioned above. Incase you lose these files, you just need to copy the backup in its correct location.

On Mac you will need to manually copy those files together with your "system" and "files" folder to the new fw Server app package you have downloaded.