BaSyx / Download / Java Setup / HTTPS Setup
How to get an SSL certificate
To Run Basyx in HTTPS mode, first we need an SSL Certificate to provide a secured connection. There are two ways to get an SSL Certificate.
- From a valid SSL certificate provider
- Generate a self-signed certificate for testing purpose
From a valid SSL certificate provider
SSL Certificate can be bought from several domain and security provider company (e.g. GoDaddy, Hostgator) and can be installed on the server. A documentation on how to get an SSL and install it can be found in below link-
Generate a self-signed certificate for testing purpose
There is already a default certificate provided with Basyx. This can be found at basyx\sdks\java\basys.sdk\tomcat.8080\resources folder under the name ssl.cert
A self-signed certificate can also be created for testing purpose to run a server in HTTPS mode. For this, we need to make sure that-
- JDK is installed in the system
- JAVA_HOME environment variable is added in the system pointing to the JDK. A guide on how to add JAVA_HOME can be found here- https://docs.oracle.com/cd/E19182-01/821-0917/inst_jdk_javahome_t/index.html
- JDK/bin folder must be added to the system path. A guide on how to add JDK/bin to path can be found here- https://docs.oracle.com/javase/7/docs/webnotes/install/windows/jdk-installation-windows.html
In java/jdk/bin there is an executable file keytool.exe which can be used to create a dummy certificate. If the JAVA_HOME variable is set and path/to/bin is added to system path, keytool can be accessed by CLI.
A step-by-step guide on how to create a certificate using java keystore can be found here- https://docs.oracle.com/cd/E19798-01/821-1841/gjrgy/
How to create a dummy SSL using keytool
- Run Command Prompt from desired location.
- Run the following command:
keytool -genkeypair -alias Mycert -keyalg RSA -keystore "C:/ SSL/Key/Mycert.cert"Here under -alias, Mycert can be renamed to any name. in -keyalg we can use any encryption algorithm. Here RSA is used. We may also provide the location where it will create the certificate. After that, it will ask for a keystore password.
- After giving a password, it will ask to retype the password again. If the passwords match, it will ask some basic questions which will be used to generate the key. Finally, it will ask if all the information is correct. Then it will generate the key file.
The key will be found at the given location.
Running Basyx in HTTPS
- basyx.vab.protocol.http.server.BasyxContext has a constructor
BaSyxContext(String reqContextPath, String reqDocBasePath, String hostn, int reqPort, boolean isSecuredCon, String keyPath, String keyPass)
We must create an instance of this class using the above constructor and provide-
isSecuredCon = true
keyPath = path to the key file
keyPass = password of the key file
- We can use the above instance of BasyxContext to create a basyx.vab.protocol.http.server.BaSyxHTTPServer. This will configure the embedded Tomcat server to run on HTTPS mode. Then BaSyxHTTPServer.Start() Will run the server in HTTPS.
The above steps will run the embedded tomcat server in HTTPS mode. If we want to deploy the application in an external tomcat server, we need to configure the server externally. A brief overview on how to do that can be found here- https://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html
Requesting in Secured Basyx REST API
If the Tomcat is running in HTTPS using a valid certificate, REST (GET/POST/PUT/DELETE) request will work just like before. basyx.vab.protocol.http.connector.HTTPConnector and basyx.vab.protocol.http.connector.HTTPConnectorProvider can be used to request a secured API as well.
However, if the server is running in HTTPS using a self-signed certificate, Java will not accept this certificate since this is not a valid one and can not be verified and validated. We must create a client which will not validate anything and accept every request. Please keep in mind that this must not be done outside of development since it completely jeopardizes security if used in production.
basyx.vab.protocol.https.HTTPSConnector can be used which internally uses basyx.vab.protocol.https.JerseyHttpsClientFactory to create a client which neglects all security checks and allow the request to pass with a non-valid SSL certificate.
An example on how to run the server in HTTPS and test connection, REST API can be found in basyx.testsuite.regression.vab.protocol.https.TestVABHTTPS