Replace java based self-signed certificate generation with OpenSSL

modules/ROOT/pages/addition/agent-installation/agent-self-signed-certificates.adoc

@@ -44,7 +44,7 @@ options (required options marked with *):
 
 If you are generating a certificate for an agent on `localhost`, `localhost` is the primary name set as Subject Name field on the certificate and is also used as the name of generated files. If `CONFIG_AGENT_NAME` is not specified, the Subject Name in agent client certificate along with the host information of agent will be used as the agent name.
 
-In order to generate a self-signed certificate for the above example, execute the following command;
+In order to generate a self-signed certificate for the above example, execute the following command:
 
 [source, terminal, role=noheader]
 ----
@@ -68,4 +68,4 @@ Following is a simplified command to generate a self-signed certificate tied to
 agent ssc -n nom-agent-1 -o ./certificates
 ----
 
-It generates a key pair and a self-signed certificate and creates `nom-agent-1.cert.pem` and `nom-agent-1.key.pem` files inside `./certificates` directory.
+It generates a key pair and a self-signed certificate and creates `nom-agent-1.cert.pem` and `nom-agent-1.key.pem` files inside `./certificates` directory.

modules/ROOT/pages/first-look/docker-first-look.adoc

@@ -9,7 +9,7 @@ Docker does not recommend using compose for production.
 The manual installation, configuring and running of agents on the Neo4j containers is lost if the container is stopped. 
 
 == Prerequisites
-* unix-based operating system
+* Unix-based operating system
 * Docker
 * Docker compose
 
@@ -23,21 +23,18 @@ You need to set up the following host names in your `/etc/hosts` or `C:/windows/
 
 ==  Create persistence DBMS and NOM server
 
-=== Create an empty directory for self-signed certificates
-
-Create a directory *`~/.nom/ssc`* on your local machine before running Docker compose.
-The compose file below specifies that:
-
-* This directory will be mounted into the docker container.
-* Self-signed certificates will be generated and saved to the mounted directory during the container start up.
-* The generated certificates are used by the NOM server
-
-These certificates are used by the server itself but are also required to configure the NOM agent. 
+=== Generate self-signed certificates
 
+. Create a directory *`~/.nom/ssc`* on your local machine before running Docker compose.
+The compose files below specify that this directory will be mounted into the docker container to make the generated certificates available to the NOM server and the agent.
++
 [NOTE]
 ====
 For *`sudo`* docker compose command, make sure the correct path to *`.nom/ssc`* is set in the bind section below.
 ====
+. Change to *`~/.nom/ssc`* and generate self-signed certificates as described *xref:installation/self-signed-certificate.adoc[here]*, using `server` as common name (CN) and DNS name, and `127.0.0.1` as IP address.
+This results in the creation of `server.cer` and `server.pfx`.
+. Use the password applied for the certificate store instead of `<SSC_PASSWORD>` in the next sections.
 
 === Copy docker compose file
 
@@ -46,8 +43,8 @@ Copy this to your local machine as `docker-compose.yaml`.
 
 Edit the yaml as follows:
 
-*  replace all three occurences of <PERSISTENCE_PASSWORD> with a secure password. 
-*  replace all three occurences of <SSC_PASSWORD> with a secure password.
+*  replace all three occurrences of <PERSISTENCE_PASSWORD> with a secure password.
+*  replace all three occurrences of <SSC_PASSWORD> with a secure password.
 
 .docker-compose.yaml
 [source, yaml]
@@ -103,7 +100,7 @@ services:
     entrypoint:
       - "sh"
       - "-c"
-      - "java -jar app.jar ssc -n server -o /certificates -p <SSC_PASSWORD> -d server -i 127.0.0.1 && java -jar app.jar"
+      - "java -jar app.jar"
 ----
 
 Documentation for NOM server docker image is *xref:installation/docker/container.adoc[here]*.
@@ -133,7 +130,7 @@ Full documentation on registering an agent is *xref:addition/index.adoc#register
 Copy compose file below into `docker-compose.instance.yaml` and edit as follows: 
 
 * Replace `<CONFIG_TOKEN_CLIENT_ID from register agent step>` and `<CONFIG_TOKEN_CLIENT_SECRET from register agent step>` with the values shown during the reigister agent step in the NOM UI. 
-* Replace all three occurences of <NEO4J_INSTANCE_PASSWORD> with a secure password. 
+* Replace all three occurrences of <NEO4J_INSTANCE_PASSWORD> with a secure password.
 
 .docker-compose.instance.yaml
 [source, yaml]
@@ -201,5 +198,5 @@ docker compose -f docker-compose.instance.yaml exec sh -c tar -xvf products/neo4
 == Explore NOM UI
 Go to NOM UI and wait for DBMS to appear - this may take a few minutes. 
 You should be able to see that the agent has connected in the agents listing. 
-Once the DBMS is shown in the home page, double click on the name (initially a generated string) to edit it. 
-Double click on the DBMS to see the metrics, status, security panel, logs and upgrade pages for the DBMS. 
+Once the DBMS is shown in the home page, double-click on the name (initially a generated string) to edit it.
+Double-click on the DBMS to see the metrics, status, security panel, logs and upgrade pages for the DBMS.

modules/ROOT/pages/first-look/linux-first-look.adoc

@@ -40,22 +40,8 @@ Extracted directory is now known as NOM_SERVER_HOME.
 
 === Generate self-signed certificates
 
-Navigate to NOM_SERVER_HOME and run:
-
-[source, terminal]
-----
-java -jar ./lib/server.jar ssc -n localhost \
-        -o ./certificates \
-        -p <PASSWORD> \
-        -d localhost
-----
-
-[IMPORTANT]
-====
-<PASSWORD> appears as a value in this step and twice in the following step; all of these values should be replaced with the same secure password. 
-====
-
-More information on Self Signed certificates *xref:installation/self-signed-certificate.adoc[here]*.
+Generate `server.cer` and `server.pfx` as described *xref:installation/self-signed-certificate.adoc[here]*.
+Use the password applied for the certificate store instead of `<PASSWORD>` in the next section.
 
 === Run NOM server as console application 
 
@@ -141,5 +127,5 @@ Full documentation on configuring an agent is *xref:addition/agent-installation/
 == Explore NOM UI
 Go to NOM UI and wait for DBMS to appear - this may take a few minutes. 
 You should be able to see that the agent has connected in the agents listing. 
-Once the DBMS is shown in the home page, double click on the name (initially a generated string) to edit it. 
-Double click on the DBMS to see the metrics, status, security panel, logs and upgrade pages for the DBMS. 
+Once the DBMS is shown in the home page, double-click on the name (initially a generated string) to edit it.
+Double-click on the DBMS to see the metrics, status, security panel, logs and upgrade pages for the DBMS.

modules/ROOT/pages/installation/self-signed-certificate.adoc

@@ -8,64 +8,54 @@ For production environments, it is advisable to use a trusted certificate issuer
 This section outlines a practical way to generate a self-signed certificate for test and demo purposes.
 ====
 
-The NOM Server contains a utility to generate a self-signed certificate suitable for your environment.
-
-To invoke the utility and get help on usage, navigate to the NOM Server folder and execute the following command:
-
+The following instructions show how a self-signed certificate suitable for a NOM environment can be generated using the OpenSSL library.
+Compatible self-signed certificates, generated using other libraries or online tools also work with NOM.
+
+. Ensure the OpenSSL library is installed.
++
+Commands used in these instructions were tested with OpenSSL 3.1.1.
+To check the version of OpenSSL, use the following command:
++
 [source, terminal, role=noheader]
 ----
-$> java -jar ./lib/server.jar ssc --help
-
-utility to generate self signed certificate for TEST purposes only
-
-sample usage:
-
-to generate a self signed certificate for 'localhost', which could either be
-accessed through DNS names of 'localhost.localdomain' or 'my.custom.domain', or
-with IP addresses of '127.0.0.1' or '192.168.100.5';
-
-$> java -jar ./lib/server.jar ssc -n localhost -o /tmp -p changeit \
-   -d localhost.localdomain,my.custom.domain \
-   -i 127.0.0.1,192.168.100.5
-
-it creates /tmp/localhost.cer and /tmp/localhost.pfx files upon completion.
-
-options (required options marked with *):
-  -d, --dns=<dns>[,<dns>...]
-                            list of dns names to use to access the
-                              server, eg. --dns=localhost.localdomain,test.
-                              local.domain
-  -i, --ip=<ip>[,<ip>...]   list of IP addresses to use to access the
-                              server, eg. --ip=127.0.0.1,192.168.100.55
-* -n, --name=<name>         common name to use in generated certificate,
-                              eg. --name=localhost
-* -o, --output=<output>     target directory, eg. --output=.
-* -p, --password=<password> password for generated PKCS12 file
-  -h, --help                help
+openssl version
 ----
-
-If you are generating a certificate for running the server on `localhost`, `localhost` is the primary name set as Subject Name field on the certificate and is also used as the name of generated files.
-For the certificate to be identified as valid, it also needs to include alternative names used to access the server.
-Assume there are also a number of virtual machines that access the server through IP addresses `192.168.10.1` and `172.16.10.1`.
-Furthermore, a local DNS alias `nom.example.com` is set up for `localhost`.
-
-In order to generate a self-signed certificate for the above example, execute the following command;
-
+. Create self-signed certificate
++
+Example: to generate a self-signed certificate for common name `localhost`, which could either be accessed through DNS names of 'localhost.localdomain' or 'my.custom.domain', or with IP addresses of '127.0.0.1' or '192.168.100.5':
++
 [source, terminal, role=noheader]
 ----
-java -jar ./lib/server.jar ssc -n localhost \
-	-o ./certificates \
-	-p changeit \
-	-d nom.example.com \
-	-i 192.168.10.1,172.16.10.1
+openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+  -subj "/CN=localhost" \
+  -addext "subjectAltName = DNS:localhost.localdomain, DNS:my.custom.domain, IP:127.0.0.1, IP:192.168.100.5" \
+  -addext "keyUsage = critical, digitalSignature, keyEncipherment" \
+  -addext "extendedKeyUsage = serverAuth" \
+  -addext "authorityKeyIdentifier = keyid:always,issuer:always" \
+  -keyout "server.key" \
+  -out "server.cer"
+----
++
+As a result, files `server.key` and `server.cer` are created in the current directory.
++
+Important parameters:
+
+* `-subj "..."`: use to specify the common name
+* `-addext "subjectAltName = ..."`: use to specify alternative DNS name(s) and/or IP address(es)
+. Convert the generated certificate to the PFX format, specifying a password for the certificate store generated in `server.pfx`:
++
+[source, terminal, role=noheader]
+----
+openssl pkcs12 -export \
+  -inkey "server.key" \
+  -in "server.cer" \
+  -out "server.pfx" \
+  -password "pass:changeit"
 ----
-
-It generates a key pair and a self-signed certificate and creates `localhost.cer` and `localhost.pfx` files inside `./certificates` directory.
-`localhost.pfx` is assigned the password `changeit` which is provided to the command as an argument.
-
-You can then use these two files to configure the server and agents for TLS encrypted communication.
 
 [IMPORTANT]
 ====
-Please note that in the rest of documentation, certificate files are referred to as `server.cer` and `server.pfx`.
+To avoid specifying the store password on the command line, omit the `-password` option in the previous command to have OpenSSL ask for the password interactively.
 ====
+
+You can then use the files `server.cer` and `server.pfx` to configure the server and agents for TLS encrypted communication.