TechStunnel: Difference between revisions

From Redrock Wiki

No edit summary
No edit summary
Line 4: Line 4:
{| style="width:100%; vertical-align:top; "
{| style="width:100%; vertical-align:top; "


| style="vertical-align:top; font-size:160%; color:#7c1911; " | '''Use SSL Encryption to Secure Your Trac System''' <HR>
<span style="vertical-align:top; font-size:160%; color:#7c1911;"><big>HTTPS Connections to your Trac System</big></span><HR>


|-
The Trac System doesn't inherently support secure connections over HTTPS, a proxy such as Stunnel must be used to facilitate this instead. Other proxies may be used, but Stunnel is the only option that Redrock Software can offer support for. If your Trac System is hosted by Redrock, you will already be able to connect over HTTPS using our domain name (example.go-redrock.com). If you would like to use a custom domain for your hosted system, create a CNAME record pointing to <span style="color:red">rscprxy.go-redrock.com</span> and provide an Apache X509-compatible certificate and key to us. The cert and key can be uploaded to our SFTP server (same location as your import files). We are unable to provide CSR/.req files. For non-hosted instances, continue reading.
| style="vertical-align:top; font-size:120%; " | <br />Transport Layer Security (TLS) and Secure Sockets Layer (SSL) are cryptographic protocols that provide secure communications on the Internet. There are slight differences between SSL and TLS, but they essentially provide the same protection.<br /><br />


|-
<hr>
| style="vertical-align:top; font-size:140%; color:#7c1911; " | For Hosted Systems <HR>
<big><span style="color:#7c1911">Stunnel / Proxies</big></span><br>
|-
| style="vertical-align:top; font-size:100%; " | If we host your Trac System, adding or updating your SSL certificate is a straightforward process.


1. '''Provide us with an Apache x509 Compatible certificate, along with any intermediate/root files and the matching key'''.
There are several options for implementing HTTPS for your Trac server. A web server for HTTPS proxying such as Apache or Nginx can be used, or you can utilize a dedicated proxying application such as HAProxy. These could be running on the same or a separate server. Only internal traffic between the proxy and the Trac System would be in plaintext. As an alternative, a 3rd party application (like Stunnel) may be installed on your Trac System server. The latter is what we at Redrock are able to offically support.


2. '''If a custom URL is being used, point your domain to <span style="color:red">rscprxy.go-redrock.com</span>'''. This will allow you to use a URL other than "school.go-redrock.com", for example, "tutortrac.school.edu" or otherwise.
Stunnel is a program that encrypts all connections to your server. Stunnel facilitates this by acting as a proxy between users' browsers and the Trac application. A user would open a web browser and enter in your server address, e.g., '''<nowiki>https://trac.example.edu/</nowiki>'''. Stunnel receives the encrypted request, decrypts the request, and then forwards the request to the Trac application. The Trac application will then issue a response back to Stunnel, Stunnel encrypts the response, and then forwards the encrypted response back to the user's browser. With this method, all network traffic from the server to the client is encrypted while the Trac application communicates with Stunnel locally in an unencrypted format.


<hr>
<big><span style="color:#7c1911">Installing Stunnel</big></span><br>


|-
Click [https://www.stunnel.org/downloads.html on this link] to download and install the latest stable win64-installer. Once the .exe file has downloaded, install Stunnel using the default options. If you already have a certificate, you can close the prompt to generate a certificate/CSR that appears during installation.
| style="vertical-align:top; font-size:140%; color:#7c1911; " | For Non-Hosted Systems
<BR>HTTPS Encryption and Web Certificate <HR>


|-
<hr>
| style="vertical-align:top; font-size:100%; " |There are several options for implementing TLS encryption for your Trac server.  A preferred method is to use a web server for https proxying such as Apache or Nginx.  Another option is using a dedicated proxying application such as HAProxy.  Both of these could be running on a separate physical server.  Only internal traffic between the proxy and the Trac System server would then be plaintext. As an alternative, a 3rd party application (like Stunnel) may be installed on your Trac System server.<br /><br />
<big><span style="color:#7c1911">Certificate Format</big></span><br>


|-
The necessary SSL files are a certificate (typically cert.pem) and a key file (typically key.pem). You will need to obtain your own Apache X509-compatible certificate from any trusted Certificate Authority. Some CAs will provide you with a chained certificate, which we will have to combine in order to make the file compatible. Place the certificate and key files in your Stunnel config directory (C:\Program Files (x86)\stunnel\config). Keep a copy of your req.pem (CSR) file to request your new certificate when it expires.
| style="vertical-align:top; font-size:140%; color:#7c1911; " | What is Stunnel? <HR>


|-
In the event that you only have a .pfx file available, it can be split into separate certificate and key files for use in Stunnel with the following OpenSSL commands.
| style="vertical-align:top; font-size:100%; " | Stunnel is a program that encrypts all data connections to your Trac server. Stunnel facilitates this by acting as a proxy between users' browsers and the Trac application. So, a user would open web browser and enter in your server address, i.e. '''<nowiki>https://trac.go-redrock.com/</nowiki>'''. Stunnel receives the encrypted request, decrypts the request, and then forwards the request to the Trac application. The Trac application will then issue a response back to Stunnel, Stunnel encrypts the response, and then forwards the encrypted response back to the user's browser. With this method, all network traffic from the server to the client is encrypted while the Trac application communicates with Stunnel in an unencrypted format.<br /><br />
<syntaxhighlight style="border: 1px dashed black" lang="bash">
openssl pkcs12 -in input.pfx -clcerts -nokeys -out output.crt
openssl pkcs12 -nocerts -in input.pfx -out output.key -nodes
</syntaxhighlight>


|-
<hr>
| style="vertical-align:top; font-size:140%; color:#7c1911; " | Installing Stunnel <HR>
<big><span style="color:#7c1911">Stunnel Config File</big></span><br>


|-
The Stunnel configuration file (stunnel.conf) is located in the C:\Program Files (x86)\stunnel\config directory by default and must be edited. Below is a good default config file. Simply replace the contents of stunnel.conf with this, replacing the IP address and cert/key file names as needed.<br /><br />
| style="vertical-align:top; font-size:100%; " | Click  [https://www.stunnel.org/downloads.html on this link] to download and install the latest stable win64-installer. Once the .exe file has downloaded, install Stunnel using the default options.<br /><br />
 
|-
| style="vertical-align:top; font-size:140%; color:#7c1911; " | Secure Certificate Files <HR>
 
|-
| style="vertical-align:top; font-size:100%; " | The necessary SSL Files are a certificate (typically cert.pem) and a key  file (typically key.pem). You will need to obtain your own Apache X509-compatible certificate from a "Trusted" source, such as DigiCert, GoDaddy, or VeriSign. These are just a few of the options available to you; in all, the mainstream browsers (Firefox, Chrome, Safari, etc) only trust about 100 of the major Certificate Authorities (CA).<br /><br />
 
If you choose to obtain your own certificate, be sure to retrieve an Apache X509-compatible certificate, as this is the only certificate type that is compatible with the Trac System. Some CA's will provide you with a chained certificate, which we will have to combine in order to make the file compatible. Place the certificate and key files in your  Stunnel installation directory (C:\Program Files (x86)\stunnel). Keep a copy of your req.pem (CSR) file to request your new certificate when it expires.<br /><br />
 
|-
| style="vertical-align:top; font-size:140%; color:#7c1911; " | Stunnel Config File <HR>
 
|-
| style="vertical-align:top; font-size:100%; " | The Stunnel configuration file (Stunnel.conf) is located in the C:\Program Files (x86)\stunnel\ directory. You will need to edit this file to secure your Trac site. Below is a good default config file. Simply replace the contents of Stunnel.conf with this, and edit the IP Address on line 17.<br /><br />


'''Sample stunnel configuration file by Redrock Software'''<br />
'''Sample stunnel configuration file by Redrock Software'''<br />
 
<syntaxhighlight style="border: 1px dashed black" lang="ini">
  ; identify the private key and public certificate files
  ; identify the private key and public certificate files, placed in the config directory
  cert = cert.pem
  cert = cert.pem
  key = key.pem
  key = key.pem
Line 64: Line 48:
  ; Service-level configuration
  ; Service-level configuration
  [https]
  [https]
  accept = 192.168.0.1:443
  accept = 192.168.0.42:443
  connect = 192.168.0.1:81
  connect = 192.168.0.42:81
  TIMEOUTclose = 0
  TIMEOUTclose = 0


|-
; Force TLS 1.2
| style="vertical-align:top; font-size:140%; color:#7c1911; " | Trac System Prefs.ini File <HR>
options = NO_SSLv2
 
options = NO_SSLv3
|-
sslVersionMin = TLSv1.2
| style="vertical-align:top; font-size:100%; " | Open the Prefs.ini file in the Trac application folder. Edit the following lines to match the sample values.<br />
</syntaxhighlight>
 
<!----------- Prefs.ini ------------>
If a school is NOT using stunnel at all, set:
<hr>
 
<big><span style="color:#7c1911">Trac System Prefs.ini File</big></span><br>
serverProcs=15
serverProcs2=0
redirect=None
 
If a school is using stunnel, but redirect=None,
 
serverProcs=15
serverProcs2=2
 
If a school is using stunnel, and redirect=https<nowiki/>://whatever.site, (it is set to a url)
 
serverProcs=2
serverProcs2=15
 
Full example:
 
[Server]
serverPort=80
serverPort2=81
serverProcs=15
serverProcs2=2
serverSecure=NO
serverSecure2=NO
 
The  Trac application is now listening for standard HTTP connections on port  80. Those connections will come from users accessing the Trac  application across the network. The Trac application is also listening  for standard HTTP connections on port 81. The HTTP connections on port  81 are coming from the Stunnel application, which is listening for HTTPS  connections on port 443.<br /><br />


|-
After installing Stunnel, go to your Trac installation folder, and edit /database/prefs.ini. Edit the following lines depending on your configuration, the Trac System must be restarted to apply changed.
| style="vertical-align:top; font-size:140%; color:#7c1911; " | Force All Connections on Secure Port <HR>


|-
If your installation is not using Stunnel and is only accessible via HTTP.
| style="vertical-align:top; font-size:100%; " | After the server connections have been tested and confirmed on ports 80 and 443, you can now force all users to connect on the secure port 443. Open the Prefs.ini file in the Trac application folder and make the following change:<br />
<syntaxhighlight style="border: 1px dashed black" lang="ini">
[Server]
serverPort=80
serverPort2=
serverProcs=15
serverProcs2=0
redirect=None
redirect2=None
</syntaxhighlight>


redirect=https://[Your URL]/tracweb40/default.html
If your installation is using Stunnel and will be accessible via HTTPS.
<syntaxhighlight style="border: 1px dashed black" lang="ini">
[Server]
serverPort=80
serverPort2=81
serverProcs=5
serverProcs2=15
redirect=https://your.trac.domain.edu
redirect2=None
</syntaxhighlight><br>


The Trac application now listens for a standard HTTP connection on port 80 and redirects all requests to the address entered in the redirect  setting, which should be your secure HTTPS address. Now the connection  is on the secure HTTPS port 443 and Stunnel receives the request.  Stunnel makes the local HTTP connection to the Trac application on port 81 and responds back to the user's browser on the secure port 443. All  network traffic on your Trac system is directed to the secure connection  on port 443.<br /><br />
The 'serverPort' variables determine what ports your Trac System is accessible at. The purpose of the second port is for proxies like Stunnel, as incoming connections on port 80 can be redirected to 443 and Stunnel can communicate locally with Trac over port 81 (or any other preferred port).<br><br>


|-
The 'serverProcs' variables are effectively the processing resources available on each port. The sum total of these two variables should not exceed 20. If your Trac System is only available on port 80, then serverProcs can be set to 15 and serverProcs2 can be 0 (unused). If Stunnel is used, the only purpose of port 80 will be to redirect users to 443 (81 internally). In this case, serverProcs2 should be set to 15 and serverProcs doesn't need as much as it will only be redirecting users.<br><br>
| style="vertical-align:top; font-size:140%; color:#7c1911; " | Configure Stunnel as a Service <HR>


|-
The 'redirect' variables determine where users are sent when they reach the Trac System on each port. If your Trac System is only accessible on port 80, both redirect variables can be left as "None" as there's nowhere to redirect to. If Stunnel is used, redirect (not redirect2) should send users to your Trac System's https:// URL.<br><br>
| style="vertical-align:top; font-size:100%; " | To set stunnel as a service, run the following command in a Command Prompt window.<br />


stunnel.exe -install
'ServerSecure' and 'ServerSecure2' should both be kept at the default value of 'None' in either case.
<!----------- Stunnel Service ------------>
<hr>
<big><span style="color:#7c1911">Configure Stunnel as a Service</big></span><br>


You  will receive a prompt informing you that the service was installed. You  can now access the Services from your Administrator Tool and start  Stunnel as a service.<br /><br />
To install Stunnel as a service, run the following command in a Command Prompt window. Note that the Stunnel service and Stunnel application (started from the /bin folder) cannot run at the same time and will cause errors. Always stop the Stunnel application before starting the service, and vice versa.


|}
<syntaxhighlight style="border: 1px dashed black" lang="text">
|-
stunnel.exe -install
| style="width:250px; vertical-align:top; padding:0px 0px 0px 0px;" |
</syntaxhighlight>
| style="vertical-align:top; padding:0px 0px 0px 2px;" |


<!-- this table appears at the bottom of the manual page and contains a previous page and next page link  -->
{| style="width:70%; vertical-align:top; "
| style="width:50%; text-align:left;" | [[TechAsService|&larr; Previous Page]]
| style="width:50%; text-align:right;" | [[TechEmailTool|Next Page &rarr;]]


|}
|}
__NOTOC__
__NOTOC__
[[Category:Trac 4]]
[[Category:Trac 4]]

Revision as of 16:42, 12 October 2023

Tech Documentation

• Installation

• Windows DEP

• Service Setup

• TLS Encryption

• Mail Server

• SSO Authentication

• Data Imports

• Barcode Scanners

• Trac 4.0 Updates

• Migrating to TracCloud

HTTPS Connections to your Trac System

The Trac System doesn't inherently support secure connections over HTTPS, a proxy such as Stunnel must be used to facilitate this instead. Other proxies may be used, but Stunnel is the only option that Redrock Software can offer support for. If your Trac System is hosted by Redrock, you will already be able to connect over HTTPS using our domain name (example.go-redrock.com). If you would like to use a custom domain for your hosted system, create a CNAME record pointing to rscprxy.go-redrock.com and provide an Apache X509-compatible certificate and key to us. The cert and key can be uploaded to our SFTP server (same location as your import files). We are unable to provide CSR/.req files. For non-hosted instances, continue reading.

Stunnel / Proxies

There are several options for implementing HTTPS for your Trac server. A web server for HTTPS proxying such as Apache or Nginx can be used, or you can utilize a dedicated proxying application such as HAProxy. These could be running on the same or a separate server. Only internal traffic between the proxy and the Trac System would be in plaintext. As an alternative, a 3rd party application (like Stunnel) may be installed on your Trac System server. The latter is what we at Redrock are able to offically support.

Stunnel is a program that encrypts all connections to your server. Stunnel facilitates this by acting as a proxy between users' browsers and the Trac application. A user would open a web browser and enter in your server address, e.g., https://trac.example.edu/. Stunnel receives the encrypted request, decrypts the request, and then forwards the request to the Trac application. The Trac application will then issue a response back to Stunnel, Stunnel encrypts the response, and then forwards the encrypted response back to the user's browser. With this method, all network traffic from the server to the client is encrypted while the Trac application communicates with Stunnel locally in an unencrypted format.

Installing Stunnel

Click on this link to download and install the latest stable win64-installer. Once the .exe file has downloaded, install Stunnel using the default options. If you already have a certificate, you can close the prompt to generate a certificate/CSR that appears during installation.

Certificate Format

The necessary SSL files are a certificate (typically cert.pem) and a key file (typically key.pem). You will need to obtain your own Apache X509-compatible certificate from any trusted Certificate Authority. Some CAs will provide you with a chained certificate, which we will have to combine in order to make the file compatible. Place the certificate and key files in your Stunnel config directory (C:\Program Files (x86)\stunnel\config). Keep a copy of your req.pem (CSR) file to request your new certificate when it expires.

In the event that you only have a .pfx file available, it can be split into separate certificate and key files for use in Stunnel with the following OpenSSL commands. 

openssl pkcs12 -in input.pfx -clcerts -nokeys -out output.crt
openssl pkcs12 -nocerts -in input.pfx -out output.key -nodes

Stunnel Config File

The Stunnel configuration file (stunnel.conf) is located in the C:\Program Files (x86)\stunnel\config directory by default and must be edited. Below is a good default config file. Simply replace the contents of stunnel.conf with this, replacing the IP address and cert/key file names as needed.

Sample stunnel configuration file by Redrock Software

 ; identify the private key and public certificate files, placed in the config directory
 cert = cert.pem
 key = key.pem
 
 ; Some performance tunings
 socket = l:TCP_NODELAY=1
 socket = r:TCP_NODELAY=1
 
 ; Service-level configuration
 [https]
 accept = 192.168.0.42:443
 connect = 192.168.0.42:81
 TIMEOUTclose = 0

; Force TLS 1.2
options = NO_SSLv2
options = NO_SSLv3
sslVersionMin = TLSv1.2

Trac System Prefs.ini File

After installing Stunnel, go to your Trac installation folder, and edit /database/prefs.ini. Edit the following lines depending on your configuration, the Trac System must be restarted to apply changed.

If your installation is not using Stunnel and is only accessible via HTTP. 

[Server]
serverPort=80
serverPort2=
serverProcs=15
serverProcs2=0
redirect=None
redirect2=None

If your installation is using Stunnel and will be accessible via HTTPS. 

[Server]
serverPort=80
serverPort2=81
serverProcs=5
serverProcs2=15
redirect=https://your.trac.domain.edu
redirect2=None

The 'serverPort' variables determine what ports your Trac System is accessible at. The purpose of the second port is for proxies like Stunnel, as incoming connections on port 80 can be redirected to 443 and Stunnel can communicate locally with Trac over port 81 (or any other preferred port).

The 'serverProcs' variables are effectively the processing resources available on each port. The sum total of these two variables should not exceed 20. If your Trac System is only available on port 80, then serverProcs can be set to 15 and serverProcs2 can be 0 (unused). If Stunnel is used, the only purpose of port 80 will be to redirect users to 443 (81 internally). In this case, serverProcs2 should be set to 15 and serverProcs doesn't need as much as it will only be redirecting users.

The 'redirect' variables determine where users are sent when they reach the Trac System on each port. If your Trac System is only accessible on port 80, both redirect variables can be left as "None" as there's nowhere to redirect to. If Stunnel is used, redirect (not redirect2) should send users to your Trac System's https:// URL.

'ServerSecure' and 'ServerSecure2' should both be kept at the default value of 'None' in either case.

Configure Stunnel as a Service

To install Stunnel as a service, run the following command in a Command Prompt window. Note that the Stunnel service and Stunnel application (started from the /bin folder) cannot run at the same time and will cause errors. Always stop the Stunnel application before starting the service, and vice versa. 

stunnel.exe -install
Retrieved from "https://wiki.go-redrock.com/index.php?title=TechStunnel&oldid=8005"