Setting secured communication with Spooler Controller

Communication with Spooler Controller is not secured by default. In order to start encrypted and authenticated communication, security needs to be enabled and certificates properly set on all the following components (if used). All sides need to be configured to use the same security settings. If one of the sides is set to secure and the others are not, the communication does not work.

This guide covers security settings for all the following components:

  • Spooler Controller

  • End User Interface

  • FlexiSpooler

  • Mobile Print Server

  • Workflow Processing System

  • Mobile Integration Gateway

In order to improve performance, the key agreement is not performed for each message, but once a specific time instead. This period can be configured in the sessionLifeTimeMinutes system property in the YSoft SafeQ management interface (Advanced option).

CA-signed certificate requirements for Spooler Controller and End User Interface

  • 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 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 a 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.

CA-signed certificate requirements for YSoft SafeQ Client, FlexiSpooler, Mobile Print Server, Workflow Processing System, and Mobile Integration Gateway

  • 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 importing the certificate you need it in an appropriate format - Personal Information Exchange (.pfx file) containing the private key and whole certificate chain.

  • Must be created using the Microsoft Enhanced RSA and AES Cryptographic Provider.

In case your key/certificate is in a different format than Personal Information Exchange, you can 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 Personal Information Exchange format chapter in System communication hardening.

A separate certificate must be created for each YSoft SafeQ Client and each YSoft SafeQ Client must be configured to use its own certificate. Because this requires a significant administrator effort, the YSoft SafeQ Client v3 should be used instead.

Spooler Controller settings

Following settings apply for both cases, when Spooler Controller acts as a server and as a client. In order to enable security, follow the steps below.

  1. Stop YSoft SafeQ Spooler Controller service.

  2. Enable encrypted communication with Spooler Controller. In the management interface go to the System Configuration > Expert options find the following parameter

    usePlainCommunicationForOrsSubsystems

    and set it to Disabled.

  3. Copy your key/certificate and certificate of the root certification authority, both in the Java Keystore format, to the server where the Spooler Controller is installed.

  4. Set following properties in the <spoc_folder>\conf\ymq_config.properties file (usually <install_dir>\SPOC\conf\ymq_config.properties):

    keyStorePath=absolute/path/to/your/keystore.jks
    keyStorePassword=keystoreprotectingpassword
    keyStoreAlias=safeq
    keyStoreAliasPassword=keyprotectingpassword
    trustStorePath=absolute/path/to/your/truststore.jks
    trustStorePassword=truststoreprotectingpassword
    ellipticCurve=secp256r1
    certificateValidationMode=VALIDATE_CERTIFICATE

    certificateValidationMode property is currently mandatory. The recommended value is VALIDATE_CERTIFICATE, which means everything is validated including server hostname. In case you have problems with hostname verification (wrong or missing IP address in the SAN field of the server certificate), you may select IGNORE_HOSTNAME value. This option is taken into account only if this Spooler Controller acts as a client (server is always ignoring client's hostname).

  5. Start the YSoft SafeQ Spooler Controller service.

End User Interface settings

Follow the steps below to set a secure connection of the End User Interface to the Spooler Controller, which is set to communicate securely.

  1. Stop YSoft SafeQ End User Interface service.

  2. Copy your key/certificate and certificate of the root certification authority, both in the Java Keystore format, to the server where EUI is installed.

  3. Set following properties in the <eui_folder>\ui-conf\environment-configuration.properties file (usually <install_dir>\SPOC\EUI\ui-conf\environment-configuration.properties):

    messagingContext.secureMechanism=secured-messaging-context
    messagingContext.keyStorePath=absolute/path/to/your/keystore.jks
    messagingContext.keyStorePassword=keystoreprotectingpassword
    messagingContext.keyStoreAlias=safeq
    messagingContext.keyStoreAliasPassword=keyprotectingpassword
    messagingContext.trustStorePath=absolute/path/to/your/truststore.jks
    messagingContext.trustStorePassword=truststoreprotectingpassword
    messagingContext.ellipticCurve=secp256r1
    messagingContext.encryptionKeyLength=16

    There is one additional property that you can set:

    messagingContext.certificateValidationMode - default value is IGNORE_HOSTNAME. You should select the VALIDATE_CERTIFICATE value unless you have problems with hostname verification (wrong or missing IP address in the SAN field of the SPOC certificate). VALIDATE_CERTIFICATE value means that everything is validated including server hostname.

  4. Start the YSoft SafeQ End User Interface service.

FlexiSpooler settings

  1. Stop YSoft SafeQ FlexiSpooler service.

  2. Copy your key/certificate in the Personal Information Exchange format to the server where the FlexiSpooler is installed.

  3. Import the key with the signed certificate to the Windows Certificate store.
    In Windows Server 2012 and newer use the following command:

    certutil.exe -csp "Microsoft Enhanced RSA and AES Cryptographic Provider" -importpfx "My" "safeqcertificate.pfx"

    In Windows Server 2008 use the following command:

    certutil.exe -csp "Microsoft Enhanced RSA and AES Cryptographic Provider" -importpfx "safeqcertificate.pfx"

    Please note, that importing the certificate incorrectly, e.g. by using Windows Certificate Manager, may lead to "Invalid algorithm specified." errors.

  4. If you have not installed your Root CA as a trusted authority yet, do it following the guide in chapter Installing your Root CA to truststores of YSoft SafeQ machines - Windows Certificate Store in System communication hardening.

  5. Set following properties in the <fsp_folder>\Service\spooler.config file (usually <install_dir>\FSP\Service\spooler.config):

    "CertificateThumbprint":"000102030405060708090a0b0c0d0e0f10111213","encryption":"Aes128"

    The value is a thumbprint (SHA1 hash) of a certificate stored in the Windows certificate store, in the Local Computer \ Personal folder. You can obtain the thumbprint by opening the certificate (.cer or .crt) file in Windows. In the Details tab, you can find the Thumbprint field. Remove spaces and make sure there are no invisible characters when copying the value from the window (it adds an invisible character at the beginning!).

    In case you have problems with hostname verification (wrong or missing IP address in the SAN field of the SPOC certificate), you may turn off hostname verification by using value ValidateServerCertificateHost ("ValidateServerCertificateHost":"false") in the spooler.config file. This is, however, not recommended. If you do not specify it, the default value is true.

  6. Start the YSoft SafeQ FlexiSpooler service.

Mobile Print Server settings

  1. Stop YSoft SafeQ Mobile Print Server service.

  2. Copy your key/certificate in the Personal Information Exchange format to the server where the Mobile Print Server is installed.

  3. Import the key with the signed certificate to the Windows Certificate store.
    In Windows Server 2012 and newer use the following command:

    certutil.exe -csp "Microsoft Enhanced RSA and AES Cryptographic Provider" -importpfx "My" "safeqcertificate.pfx"

    In Windows Server 2008 use the following command:

    certutil.exe -csp "Microsoft Enhanced RSA and AES Cryptographic Provider" -importpfx "safeqcertificate.pfx"

    Please note, that importing the certificate incorrectly, e.g. by using Windows Certificate Manager, may lead to "Invalid algorithm specified." errors.

  4. If you have not installed your Root CA as a trusted authority yet, do it following the guide in chapter Installing your Root CA to truststores of YSoft SafeQ machines - Windows Certificate Store in System communication hardening.

  5. In the <mps_folder>\Service\conf\mps.config file (usually <install_dir>\MPS\Service\conf\mps.config) edit the following tag to contain certificate thumbprint (hash) and the encryption type.

    <communicator connectionLostTimeout="4000" controllerPort="5555" certificateThumbprint="000102030405060708090a0b0c0d0e0f101213" encryption="Aes128" />

    The value is a thumbprint (SHA1 hash) of a certificate stored in the Windows certificate store, in Local Computer \ Personal folder. You can obtain the thumbprint by opening the certificate (.cer or .crt) file in Windows. In the Details tab, you can find the Thumbprint field. Remove spaces and make sure there are no invisible characters when copying the value from the window (it adds an invisible character at the beginning!).

    In case you have problems with hostname verification (wrong or missing IP address in the SAN field of the Spooler Controller certificate), you may turn off hostname verification by using the attribute ValidateServerCertificateHost (ValidateServerCertificateHost="false") in the communicator tag above. This is, however, not recommended. If you do not specify it, the default value is true.

  6. Start the YSoft SafeQ Mobile Print Server service.

Workflow Processing System settings

  1. Stop YSoft SafeQ Workflow Processing System service.

  2. Copy your key/certificate in the Personal Information Exchange format to the server where the Workflow Processing System is installed.

  3. Import the key with the signed certificate to the Windows Certificate store.

    In Windows Server 2012 and newer use the following command:

    certutil.exe -CSP "Microsoft Enhanced RSA and AES Cryptographic Provider" -importpfx "My" "safeqcertificate.pfx"

    In Windows Server 2008 use the following command:

    certutil.exe -CSP "Microsoft Enhanced RSA and AES Cryptographic Provider" -importpfx "safeqcertificate.pfx"

    Please note, that importing the certificate incorrectly, e.g. by using Windows Certificate Manager, may lead to "Invalid algorithm specified." errors.

  4. If you have not installed your Root CA as a trusted authority yet, do it following the guide in chapter Installing your Root CA to truststores of YSoft SafeQ machines - Windows Certificate Store in System communication hardening.

  5. In the <wps_folder>\WpsService.exe.config file (usually <install_dir>\WPS\WpsService.exe.config) add the following keys, where the value of certificateThumbprint key is set to the client certificate thumbprint (hash):

    <add key="certificateThumbprint" value="000102030405060708090a0b0c0d0e0f101213" />
    <add key="ymqEncryption" value="Aes128" />

    The value is a thumbprint (SHA1 hash) of a certificate stored in the Windows certificate store, in Local Computer \ Personal folder. You can obtain the thumbprint by opening the certificate (.cer or .crt) file in Windows. In the Details tab, you can find the Thumbprint field. Remove spaces and make sure there are no invisible characters when copying the value from the window (it adds an invisible character at the beginning!).

    In case you have problems with hostname verification (wrong or missing IP address in the SAN field of the Spooler Controller certificate), you may turn off hostname verification by using key validateServerCertificateHost (<add key="validateServerCertificateHost" value="false" />) in the WpsService.exe.config file. This is, however, not recommended. If you do not specify it, the default value is true. If the validation is enabled, Workflow Processing System will check that CN specified in the certificate matches with the Spooler Controller server address specified in the configuration file.

  6. Start the YSoft SafeQ Workflow Processing System service.

Terminal Server settings

Once Workflow Processing System is set for secure communication, the Workflow Processing System endpoint is accessible only using the HTTPS address. You need to set this in the Terminal Server configurations along with the valid certificate. To set up Terminal Server to use HTTPS communication, you need to edit <install_dir>\SPOC\terminalserver\terminalserver.exe.config configuration file and set the wpsBaseAddress parameter to URL that has set the HTTPS protocol.


<add key="wpsBaseAddress" value="https://SCAN SERVER OR IP:port/" />

In case you have problems with hostname verification (wrong or missing IP address in the SAN field of the Workflow Processing System certificate), you may turn off hostname verification by using key validateServerCertificateHost (<add key="validateServerCertificateHost" value="false" />) in the <spoc_folder>terminalserver\TerminalServer.exe.config file (usually <install_dir>\SPOC\terminalserver\TerminalServer.exe.config). This is, however, not recommended. If you do not specify it, the default value is true. If the validation is enabled, Terminal Server will check that CN specified in the certificate matches with the Workflow Processing System server address specified in the configuration file.

Mobile Integration Gateway settings

  1. Stop YSoft SafeQ Mobile Integration Gateway service.

  2. Copy your key/certificate in the Personal Information Exchange format to the server where the Mobile Integration Gateway is installed.

  3. Import the key with the signed certificate to the Windows Certificate store.
    In Windows Server 2012 and newer use the following command:

    certutil.exe -csp "Microsoft Enhanced RSA and AES Cryptographic Provider" -importpfx "My" "safeqcertificate.pfx"

    In Windows Server 2008 use the following command:

    certutil.exe -csp "Microsoft Enhanced RSA and AES Cryptographic Provider" -importpfx "safeqcertificate.pfx"

    Please note, that importing the certificate incorrectly, e.g. by using Windows Certificate Manager, may lead to "Invalid algorithm specified." errors.

  4. If you have not installed your Root CA as a trusted authority yet, do it following the guide in chapter Installing your Root CA to truststores of YSoft SafeQ machines - Windows Certificate Store in System communication hardening.

  5. In the <mig_folder>\bin\MigService.exe.config file (usually <install_dir>\MIG\bin\MigService.exe.config) add the following key with value set to the client certificate thumbprint (hash).

    <add key="certificate-hash" value="000102030405060708090a0b0c0d0e0f10111213" />

    The value is a thumbprint (SHA1 hash) of a certificate stored in the Windows certificate store, in Local Computer \ Personal folder. You can obtain the thumbprint by opening the certificate (.cer or .crt) file in Windows. In the Details tab, you can find the Thumbprint field. Remove spaces and make sure there are no invisible characters when copying the value from the window (it adds an invisible character at the beginning!).

  6. Start the YSoft SafeQ Mobile Integration Gateway service.