Skip to main content
Version: 4.2 (beta)

SSL Certificates for Cryptography

HSYCO supports high-grade cryptography (TLS ECDHE RSA with AES 128 GCM SHA 256, 128 bit keys, TLS 1.2) to protect the communication between the web browser used by HSYCO web interface and the HSYCO web server.

This is considered secure for commercial applications (for example, on-line banking and e-commerce) and for the exchange of classified information.

HSYCO can use either self-generated certificates, or import certificates issued by a Certification Authority (CA).

note

A Java Virtual Machine version 8 or above is required to fully support HTTPS encryption, and to ensure compatibility with modern Web browsers.

Self-Generated Certificates​

When the SSL certificate is generated by HSYCO, it is not signed by a CA recognized by the Web Browser. It is normal for the browser to display a security message during the first access or periodically at the beginning of a new session.

This message asks for confirmation of the server's reliability. Since the certificate is not signed by a known CA, the browser cannot guarantee the identity of the server. By accepting the certificate, the connection is established and you may proceed.

Even with self-generated certificates, all exchanged data is protected by the same level of cryptography as with signed certificates.

Configuration and Storage​

  • ServerName: This parameter in hsyco.ini specifies the name used to generate the certificate and must correspond to the domain name used to access HSYCO via the Internet.
  • hsyco.keys: The certificate is stored in this file. If the file is missing at startup, HSYCO automatically generates a new one based on the ServerName. Otherwise, HSYCO simply uses the certificate contained in this file, which could have also been generated by an official Certification Authority (CA).
  • Automatic Updates: If the ServerName is modified, HSYCO will automatically recreate the hsyco.keys file upon the next restart.

Importing the Self-Generated Certificate on your Client​

With some browsers and operating systems, like Safari on iOS, permanently importing the self-generated certificate in the local keystore could improve usability. Once stored, the browser will accept the connection without asking for confirmation and, on iOS, will significantly improve GUI initialization time.

To download the public key in PEM format, click the link in the logout panel and follow your operating system's instructions.

Logout Download Pem Certificate

Certificates Issued by Certification Authorities​

Automatic Managed Import (ZeroSSL)​

HSYCO can be configured to automatically request certificates to the ZeroSSL Certification Authority. A ZeroSSL account that supports their "REST API Access" is required.

In order to enable this feature, all relevant parameters must be configured in the Network tab of System Settings.

HSYCO will request a certificate when the current certificate is self-generated, or if it is expired or expiring in less than the number of days set with the HTTPSSLAdvanceRenewDays configuration parameter.

When a new certificate is issued by ZeroSSL, and downloaded by HSYCO, it will be saved in the hsyco.keys file and used by the HTTPS server for all new HTTPS connections. The downloaded certificate files, certificate.crt, ca_bundle.crt and private.key, are also saved to the hsyco.cert.save directory.

In order to issue a certificate, ZeroSSL must first verify the domain.

One way is to use HTTP verification. This is a fully automatic process, requiring no user interaction, but the unencrypted HSYCO HTTP server (not HTTPS) must be accessible from the public Internet on port 80 at the public IP address associated with the certificate's domain name.

Another option is to use email verification. ZeroSSL will send an email to the email address set with the HTTPSSLValidationEmail configuration parameter. To finalize the verification of your domain, simply grab the domain verification key, click the "Go To Verification Page" button to get to the verification page and submit the domain verification key.

HSYCO periodically checks with ZeroSSL if the certificate has been issued. Log messages are printed in the log and also at the bottom of the Network configuration page.

For example:

2022.03.16 18:19:22.443 - SSLCERTS: CSR created. Submitting to CA 
2022.03.16 18:19:25.102 - SSLCERTS: Sending email verification request to CA 
2022.03.16 18:19:27.247 - SSLCERTS: Email verification request successfully sent. Checking in 5 minutes 
2022.03.16 18:24:28.719 - SSLCERTS: Sending certifcate status request to CA 
2022.03.16 18:24:29.254 - SSLCERTS: Certificate has been issued by CA 
2022.03.16 18:24:39.313 - SSLCERTS: Sending certifcate download request to CA 
2022.03.16 18:24:39.930 - SSLCERTS: Certifcate successfully downloaded from CA 
2022.03.16 18:24:39.930 - SSLCERTS: Importing certificate 
2022.03.16 18:24:41.630 - SSLCERTS: Certificate successfully imported 
2022.03.16 18:24:41.631 - Reloading HTTPS SSL Certificate
note

Note that, in a High Availability configuration, HSYCO slave will never request new certificates from the certification authority when it is not active

Manual Import​

To manually import a certificate, you must prepare a specific set of files:

  • Required files: Obtain the following three files from your CA:

    • certificate.crt: The primary SSL certificate.
    • ca_bundle.crt: The intermediate certificate.
    • private.key: The unencrypted private key.

  • Import process:

    • Create a sub-directory called hsyco.cert in the HSYCO main directory.
    • Copy the three files above into this folder.
    • Ensure the ServerName in hsyco.ini matches the certificate’s Common Name (CN/Full Domain Name).
    • Restart HSYCO; it will import the files into hsyco.keys and delete the hsyco.cert directory.
important

HSYCO only supports single-domain certificates. Multi-domain or wildcard certificates are not supported.

Let's Encrypt Certificates​

Let's Encrypt certificates are highly compatible but often require manual extraction from their standard .pem delivery format. Your goal is to extract the files defined in the Manual Import section.

  • Extracting the Intermediate Certificate: Let's Encrypt chains (e.g., fullchain.pem or chain.pem) typically include the R12 intermediate and the ISRG Root X1. Only the R12 intermediate should be saved as ca_bundle.crt. You can extract it using this command:

    awk 'BEGIN{c=0} /-----BEGIN CERTIFICATE-----/{c++} c==1{print} /-----END CERTIFICATE-----/ && c==1{exit}' chain.pem > ca_bundle.crt

  • Decrypting the Private Key: The private key must be unencrypted before HSYCO can import it. If your key is encrypted, use OpenSSL to decrypt it:

    openssl pkcs8 -in encrypted_private.key -out private.key

  • Verify the Pair: Before placing the files in the hsyco.cert folder, ensure the key and certificate match by checking their MD5 moduli hashes:

    openssl x509 -noout -modulus -in certificate.crt | openssl md5
    openssl pkey -noout -modulus -in private.key | openssl md5

Both commands must produce the exact same hash. Once verified, proceed with the Manual Import.