Set Up SSL Encryption
SSL (Secure Sockets Layer) is an encryption security protocol that encrypts data transmitted between a client and a server. In FlowForce Server, you can encrypt the following HTTP connections with SSL certificates:
•The connection between a browser and FlowForce Web Server
•The connection between a Web service consumer (e.g., a client application) and the FlowForce Server service
•The internal connection between FlowForce Web Server and FlowForce Server
For the first two connections, you need an SSL certificate and a private key corresponding to that certificate. For security reasons, you might want to use a separate SSL certificate and private key for each connection. If you want to use the same certificate and private key for both connections, this requires that both FlowForce Server and FlowForce Web Server have the same fully qualified domain name (FQDN). For example, if FlowForce Web Server listens on https://somehost:8083, then FlowForce Server should listen on https://somehost:4647. Note that you can always change the port later; only the host name is important in this case.
For the last connection, there is no need for a third certificate and private key pair—you can use the same SSL certificate as for FlowForce Server. In this case, FlowForce Web Server acts as an HTTP client for FlowForce Server.
FlowForce Server Advanced Edition
If you use FlowForce for exchanging AS2 data, you can also use SSL certificates to sign or encrypt data as part of the AS2 service (see AS2 Integration).
SSL encryption precedures
If you need to encrypt communications with the SSL protocol, follow the instructions below. In this example, we have used the open-source OpenSSL toolkit to set up SSL encryption. The steps listed below, therefore, need to be carried out on a computer on which OpenSSL is available. OpenSSL typically comes pre-installed on most Linux distributions and on macOS machines. It can also be installed on Windows computers. For download links to installer binaries, see the OpenSSL Wiki.
SSL requires that a private key be installed on FlowForce Server. This private key will be used to encrypt all data sent to clients. To create the private key, use the following OpenSSL command:
openssl genrsa -out private.key 2048
The command above creates a file called private.key, which contains your private key. Note where you save the file. You will need the private key (i) to generate the Certificate Signing Request (CSR) and (ii) to be installed on FlowForce Server (see Step 7 below). The value 2048 refers to the 2048-bit size of the private key, which is the minimum encryption strength normally accepted by a certification authority.
Private key requirementsBecause FlowForce Server runs unattended, enabling SSL requires that the certificate's private key be unencrypted, which means it must not be protected with a password. Otherwise, the private key cannot be used by FlowForce Server. For this reason, the file that stores the private key must have restricted access and be accessible only to entitled personnel in your organization.
To check whether the private key is password-protected or unencrypted, open the private key file using a text editor or the command line. An encrypted private key begins with the following lines:
-----BEGIN RSA PRIVATE KEY----- Proc-Type: 4,ENCRYPTED DEK-Info: AES-256-CBC,DFC3FAD546517ED6336CFF72AA23F6C7
To decrypt the private key, you can use the following OpenSSL command:
openssl rsa -in enc.key -out dec.key
Note also the following requirements:
•The private key must be in PEM (Privacy Enhanced Mail) format. The file extension of PEM files is usually .pem, but it can also be .key, .cert, .cer, or .crt. •The private key must be stored securely.
|
2.Create a Certificate Signing Request (CSR)
A Certificate Signing Request (CSR) is sent to a certificate authority (CA), such as VeriSign or Thawte, to request a public key certificate. The CSR is based on your private key and contains information about your organization. Create a CSR with the following OpenSSL command (which provides the private-key file, private.key, that was created in Step 1, as one of its parameters):
openssl req -new -nodes -key private.key -out my.csr
During the generation of the CSR, you will need to give information about your organization (listed below). This information will be used by the certificate authority to verify your company's identity.
•Country •Locality (the city where your business is located) •Organization (your company name). Do not use special characters - these will invalidate your certificate. •Common Name (the DNS name of your server). This must exactly match your server's official name, that is, the DNS name that client apps will use to connect to the server. •A challenge password. Keep this entry blank.
|
In the next step, you need to purchase an SSL certificate from a recognized certificate authority (CA), such as VeriSign or Thawte. For the rest of these instructions, we follow the VeriSign procedure. The procedure with other CAs is similar.
1.Go to the VeriSign website. 2.Click Buy SSL Certificates. 3.Different types of SSL certificates are available. For FlowForce Server, Secure Site or Secure Site Pro certificates are sufficient. EV (extended verification) is not necessary, since there is no "green address bar" for users to see. 4.Proceed through the sign-up process and fill in the information required to place your order. 5.When prompted for the CSR (created in Step 2: Create a Certificate Signing Request above), copy and paste the contents of the my.csr file into the order form. 6.Pay for the certificate with your credit card.
Obtaining public key certificates from an SSL certificate authority (CA) typically takes two to three business days. Please take this into account when setting up your FlowForce Server.
Alternative method: Create a self-signed SSL certificateAlternatively, if FlowForce Server runs on a private network, you can configure your own SSL root certification authority (provided you are entitled to do this in your organization). No browser or operating system trusts such an authority by default. Therefore, you will need to configure each machine (or browser, depending on the case) that connects to FlowForce Server to trust your self-signed root certificate. Otherwise, the browser will still display warnings, or the Web service call will not be successful. For more information, see Create Self-Signed SSL Certificates.
|
4.Receive the public key from CA
Your certificate authority will complete the enrollment process over the next two to three business days. During this time, you might get emails or phone calls to check whether you are authorized to request an SSL certificate for your DNS domain. Please work with the authority to complete the process.
After the authorization and enrollment process has been completed, you will get an email containing the public key of your SSL certificate. The public key will be in plain text form or attached as a .cer file.
|
5.Save the public key to a file
For use with FlowForce Server, the public key must be saved in a .cer file. If the public key was supplied as text, copy-paste all the lines from
--BEGIN CERTIFICATE-- ... --END CERTIFICATE--
into a text file that we will call mycertificate.cer.
|
6.Save CA's intermediate certificates to a file
When you sign a certificate with a certificate authority, you will receive a single intermediate certificate or intermediate certificates (primary and secondary) that form the chain of trust between your server and the certificate authority. If you receive a primary certificate and a secondary certificate, you must combine them into a single file (the so-called Certificate Chain File), as shown in the instructions below.
1.Using a text editor such as Notepad, create a new text file. In our example, we have called it intermediate.pem. You can choose another file name and extension. 2.Open each intermediate certificate in a text editor and copy-paste its contents into intermediate.pem. Importantly, the certificate text must be copied in reverse order: The secondary intermediate certificate goes first; the primary one goes second (code listing below).
--BEGIN CERTIFICATE-- ... (secondary intermediate certificate) ... --END CERTIFICATE-- --BEGIN CERTIFICATE-- ... (primary intermediate certificate) ... --END CERTIFICATE
3.Save the changes. You will need intermediate.pem on the FlowForce Setup page later.
|
7.Enable SSL for FlowForce Server/Web Server
The instructions below show you how to enable SSL for FlowForce Web Server (the service which drives the Web administration interface of FlowForce) and FlowForce Server (the service responsible for exposing Web services created from FlowForce jobs to HTTP(S) clients).
To enable SSL for FlowForce Server/Web Server, follow the instructions below:
1.Open the FlowForce Server Setup page and click Configure Parameters. 2.Depending on your needs, navigate to the settings of FlowForce Web Server or FlowForce Server. 3.Select the Enabled check box in the SSL Encrypted Connection section. 4.Select All Interfaces (0.0.0.0) in the Bind address drop-down list. This value means that FlowForce Server/FlowForce Web Server will be accessible externally, not only from the current machine. 5.Enter the host (domain) name and port where FlowForce Server/Web Server should listen to SSL-encrypted connections. The domain name entered in the Host name field must correspond to the SSL certificate's Common Name. The port must not be in use. Depending on the case, you can also enter a different IP address. If you enter an IP address in the Other field without entering a host name, this IP address must correspond to the SSL certificate's Common Name. 6.Enter the path to the certificate in the Certificate File field. The certificate must be in PEM (Privacy Enhanced Mail) format. The file extension of PEM files is usually .pem, but it can also be .key, .cert, .cer, or .crt. The certificate must be issued for the domain name on which FlowForce Server is running. 7.Enter the path to the private key file in the Private Key File field. The private key must be in PEM (Privacy Enhanced Mail) format. The file extension of PEM files is usually .pem, but it can also be .key, .cert, .cer, or .crt. The private key must be stored securely. In order for the private key to be usable in FlowForce, it must not be password protected. 8.Enter the path to the certificate chain file in the Certificate Chain File field. If there is no intermediate certificate, you can leave this field empty. If there are several intermediate certificates available, then you must combine all of them into the so-called Chain File (see Save CA's Intermediate Certificates to a File (Step 6) above). 9.Click Apply settings and restart FlowForce services at the bottom of the Setup page.
Optionally, clear the Enabled check box under Unencrypted Connection. Note that this will make FlowForce Server/Web Server unavailable through plain HTTP, so you should take this step only after the SSL encrypted connection starts working. Instead of disabling the HTTP connection completely, you may want to restrict it to local connections only (the Local only option in the Bind address drop-down list).
Note the following points:
•The browser (or connecting client) will display warnings if the Common Name (CN) of the SSL certificate does not correspond to the domain name or IP address where FlowForce Server runs. •If you are using self-signed certificates, the browser (or connecting client) will display warnings if you have not added your CA root certificate to the operating system's certificate store or to the browser's certificate store (see Import Root Certificates)
|
You can now use any SSL testing tool to check whether secure communication with your server via HTTPS is working properly. This will tell you (i) whether the public key certificate file was properly constructed with the intermediate trust chain in Step 6, and (ii) whether your server can be reached properly through the firewall.
|