This quick guide describe how to setup certificates used by the certificate authority within EnginFrame.

========================================================================================================================
 Create self-signed certificates with the tomcatssl-certificates.sh tool
========================================================================================================================

In the following section we describe how to create self-signed certificates using the tomcatssl-certificates.sh tool.
In case you have a valid Certification Authority we suggest to create CA-signed certificates instead of self-signed ones.

For simplicity the passwords used in this example are "passwordtest" for the EF Tomcat Server certificates and "clientpassword"
for the Client password.

In this example the alias of the Enginframe certificate is "enginframe". The alias of the client where library will be used
is "myClient".

The tool to create self-signed certificates is provided under the directory ${EF_ROOT}/tools. It is called
tomcatssl-certificates.sh. In order to use it, please export the Java Home path into environment.

export JAVA_HOME=/usr/java/jdk1.8.0_92/

To generate the self-signed certificate use the following command:

echo "passwordtest" | sh tomcatssl-certificates.sh - generate --tomcatuser efnobody --client-auth --client-password clientpassword --ef-alias enginframe --client-aliases myClient

(In case of multiple client aliases, the command should be translated to:
    echo "passwordtest" | sh tomcatssl-certificates.sh - generate --tomcatuser efnobody --client-auth --client-password clientpassword --ef-alias enginframe --client-aliases 'myClient1 myClient2'
)

The certificates will be generated under the ${EF_CONF_ROOT}/tomcat/conf/certs folder.

-rw------- 1 root     root       10 Mar  9 08:59 client.keystore.password
-rw------- 1 root     root     1267 Mar  9 08:59 enginframe.agent.cert
-rw------- 1 root     root     2230 Mar  9 08:59 enginframe.agent.keystore
-rw------- 1 root     root      940 Mar  9 08:59 enginframe.agent.truststore
-rw------- 1 root     root       41 Mar  9 08:58 ef.keystore.password
-rw------- 1 efnobody root     1267 Mar  9 08:59 enginframe.tomcat.cert
-rw------- 1 efnobody root     2229 Mar  9 08:59 enginframe.tomcat.keystore
-rw------- 1 efnobody root     1848 Mar  9 08:59 enginframe.tomcat.truststore
-rw------- 1 root     root     1267 Mar  9 08:59 myClient.client.cert
-rw------- 1 root     root     2556 Mar  9 08:59 myClient.client.cert.p12
-rw------- 1 root     root     2230 Mar  9 08:59 myClient.client.keystore
-rw------- 1 root     root      940 Mar  9 08:59 myClient.client.truststore

========================================================================================================================
 Configure keystore and truststore on EnginFrame Apache Tomcat
========================================================================================================================

The generated EnginFrame keystore and truststore files will be copied to ${EF_CONF_ROOT}/tomcat/conf/certs folder
with the right ownsership and permission. Remember that file permissions of those files must be 600.

Modify ${EF_CONF_ROOT}/tomcat/conf/server.xml configuration and add:

<Connector
    clientAuth="true"
    port="8443"
    minSpareThreads="5"
    protocol="HTTP/1.1"
    enableLookups="true"
    disableUploadTimeout="true"
    URIEncoding="utf-8"
    acceptCount="100"
    maxThreads="200"
    scheme="https"
    secure="true"
    SSLEnabled="true"
    keystoreFile="conf/certs/enginframe.tomcat.keystore"
    keystoreType="JKS"
    keystorePass="passwordtest"
    keyAlias="enginframe"
    truststoreFile="conf/certs/enginframe.tomcat.truststore"
    truststoreType="JKS"
    truststorePass="passwordtest"
    sslProtocol="TLS"
    server="Apache" />

The file paths for the attributes keystoreFile and truststoreFile can be specified using a URL, an absolute path or
a relative path to ${EF_CONF_ROOT}/tomcat/.

For security purposes we suggest to close the HTTP Connector commenting it.
In this way only secured HTTPs connections will be possible from outside.

<!--
<Connector
    port="8080"
    maxHttpHeaderSize="8192"
    maxThreads="150"
    minSpareThreads="25"
    enableLookups="false"
    redirectPort="8443"
    acceptCount="100"
    connectionTimeout="20000"
    disableUploadTimeout="true"
    URIEncoding="utf-8"/>
-->

Set EF_DEFAULT_AUTHORITY=certificate inside the configuration file ${EF_CONF_ROOT}/enginframe/server.conf

This will enable EnginFrame authentication using authorized trusted certificates. By default the client has to provide
the user name to log in. User mapping is also possible.

If you chose the authority certificate during EnginFrame installation, the installer does all the previous step
for you, creating self-signed certificates and configuring the Apache Tomcat connector.

========================================================================================================================
 Testing with Browser
========================================================================================================================

For testing purpose, you can connect a browser to EnginFrame via HTTPs.
In this example Firefox Browser will be used to connect to the EnginFrame portal, but first a valid certificate
has to be imported.

Import the client p12 certificate into Firefox "Your Certificates" page, using the client password "clientpassword".

Open the link with Firefox

https://enginframe:8443/enginframe/demo/showcase/showcase.xml?_service=job.submission

Accept the self-signed server certificate

Submit the job after selecting a file to compress. (This step require you have installed EnginFrame Demo Documentation)

========================================================================================================================
 Configure keystore and truststore on client side
========================================================================================================================

Copy the myClient.client.keystore and myClient.client.truststore to a secure location on the client host.
In the following example we will use: E:\certificate\myClient.client.keystore

Setup the environment of the client application with the following Java properties

-Djavax.net.ssl.keyStore="E:\certificate\myClient.client.keystore"
-Djavax.net.ssl.keyStorePassword=clientpassword
-Djavax.net.ssl.trustStore="E:\certificate\myClient.client.truststore"
-Djavax.net.ssl.trustStorePassword=clientpassword

For example, if you have a Windows application with a startup script located in
C:\app\jboss_start.cmd, then add the following Java options at the bottom:

set JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.keyStore="E:\certificate\myClient.client.keystore"
set JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.keyStorePassword=clientpassword
set JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.trustStore="E:\certificate\myClient.client.truststore"
set JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.trustStorePassword=clientpassword

The client can now connect and be trusted by EnginFrame

========================================================================================================================
 Using certificates different from self-signed ones
========================================================================================================================

If you already have certificates different from self-signed ones, you should read Apache Tomcat documentation in order
to configure the connector in the right way.

https://tomcat.apache.org/tomcat-9.0-doc/ssl-howto.html

Depending on the certificate format in which you received the certificate from the Certificate Authority,
there are different ways of configuring the Apache Tomcat connector.

For example, you can choose to convert your PEM private key and PEM CA issued certificate to a format that can be
handled by the Java keystore, as recommended by the Apache Tomcat documentation. To do this, first convert them to
PKCS12 format, doing the following:

openssl pkcs12 -export -in <your_CA_signed_PEM_cert> -inkey <your_PEM_private.key> -out <your_certificate_name>.p12 -name tomcat -chain -CAFile <your_root_CA_certificate>

Then import the created PKCS12 certification into a Java keystore file:

keytool -importkeystore -deststorepass <password> -destkeypass <password> -destkeystore tomcat.keystore -srckeystore <exported_private_key_and_cert.p12> -srcstoretype PKCS12 -srcstorepass <password> -alias tomcat

If your CA has intermediate certificates, you should import them into the new keystore just created.
It is very likely that your CA will provide instructions on how to do this and how the certificates should be named.

For example, doing:

keytool -import -alias cross -keystore tomcat.keystore -trustcacerts -file gd_cross_intermediate.crt

and

keytool -import -alias intermed -keystore tomcat.keystore -trustcacerts -file gd_intermediate.crt

You may also need to import the root CA certificate into the keystore, but in general you shouldn’t have to
as most systems these days come with a pre-configured store of well known root CA certificates.

For reference on how to use the keytool and openssl commands, refer to their official documentation:

https://docs.oracle.com/javase/7/docs/technotes/tools/windows/keytool.html

https://www.openssl.org/
