Certificate installation
The trusted connection between node servers and Sage X3 servers is based on signed certificates. This document explains how the certificates must be set up and installed, and includes the following sections:
In normal cryptography, anyone who encrypts something can also decrypt it because the same key is used for both encryption and decryption.
In public key cryptography there is:
A similar mechanism is used for digital signatures in order to secure some data. For this purpose, you can compute the digital signature (some kind of encrypted summary) of the data using the private key. Anyone who has the public key can verify the digital signature of the data and thus make sure that the data has not been changed. It is almost impossible to change the data without changing the signature, and to compute a valid signature of some data without the private key.
The private key is very sensitive and usually encrypted using a so-called passphrase (something like a password, but more complicated). You can use the private key only if you know the passphrase.
A certificate is like a bundle of a public key with some additional data and a digital signature. There are always two parties involved: a subject and an issuer.
A certificate is a file that contains information about the issuer and the subject of the certificate, an expiration date, the subject's public key, and the issuer's digital signature to verify that the certificate is not fake (you need the issuer's certificate or public key to verify it). When you use a certificate, you are supposed to trust the issuer of the certificate.
When you have the certificate, you can verify that the subject of the certificate has the corresponding private key.
This schema summarizes the components that are set up for a certificate management:
Certificates are managed as follows:
In the first step, a master certificate or "CA certificate" is created. This master certificate is used as a "certification authority" (the issuer and subject are the same). It identifies a domain of trust for your company or organization.
For a strong security, this certificate should be generated on a secured server, and the private key MUST NOT BE TRANSFERRED anywhere. However, the master certificate will be transferred on different node.js servers as illustrated on the following schema:
In this schema, the number (1) means that only one master certificate exists, and the corresponding private key is kept safe on a master secured server, while the certificate is distributed on every node.js server.
The second step is to create a private and public keys, and a certificate for every node.js server. They are generated using the master certificate and master private key, thus the issuer is the above "certification authority" and the subject is the node.js server. This will secure the connections to Sage X3 and may also secure connections between node.js servers. Every time a connection request is sent from a node.js server to a Sage X3 server, encrypted data is sent. The Sage X3 server is able, by using the public key, to identify the server that connects on it, will ensure the authentication. This is why we will have as many certificates as node.js servers. This corresponds to the following schema:
In this schema, the letter (N) means that there are as many certificates and private keys as node.js servers. The private key and certificate will remain on the node.js server, while the public key will be distributed to the Sage X3 servers that will receive a connection from the corresponding node.js server. Note that the Sage X3 servers will only get the public key, without the certificate itself (which also contains the same public key and some other information), or the private key.
For security reasons, it is impossible to completely automate the generation and distribution of certificates and keys because each server needs some trusted piece of information to check and trust another server. However, there is a simplified method where the installation can be automated. If a unique node.js server is present on the network, the generation of the CA certificate and the the unique node.js certificate can be done in a completely automated method by the installation procedure. In addition, if the Sage X3 server is located on the same physical server, you can directly copy the key in Sage X3.
The simplified procedure has been created to handle all the cases where a unique node.js server is installed on the network.
If you want to have a separate server that creates the certificates in a very secured environment, you will need to run the complete generation procedure anyway.
The key generation procedure is included within the software installation procedure. This section describes the installation steps involved with the key generation. The following screens have been shrunk to display only the useful information.
The first step regarding the key generation is step 9 of 18. The following screen appears:
The following information is provided:
If the use of an existing certificate is selected, the procedure is described here.
If the Simplified procedure is selected, the following screen appears:
This screen requires you to enter a passphrase used for the private key of the certification authority and another passphrase used for the server certificate. A passphrase is the equivalent of a password that must be long and where digits and upper case, lower case and special characters should be mixed as indicated to ensure maximum security. You should memorize these passphrases because it will be impossible to recover them.
Both passphrases must be entered twice.
The next screen requires information about the issuer of certificates.
The screens are similar to the following screen:
The data required for a certificate are the country and state (if necessary), city, organization, service, name, and validity duration in days. Note that when the duration expires, you will have to recreate the different certificates and distribute them. For this reason, you have to choose the best compromise between security (everlasting certificate is not very secured) and convenience (recreating and deploying certificates will be done with the manual procedure).
The details for the certificate should identify the global organization that you have to trust when you create new certificates. For example, it can be your company or the group it belongs to if the certificate delivery is done for several node.js instances.
The next screen associated with the certificate generation is the following:
In this screen, you define the server (it must include the full qualified domain name) and the folder where the certificate generation tool is installed. You can change the default path. This path will be used if you want to manually generate other certificates in a later step.
This screen also includes two check boxes:
* a check box to specify a local Sage X3 runtime if there is one. This happens if a unique physical server hosts the node.js server and the Sage X3 runtime.
* a check box to specify a local Sage X3 webservice ADC server if there is one.
If any one of these check boxes is selected, the following screen appears with an additional field where the corresponding path is to be entered:
If the runtime check box is selected, the path must be provided so that the public key will be automatically copied into the correct folder. Similarly, the same rule applies for the webservice ADC server check box and path.
The next installation procedure screens are not related to the key generation.
When these steps have been fulfilled, the system is ready to be used.
When this choice is done, you have to enter the certificate used, and if necessary the X3 runtime and web service paths to copy the certificates, with the following screen:
The procedure goes then to the final step as previously.
If the simplified generation procedure has not been selected, you will have to manually create and install the certificates and public and private keys to ensure a secured connection between the different servers. This chapter describes the procedure.
You need a computer to generate certificates which are used for secured communication and authentication of the servers. These certificates and private keys contain sensitive data; therefore, this computer should be secured without Internet access, if possible. It is not necessary that this physical computer belong to the node.js cluster.
To do this, copy the contents of the folder bin/cert_gen (at least the following files: bcpkix-jdk15on-150.jar, bcprov-jdk15on-150.jar, certgen.jar, certgen.bat) of an arbitrary node.js installation into one folder of the file system for this computer.
Java 7 must be installed on that computer, and Java must be in the search path for executables.
To generate the certificates, invoke on the command line (within that folder)java -jar certgen.jar. Under Microsoft Windows, click certgen.bat, which will invoke this command line. The user who executes the program must have write access to the folder and subfolders. The program will create subfolders private (for the private key of the generated certificate authority) and output (for all other certificates, server private keys, and public keys).
When you run the program for the first time, it will create these subfolders and ask for data of the generated certificate authority which will be used to sign all server certificates. After that, you can create an arbitrary number of certificates.
There must be a certificate for each server in which node.js runs. The name must be the hostname of the node.js server. It must be the same as the output of the hostname command on that server, and it will be automatically converted to lowercase. The program will ask you for the server name of the TCP connections. This must be the server name or IP address in which this server can be reached by TCP from all other node.js servers (for example, hostname with domain).
If you generate the certificates on a computer which has network connection to the node.js servers, you may also automatically transfer the certificates if you have already copied the CA certificate to each server.
For a complete list of program options, see the appendix
section.
At the end, the output subfolder will contain the following files:
- ca.cacrt, the certificate of the generated certification authority.
- The following three files for each server. The name is always the hostname of the server (in lowercase):
* The file with extension .crt contains the certificate of that server.
* The file with extension .key contains the private key for this server.
* The file with extension .pem contains the corresponding public key which is used by Sage X3 servers for communication with this server. Note that in the name of the .pem file, the characters $, ., @ have been replaced with _.
The setup has created a folder for certificates on each server. Within this folder, there is a subfolder whose name is the server name. Under Unix, this subfolder is only accessible by the user in which the node.js process runs. Copy the files ca.cacrt into this subfolder.
If you do not want to transfer the certificate, private key, and passphrase using the certificate generation tool, you must also manually copy the files with extensions .key and .crt, whose name is the server name, into this subfolder. Moreover, the passphrase must be set. In the node.js installation folder, you can find the batch file passphrase.cmd or the shell script passphrase.sh which can set the passphrase. You have to invoke this file with one parameter (the passphrase of the private key) on the command line. This will set and encrypt the passphrase, and check the certificate and private key. The encryption of the passphrase depends on the computer and the operating system user. Therefore, the command will write the passphrase for the user in which the node.js process runs.
You can check your settings by invoking the passphrase file with the special parameter -check. This will not set a passphrase, but will only report the integrity of the certificate and private key.
Remark: It is not possible to set the value -check as a passphrase for a server key. A passphrase must include at least four characters.
The passphrase command will automatically contact the node.js server to update its configuration so that you do not have to restart the node.js server.
When everything is OK, you can start the administration application. In the Hosts entity, make sure that all hosts have the status OK and the security check box is selected.
Each node.js server has to authenticate against each Sage X3 server it invokes. You have two options:
For the x3server entity with some certificates declared. This must be a certificate with a private key and must not be any of the previously manually installed internal certificates for node.js servers. You can also generate this new certificate by using the certificate generation tool and can install it on all node.js servers by adding a new instance of the certificate entity. You have to copy the public key file (with extension .pem) for this certificate into the keys subfolder of the Sage X3 runtime (and into \data\KEYSTORE\WEBSERVER\ subfolder if webservice ADC server is installed). Note that the characters $, ., @ in the certificate name will be replaced with _.
For example: When the name of the instance of the certificate entity is test.test, there must be a file test_test.pem in the keys directory.
For the x3server entity with no certificates declared. The manually installed server certificate of this node.js server will be used. This means that you have to copy all public keys of the node.js servers (all .pem files of the output folder of the certificate generation tool) into the keys subfolder of the Sage X3 runtime (and into \data\KEYSTORE\WEBSERVER\ subfolder if webservice ADC server is installed). When you add a node.js server later on, you will also have to copy its public key (the .pem file) into the keys subfolder of all Sage X3 runtimes (and into \data\KEYSTORE\WEBSERVER\ subfolder if webservice ADC server is installed). Note that in the .pem file, the characters $, ., @ of the hostname have been replaced with _ to build the name of the .pem file. For example: For the server ABC.DEF.GHI, the file will be abc_def_ghi.pem.
Let's just illustrate this last option by using an example where you have two node servers (A and B), and two Sage X3 servers (1 and 2). If you want the Sage X3 server 1 to accept connections from both node.js servers (A and B), and Sage X3 server 2 to accept connections only from node.js server A, the deployment policy is summarized in the following table, where:
| Type of file | Installed on | ||||
|---|---|---|---|---|---|
| Secured CA server | node.js server A | node server B | Sage X3 server 1 | Sage X3 server 2 | |
| CA certificate | available | yes | yes | no | no |
| CA private key | available | never | never | never | never |
| Certificate for server A | generated | yes/transfer | no | no | no |
| Server A private key | generated | yes/transfer | never | never | never |
| Server A public key | generated | no | no | yes | yes |
| Certificate for server B | generated | no | yes/transfer | no | no |
| Server B private key | generated | never | yes/transfer | never | never |
| Server B public key | generated | no | no | yes | no |
Certificates, private keys, and their passphrases are very sensitive data which are important for securing connections and for signing documents. Therefore, they will not be stored in the database but placed as files in the local file system in a folder with limited access rights. The encrypted passphrases will be added to another file in the same folder.
There will be a system of customer generated certificates and private keys which will ensure that the servers are able to trust each other (and be trustworthy to the Sage X3 runtime). These certificates will be signed using a customer generated certification authority. The node.js servers will have the certificate and the private key, while the Sage X3 runtime will have only the certificates of the servers calling the Sage X3 runtime. In the future, only the certificate of the customer generated certification authority may be added to the Sage X3 runtime so that it has to verify the certificates of the node.js servers.
At customer site, the administrator generates a private key and a self-signed certificate which will act as a certification authority. For each server in the cluster, a certificate and a private key will be generated in such a way that the certificate can act as a server certificate for HTTPS. The certificates will be signed using the previously generated self-signed certificate.
For this purpose, the administrator uses a command line tool. The tool is totally independent from the node.js installation folders, and should run on a totally different computer. You should copy all contents of the cert_gen subfolder of the customer image into an empty folder.
A Java runtime (Java version 7 and above) must be available on the computer and in the search path for binaries.
On a Microsoft Windows operating system, you can invoke certgen.bat without opening a command line to start the tool without command line parameters. You can also add command line parameters to certgen.bat.
Otherwise, you invoke java -jar certgen.jar and may add command line parameters.
The application will create two subfolders private and output (see "First Invocation" below). After generation, the CA certificate, the server certificate, and the corresponding private key must be manually copied to each server which runs the 'node.js' processes. The server certificates must be copied to servers having the Sage X3 runtime with the help of the administration GUI. It can be used for several actions within one interactive session (where the passphrase of the CA private key is re-used).
The following is a list of possible use cases for the tool:
-batch switch has been set. -batch switch is set, there will be no input from the console and an error will appear when data is missing. This switch is recommended when you use the tool within batch files.-notransfer switch to the invocation of the tool to switch off all transfer options. When node.js cannot be reached, the tool stops with an error message. When the -wait option is set together with a positive number (for example, -wait 20), the tool will try numerous times to connect to this port for this number of seconds. When you specify the -port switch together with a positive number (for example, -port 8124), the tool will transfer the data to the node.js server even in batch mode.When the tool is started for the first time, it will create two folders:
output folder for the generated server certificates, their private keys, and the CA certificate. private folder for the CA private key.This separation reduces the risk of copying the CA private key unintentionally. The tool will not store passphrases anywhere.
The tool will also generate the certificate and private key of the certification authority; all other actions will be rejected. For this, it needs:
* The distinguished name of the subject of the CA certificate either interactively or behind the command line parameter -dn. The distinguished name must obey the AVA format for distinguished names according to http://www.ietf.org/rfc/rfc4514.txt.
* The passphrase of the CA private key either interactively or behind the command line parameter -capass.
* The number of days which the certificate should be valid, starting from the current time; either interactively or behind the command line parameter -days.
* Optional: the port of the node.js server to which the server certificate should be transferred via encrypted HTTP requests (either interactively by entering a positive port number) or behind the command line parameter -port. This only works when the server has already the CA certificate.
When the CA certificate is available, the user can perform the following actions. When the corresponding command line parameter is not given, the action will be asked interactively. Note that the CA passphrase will only be prompted once when you do several actions within one session of the program.
-create)This action requires the following:
* The computer name of the server interactively or as a last command line parameter.
* The passphrase of the private key for the server certificate interactively or behind a -pass parameter.
* The passphrase of the private key for the CA certificate interactively or behind a -capass parameter.
* The server name as it should be used from other servers in TCP connections either interactively or as a common name of a distinguished name behind the -dn parameter, or as a value behind the -cn parameter. The default value is the computer name. The other parts of the distinguished name will be used from the CA certificate unless the -dn parameter is given.
* The number of days which the certificate should be valid, starting from the current time; either interactively or behind the command line parameter -days, default being the validity of the CA certificate.
Remark: Unless the -notransfer switch is set, you will be prompted for the port of a node.js server. Only if you enter a valid positive port number, the data will be transferred to that server using encrypted HTTP requests.
-renew-cert)This action will generate a new certificate with the same subject, but different validity.
This requires the following:
* The computer name of the server interactively or as a last command line parameter.
* The passphrase of the private key for the CA certificate interactively or behind a -capass parameter.
* The number of days which the certificate should be valid, starting from the current time; either interactively or behind the command line parameter -days, default being the current validity of the certificate.
Remark: Unless the -notransfer switch is set, you will be prompted for the port of a node.js server. Only if you enter a valid positive port number, the data will be transferred to that server using encrypted HTTP requests.
-renew-all-certs)This action will change, in a single action, the validity of the CA certificate and all server certificates to the given date. This requires the following:
* The passphrase of the private key for the CA certificate interactively or behind a -capass parameter.
* The number of days which the certificate should be valid, starting from the current time; either interactively or behind the command line parameter -days, default being the current validity of the certificate.
Remark: Unless the -notransfer switch is set, you will be prompted for all ports of node.js servers one after each other. Only if you enter a valid positive port number, the data will be transferred to that server including the new CA certificate. This does not work in batch mode.
-renew-key)This action will generate a new pair of public and private keys and generate a new certificate with the same subject and validity, but containing the new public key. When this is applied to the CA certificate, it will automatically sign all server certificates with the new key. This requires the following:
* The computer name of the server or an empty name for the CA certificate interactively or as a last command line parameter.
* The passphrase of the new private key interactively or behind a -pass parameter; when the CA certificate key is changed, the -capass parameter should be used instead.
* For server certificates only, the passphrase of the existing private key for the CA certificate interactively or behind a -capass parameter.
Remark: Unless the -notransfer switch is set, you will be prompted for the port of a node.js server. Only if you enter a valid positive port number, the data will be transferred to that server using encrypted HTTP requests. When you change the key of the CA certificate, you will be prompted for all ports of node.js servers one after each other. Only if you enter a valid positive port number, the data will be transferred to that server including the new CA certificate. This does not work in batch mode.
-change-name)This action will change the subject of the certificate without changing the validity. If applied to the CA certificate, it will change the issuer of all CA certificates and sign them again. When the subject of the certificate is identical to the issuer (except for the common name), the subject (except for the common name) will also be changed.
Example: The CA certificate has a distinguished name C=de,ST=bw,L=vs,O=xx,OU=mm,CN=ca which will be changed to C=uu,ST=vv,L=ww,O=xx,OU=yy,CN=zz. Then the subject C=de,ST=bw,L=vs,O=xx,OU=mm,CN=server1 will be changed to C=uu,ST=vv,L=ww,O=xx,OU=yy,CN=server1. However, the subject C=ab,ST=cd,L=ef,O=gh,OU=ij,CN=kl will remain unchanged.
This requires the following:
* The computer name of the server or an empty name for the CA certificate interactively or as a last command line parameter.
* The passphrase of the private key for the CA certificate interactively or behind a -capass parameter.
* The number of days the certificate should be valid, starting from the current time; either interactively or behind the command line parameter -days, default being the current validity of the certificate.
* The new distinguished name of the subject. You can enter this interactively (with the old name being the default) or use the parameter -cn to set a new common name, or -dn to set a new distinguished name (the distinguished name must obey the AVA format for distinguished names according to http://www.ietf.org/rfc/rfc4514.txt). For server certificates, you will only be prompted for the new common name (name of the server as used in TCP connections), and for the CA certificate you will be prompted for all parts of the common name.
Remark: Unless the -notransfer switch is set, you will be prompted for the port of a node.js server. Only if you enter a valid positive port number, the data will be transferred to that server. When you change the key of the CA certificate, you will be prompted for all ports of node.js servers one after each other. Only if you enter a valid positive port number, the data will be transferred to that server including the new CA certificate. This does not work in batch mode.
-show)This action will show the subject and issuer distinguished names and the start and end date of the validity for the certificate. This requires the following:
* The computer name of the server or an empty name for the CA certificate interactively or as a last command line parameter.
-show-all)This action will show the subject and issuer distinguished names and the start and end date of the validity for all certificates. This does not require any further data.
-delete)This action will delete the certificate, public key file (for the X3 server) and the private key file from the output directory. The CA certificate cannot be deleted in this manner. This requires the following:
* The computer name of the server interactively or as a last command line parameter.
-transfer)This action will only be shown when the -notransfer switch is not set. This will just transfer the certificate, private key, and passphrase for that server to that server (provided these files are in the output folder). This requires the following:
* The computer name of the server or an empty name for the CA certificate interactively or as a last command line parameter.
* The passphrase of the private key for the server certificate interactively or behind a -pass parameter.
* The passphrase of the private key for the CA certificate interactively or behind a -capass parameter.
* The port of the node.js server interactively or behind a -port parameter.
This is only necessary when you do not use the certificate generation tool to transfer the passphrase. This is done using the passphrase.cmd batch file or passphrase.sh shell script (as described above in "Distribution of certificates to node.js servers"). This will encrypt the password of the generated private key on the server and dependent on the user (for example, on MS Windows using CryptProtectData). When it is invoked without further parameters, it will check the validity of the certificates. Otherwise, it will set and encrypt the passphrase.
The certificate generation tool will make two requests to the node.js server. The first is for a Diffie-Hellman key exchange, the second will transfer the data, encrypted with the common secret Diffie-Hellman key and signed with the private CA key. The tool will authenticate using the private CA key and the node.js server will authenticate using the public CA key and its reachability by the server name given as subject's common name in the server certificate.
The setup generates a special folder for certificates and keys, and writes its path to the 'nodelocal.js' file.
In the certificate folder, there is a subfolder with the computer name in lower case (both folders are generated by the setup if they do not already exist); containing the following files (assuming the server name is foo in lower case):
- ca.cacrt: Certificate of the generated certification authority (maybe other certificates of certification authorities with extension .cacrt).
- foo.crt: Certificate of the server (maybe other certificates with extension .crt).
- foo.key: Private key file of the server (maybe other private key files with extension .key).
- foo.pwd: File with encrypted pass phrases for all private keys of that server.
Remark: The purpose for the subfolder within the certificate directory is that this avoids problems when the administrator chooses to install everything on a network drive, and therefore certificates of different servers will have to be stored within the same folder. Furthermore, it does not do any harm. The subfolder and its files should have access rights limited to the operating system user under which the node.js processes will run.
There is an entity for certificates and an entity for CA certificates which contain the metadata for the certificates and private keys:
- A logical name consisting of lower case letters, underscore, and dot. Acting as a key value which will be the computer name for the administrator generated server certificates, and private keys and ca for the administrator generated certification authority.
- A marker if the certificate is administrator generated, has been manually installed at setup time, and therefore cannot be changed using the GUI.
- A checksum of the certificate which is not for the administrator generated certificates to ensure integrity (hidden field).
- Validity of the certificates.
- Distinguished names of issuer and subject.
Both entities also contain an upload field for the certificate, yet only the checksum of the certificate will be stored in the database.
The certificate entity also contains:
* A flag if a private key has been uploaded for that certificate.
* An upload field for the private key.
* An input field for the pass phrase that will not be stored in the database.
Some certificates are only useful for one server (for example, SSL server certificate). The corresponding instance of the host entity is placed as a related instance to the certificate instance. When there is no instance, the certificate will be stored on all hosts and will be transferred at startup to servers where the certificate is missing (for example, servers added to the cluster).
The fields for the certificate, the private key, and the passphrase are input fields only. However, you can update just the certificate and leave the private key unchanged. The following consistency checks will be done:
The instances of the certificate entity and the CA certificate entity, which correspond to the administrator generated certificates, will be marked as read-only.