Frequently Asked Questions

10.1. The simplest way to set up two-way TLS

Setting up set up two-way TLS

Abstract

The following steps show one possible way to set up two-way TLS on a single machine.

1. Creating certificates

   use openssl to generate certificates, if openssl isn't in the path then use full path to openssl.exe.

   Use OpenSSL ? 1.1.1 Binaries for Windows: download link.

   The variable subjectAltName required for accessing Fairy via Chrome; Chrome will complain if TLS version <1.2 or certificate doesn't contain subjectAltName.

   cd "C:\Program Files (x86)\RenderX\InGrid"
   # create selfsigned certificate and private key for server
   openssl req -new -x509 -days 365 -nodes -out serverCert.pem \
     -keyout serverKey.pem -subj "/CN=localhost" \
     -addext "subjectAltName=DNS:localhost,IP:127.0.0.1" \
   # create selfsigned certificate and private key, don't care
   # about any info for client so use -subj to avoid questions
   openssl req -new -x509 -days 365 -nodes -out clientCert.pem \
     -keyout clientKey.pem -subj "/CN=FairyClient"
   

   Note: For different machines the procedure is the same, but files need to be copied and change 'localhost' to corresponding hosts names.

2. Configure IREn InGrid to use created certificates.

   IREn InGrid config should contain the following:

   <option name="use-https" value="True"/>
   <option name="server-ssl-certfile"
     value="C:\Program Files (x86)\RenderX\InGrid\serverCert.pem"/>
   <option name="server-ssl-keyfile"
     value="C:\Program Files (x86)\RenderX\InGrid\serverKey.pem"/>
   
   <option name="mutual-authentication" value="True"/>
   <option name="ca-certs-file"
     value="C:\Program Files (x86)\RenderX\InGrid\clientCert.pem"/>
   

3. Start IREn InGrid

   Start IREn InGrid as Windows service by invoking the following command:

   net start ingrid
   

   IREn InGrid should be started as Windows service (it will use C:\Program Files (x86)\RenderX\InGrid\ingrid.conf as its config)

4. Use this Sample Client

   This sample Client can be build to Client.jar by provided build.bat

   Format single document from examples using this sample Client:

   java -jar Client.jar -url https://localhost:6577/fairy \
     -trustedCertsFile "C:\Program Files (x86)\RenderX\InGrid\serverCert.pem" \
     -clientCert "C:\Program Files (x86)\RenderX\InGrid\clientCert.pem"
     -clientPrivateKey "C:\Program Files (x86)\RenderX\InGrid\clientKey.pem" \
     "C:\Program Files\RenderX\XEP\examples\basic\linebreak.fo"
   

   Do not forget to disable detailed logging after verifying that everything works and before doing performance tests

   Format the same document from examples 1000 times and do not save formatted pdfs to disk(useful for performance testing):

   java -jar Client.jar -url https://localhost:6577/fairy \
     -trustedCertsFile "C:\Program Files (x86)\RenderX\InGrid\serverCert.pem" \
     -clientCert "C:\Program Files (x86)\RenderX\InGrid\clientCert.pem" \
     -clientPrivateKey "C:\Program Files (x86)\RenderX\InGrid\clientKey.pem" \
     -amount 1000 -writeFormattedDocsOnDisk false
     "C:\Program Files\RenderX\XEP\examples\basic\linebreak.fo"
   

Example for generating certificates

openssl req -new -x509 -days 365 -nodes -out clientCert.pem \
  -keyout clientKey.pem

req - PKCS#10 certificate request and certificate generating utility.

Read full documentation at OpenSSL.org.

-x509 option outputs a self signed certificate instead of a certificate request. Otherwise the certificate request will be generated.

Note: ATTENTION!

When creating a certificate or submitting a certificate request you will be asked for several parameters. Pay attention to CN field. By default you'll be asked for "Common Name (e.g. server FQDN or YOUR name)", and your answer should correspond to the server's name you're going to use this certificate on. Certificate won't be valid otherwise.

Certificate requests can be signed using x509 utility, download link

Example:

Sign a certificate request using the CA certificate above and add user certificate extensions:

openssl x509 -req -in req.pem -CA cacert.pem -CAkey key.pem \
  -CAcreateserial -out signedCert.pem