The communication between Dispatcher Paragon Management Service and Dispatcher Paragon Spooler Controller is not secured by default. In order to start encrypted and authenticated communication, both sides need to be properly configured to use the same security settings. If one of the sides is set secure and the other one is not, the communication does not work.

This guide will help you with the configuration of the secured connection between Dispatcher Paragon Management Service and Dispatcher Paragon Spooler Controller, using CA-signed certificates.

CA-signed certificate requirements

The certificate must be signed by a certification authority trusted in your environment.
Certificate (fields Common Name and Subject Alternative Name) must contain all network names (i.e. all hostnames, fully qualified domain names and IP addresses) used for connection to the respective server.
- For multi-tenant deployment it's recommended to enable which is described in section Hardening multi tenant deployment with Spooler Controller tenant identity validation.
For importing the certificate you need an appropriate format - Java Keystore (.jks file) containing the private key and whole certificate chain.
Both the keystore and key itself need to be protected by a password
You will also need a truststore, file containing certificate of the root certification authority, again in the Java Keystore (.jks) format.

In case your key/certificate is in a different format than Java Keystore, convert it following the guide in Conversions between different keystores and certificate types.

In case you do not have key/certificate at all, follow the guide in the Generating key/certificate in Java Keystore format chapter in System communication hardening .

Dispatcher Paragon Management Service settings

Stop Dispatcher Paragon Management Service service in Dispatcher Paragon server.
Copy your key/certificate and certificate of the root certification authority, both in the Java Keystore format, to the <install_dir>\Management\conf\ directory on the server with Dispatcher Paragon Management Service.
Go to <install_dir>\Management\conf\ and create there a new file, communicator.conf.
When this file is present in the specified directory, correctly configured and accessible for read, then the settings specified are applied and communication between Dispatcher Paragon Spooler Controller and Dispatcher Paragon Management Service will start in secure mode.
Set following properties in the communicator.conf file:
# this property sets security in Communicator on/off if set to false then resp of properties are ignored (MANDATORY)
secureCommunicationEnabled=true
# name of Java truststore file in current directory or absolute path to file (use double backslash \\ in path) (MANDATORY)
truststoreFile=truststore.jks
# password to java truststore if not set default value 'changeit' is used (OPTIONAL)
truststorePassword=changeit
# name of Java keystore file in current directory or absolute path to file (use double backslash \\ in path) (MANDATORY)
keyStoreFile=keystore.jks
# password to java keystore if not set default value 'changeit' is used (OPTIONAL)
keystorePassword=changeit
# protocol type as defined by Java SSL specification (MANDATORY)
sslProtocol=TLS
# this option forces CML to require SPOC authentication (MANDATORY)
clientAuthenticationRequired=true
# available protocols as defined by Java SSL specification (OPTIONAL)
#allowedProtocols =
# available cipher sutes as defined by Java SSL specification (OPTIONAL)
#allowedCiphersuites =
# this property sets the certificate revocation validation method and can contain values 'NONE', 'CRL', 'OCSP' or their combination separated by comma (',') in order of their fallback priority (left to right). The default is 'NONE' (OPTIONAL)
#certificateRevocationMethod=NONE
# this property sets whether to validate full certificate chain (true) or just end-entity certificate (false). The default is true (OPTIONAL)
#revocationFullChainChecking=true
The communicator.conf file has to refer to correct Java keystore and truststore files either by relative path to file in the same conf\ directory as this configuration file, or by an absolute path to file.
Start the Dispatcher Paragon Management Service service.

Dispatcher Paragon Spooler Controller settings

Stop Dispatcher Paragon Spooler Controller service.
Copy your key/certificate and certificate of the root certification authority, both in the Java Keystore format, to the <install_dir>\SPOC\conf\ directory on the server with Dispatcher Paragon Spooler Controller.
Go to <install_dir>\SPOC\conf\ and create there a new file, communicator.conf.
When this file is present in the specified directory, correctly configured and accessible for read, then the settings specified are applied and communication between Dispatcher Paragon Spooler Controller and Dispatcher Paragon Management Service will start in secure mode.
Set following properties in the communicator.conf file:
# this property sets security in Communicator on/off if set to false then resp of properties are ignored (MANDATORY)
secureCommunicationEnabled=true
# name of Java truststore file in current directory or absolute path to file (use double backslash \\ in path) (MANDATORY)
truststoreFile=truststore.jks
# password to java truststore if not set default value 'changeit' is used (OPTIONAL)
truststorePassword=changeit
# name of Java keystore file in current directory or absolute path to file (use double backslash \\ in path) (MANDATORY)
keyStoreFile=keystore.jks
# password to java keystore if not set default value 'changeit' is used (OPTIONAL)
keystorePassword=changeit
# protocol type as defined by Java SSL specification (MANDATORY)
sslProtocol=TLS
# this option forces CML to require SPOC authentication (MANDATORY)
clientAuthenticationRequired=true
# available protocols as defined by Java SSL specification (OPTIONAL)
#allowedProtocols =
# available cipher sutes as defined by Java SSL specification (OPTIONAL)
#allowedCiphersuites =
# this property sets the certificate revocation validation method and can contain values 'NONE', 'CRL', 'OCSP' or their combination separated by comma (',') in order of their fallback priority (left to right). The default is 'NONE' (OPTIONAL)
#certificateRevocationMethod=NONE
# this property sets whether to validate full certificate chain (true) or just end-entity certificate (false). The default is true (OPTIONAL)
#revocationFullChainChecking=true
The communicator.conf file has to refer to correct Java keystore and truststore files either by relative path to file in the same conf\ directory as this configuration file, or by an absolute path to file.
Start the Dispatcher Paragon Spooler Controller service.

Example of communicator.conf file configuration

secureCommunicationEnabled=true
truststoreFile=truststore.jks
truststorePassword=password
keyStoreFile=dispatcherparagonkeystore.jks
keystorePassword=keystoreprotectingpassword
sslProtocol=TLS
clientAuthenticationRequired=true
certificateRevocationMethod=OCSP,CRL,NONE
revocationFullChainChecking=true

Certificate revocation validation

It is possible to enhance the security of communication between Dispatcher Paragon Spooler Controller and Dispatcher Paragon Management Service by checking the certificate revocation. The revocation validation method can be configured by options certificateRevocationMethod and revocationFullChainChecking in communicator.conf. If the revocation check fails, the connection is refused.

Revocation validation method

Supported validation methods: Online Certificate Status Protocol (OCSP ) and Certificate Revocation List (CRL).

The possible values of certificateRevocationMethod :

NONE (default value, certificate revocation is not checked)
OCSP (OCSP validation method is used
CRL (CRL validation method is used)

These values can be ordered (separated by comma) to define fallback validation methods (priority - left to right). That means if the first method is not available (e.g. OCSP service is down) then second method, if specified, is used to check the revocation. It does not mean the revoked certificate that failed to validate by the first method is then checked by the second method. Also, by using NONE as fallback to a validation method that is not available it causes the revocation check to pass (even if the certificate is revoked).

Examples:

certificateRevocationMethod option and its value	Explanation
certificateRevocationMethod=	default method is NONE, therefore certificate revocation is not checked (the same if the property is completely omitted from the communicator.conf file)
certificateRevocationMethod=NONE	the same effect as above, i.e. certificate revocation is not checked
certificateRevocationMethod=OCSP	OCSP method is used for revocation check (if certificate is revoked or if OCSP check cannot be performed, revocation validation fails, otherwise it succeeds)
certificateRevocationMethod=CRL	CRL method is used for revocation check (if certificate is revoked or if CRL check cannot be performed, revocation validation fails, otherwise it succeeds)
certificateRevocationMethod=CRL,NONE	CRL method is used for revocation check, and fallbacks to NONE (if certificate is not revoked or CRL check cannot be performed, revocation validation succeeds - even if the certificate is revoked - otherwise it fails)
certificateRevocationMethod=OCSP,CRL	OCSP method is used for revocation check and fallbacks to CRL (e.g. if both OCSP and CRL checks cannot be performed, revocation validation fails)
certificateRevocationMethod=OCSP,CRL,NONE	OCSP method is used for revocation check and fallbacks to CRL, which fallbacks to NONE (e.g. if both OCSP and CRL checks cannot be performed, revocation validation succeeds - even if the certificate is revoked)

Note that the OCSP and CRL protocol needs to be supported by the Private Key Infrastructure (PKI) in order for it to be used.

Usually the client finds the OCSP responder's URL and CRL distribution points by looking in the Authority Information Access (AIA) extension of the certificate.

Full chain checking

It is possible to specify whether full certificate chain should be checked for revocation, or just the End-Entity (EE) certificate. To check only EE certificate could be beneficial if the authorities in the chain does not support a validation method (e.g. OCSP) we want to use and the EE certificate does.

The possible values of revocationFullChainChecking :

true (default value, full certificate chain is checked)
false (only EE certificate is checked)

The revocationFullChainChecking has effect only if certificateRevocationMethod specifies at least one method that is not NONE (i.e. OCSP or CRL).

Hardening multi tenant deployment with Spooler Controller tenant identity validation

Configuration described above is sufficient for single tenant deployments.
In case of multi tenant deployment it might be useful to enable also Validate Spooler Controller tenant identity (option tenantValidationEnabled).
With this option enabled, Management Service ensures that communication with any Dispatcher Paragon Spooler Controller is authentic and prevents any attempt to impersonate other tenants in case of compromised Dispatcher Paragon Site Server.

For this validation to work, it is necessary to include additional metadata in SSL certificate of each Dispatcher Paragon Spooler Controller within the Dispatcher Paragon deployment.
When Spooler Controller tenant identity validation is enabled, Dispatcher Paragon Management Service accepts only communication from Dispatcher Paragon Spooler Controller, which have trusted SSL certificate with required metadata.
If Dispatcher Paragon Spooler Controller lacks required metadata in certificate or if the metadata are incorrect, then all communication from this Dispatcher Paragon Spooler Controller is rejected.

Spooler controller validation requires secured communication between Dispatcher Paragon Management Service and Spooler Controller. Plain communication would be rejected during validation.

For this feature, SSL certificate of Dispatcher Paragon Spooler Controller must contain:

Subject Alternative Name extension
- this extension must contain entry of type Directory Name where field Organization Name is set to your tenant domain
- for example: if there is tenant with domain samplecompany, then SSL certificate must contain O=samplecompany

Tenant domain can be configured only during tenant creation.

images/download/attachments/284931553/create_tenant-version-1-modificationdate-1606484081033-api-v2.png

Tenant domain must be set in client certificate of each Dispatcher Paragon Spooler Controller in extension Subject Alternative Name in Directory Name entry and it's organization name field.

images/download/attachments/284931553/image2020-2-4_12-14-27-version-1-modificationdate-1606484081070-api-v2.png

Once each Dispatcher Paragon Spooler Controller of each tenant withing Dispatcher Paragon deployment contains certificate with matching tenant domain entry, then the validation can be enabled.

Enable Validate Spooler Controller tenant identity. In the Management web interface go to the System Configuration and under Expert options find the following parameter
tenantValidationEnabled
and set it to Enabled. This option is visible only in cloud administration if multi-tenant license is enabled or together with other settings without multi-tenant license.
Restart Dispatcher Paragon Management Services. This step forces all Dispatcher Paragon Spooler Controllers to reconnect and properly validate the communication.