To secure your Linx solutions and set up your Linx Server to the correct ports on your server, you’ll need to work with SSL Certificates. Linx Server already contains an SSL certificate, which is valid and secure, but because it is self signed it may not be accepted in certain situations.
SSL Certificates use two keys which are long strings of seemingly randomly generated numbers. One is called a private key and one is called a public key. A public key is known to your server and available in the public domain. It can be used to encrypt any message. The private key is needed to decrypt the message. Thus, even if a message is intercepted, it cannot be decrypted without the private key.
Depending on you solution, Linx uses these Certificates in multiple ways, sometimes playing the role of Server (having both the public and private keys) and sometimes being a Client / Consumer (only with the public key).
Some key areas where you’d want to create or obtain an SSL certificate for your Linx solution:
- Linx Server (It comes with an SSL certificate already, but in some organisations, they require their own certificates to be used)
- REST and SOAP Web services
- FTP Authentication
- Web hooks
Here’s how to create and use a self-signed SSL certificates with Linx:
1. Create your own certificate (skip this step if you’re getting a certificate from a Certificate Authority or from your IT Security team)
Note: This certificate is called a “Self signed certificate” which means it was not issued through a recognised Certificate Authority, but it still secures and encrypts your data. Your web browser will complain about the legitimacy of the certificate, but as you’ve created the certificate yourself, you can ignore the warning.
- Download the appropriate version of OpenSSL for your version of Windows from: Win32/Win64 OpenSSL Installer for Windows - Shining Light Productions
The light version (3Mb) will suffice. - Install the version and make a note of the directory where you are installing as you will need it later. If you get the option to choose, install the “bin” folder in the application’s own folder.
- Open Command Prompt
- Navigate to the /bin directory in the OpenSSL install directory (eg “cd C:\OpenSSL-Win64\bin”).
- To generate a private key called “sslprivatekey” run the following command:
openssl genrsa -out sslprivatekey.pem 1024
- To create an X509 certificate (.cer file) containing your public key run the following command:
openssl req -new -x509 -key sslprivatekey.pem -out sslpublickey.cer -days 1825
- You will be prompted to complete several fields. The information provided will then be incorporated into your certificate request. To leave a field blank, simply enter ‘.’
- To export your x509 certificate and private key to a pfx file. run the following command (take note of the friendly name given):
openssl pkcs12 -export -out sslpublic_privatekey.pfx -inkey sslprivatekey.pem -in sslpublickey.cer -name “LinxTestCert”
- You will be prompted to enter your Export password and confirm it. Make a note of your password as you will need it later.
- To import this key into your system for Linx to use, double click on the PFX file and select import.
2. Now you’ll have an SSL Certificate (with a private key) installed on your system. You need to obtain it’s thumbprint (you don’t need to obtain the thumbprint if you are going to use Powershell to bind the certificate to the ports as described below in the next section.):
- Click on your start button and type in “Certificate”. Choose an option like “Manage computer certificates”
- Find your new certificate, normally under the Personal, Certificates heading, and double click on it
- On the details tab, find your certificate’s “Thumbprint”. Click on it and copy the whole string in the box. This code uniquely identifies the certificate on your system.
- VERY IMPORTANT: When copying the thumbprint for a certificate, there are almost always a hidden character in front of the certificate. Notepad cannot show this character, use a more advanced text editor with the option to show hidden characters. You can also change the Text encoding to “ANSI” which will show the hidden character immediately. Delete these characters and all the spaces.
- You should now have something which resembles a long string of numbers and letters. Keep this safe for now.
(i.e. 397a5f046b5c82db948ddcf55c7ccf1af8708ae5)
3. Linx Server
When using Linx Server, you’ll notice that your browser will complain about the privacy of your connection. You can check the certificate used by default and see that it was issued by Twenty57. Although we know that the connection is secure, the browser cannot confirm the authenticity of the current certificate, and as such must give the user a warning. In some circumstances you would need to correct this issue, especially in production systems.
To set up a different certificate, you’ll need to bind your new certificate to the port you are using with Linx Server.
There are 2 ways to bind the certificate, through 1. Command Prompt, or through 2. Powershell.
1. Binding a certificate with Command Prompt (Longer route):
- Run Command Promt (with Administrator rights)
- Using the thumbprint you obtained in the previous steps, use the following command, all in one line (Note the port number, you can change it to whatever port you need, and add your thumbprint for the certhash):
netsh http add sslcert ipport=0.0.0.0:9023 certhash=d7bd8d21761135c12249cb1467a5caed6c6efc07 appid={00000000-0000-0000-0000-000000000000}
- Restart your Linx Service
- If needed you’ll have to open up the port in Windows Firewall to allow access to your Linx Server from outside of the machine.
2. Binding a certificate with Powershell:
- Create a script (i.e. BindPort.ps1 file) with the following (Change the port numbers and Certificate Friendly name):
#open the port on the windows firewall - Change Port Number here
New-NetFirewallRule -Name “Linx Api” -DisplayName “Linx Api” -Enabled True -Profile “Any” -Action “Allow” -Direction “Inbound” -LocalPort 9023 -Protocol “TCP”#BIND THE INSTALLED CERT TO THE PORT TO ENABLE HTTPS - Change Cert FriendlyName and port numbers here
$thumbprint = (Get-ChildItem -Path Cert:\LocalMachine\My | Where-Object {$_.FriendlyName -match “LinxTestCert”}).Thumbprint
netsh http delete sslcert ipport=0.0.0.0:9023
netsh http add sslcert ipport=0.0.0.0:9023 certhash=$thumbprint appid=‘{00000000-0000-0000-0000-000000000000}’
- Run Powershell, and run the script
./BindPort.ps1
- Restart your Linx service
Change Linx Server Port number:
- To change the port number of your Linx Server, find the “Twenty57.Linx.Server.Core.exe.config" file, usually at:
“C:\Program Files (x86)\Twenty57 Linx Server 5\Bin\Server\Twenty57.Linx.Server.Core.exe.config”
- Find the port number under appSettings tag
- Change the port number to your desired port, i.e.
<appSettings> <add key="WebServerPort" value="9023" /> </appSettings>
- Bind your SSL certificate to the new port number using steps described in the previous section.
- Restart Linx Server service.
Rest Web Services
-
Firstly, when creating Rest Web Services, you provide a “Base URI”. Make sure that the URI is https. This will then look for a secured connection. Also, remember the port number you want to use.
-
Bind your SSL certificate to the new port as described above.
-
Deploy your solution and it should now be available over secured SSL.
SOAP Web Services
-
As with REST, you need to make sure the address provided is an https address and the correct port
-
Bind your SSL Certificate to the new port
-
Deploy you solution and test