HOWTO: Configure custom certificates for the downstream communication of the RES ONE Workspace Portable Relay Server

Version 1

    Question

    HOWTO: Configure custom certificates for the downstream communication of the RES ONE Workspace Portable Relay Server

     

    Answer

    The RES ONE Workspace Portable Relay Server can be configured to use a certificate for the downstream communication by using the options CertificateFile and CertificateKeyFile.
    With the certificate the clients that make a connection can verify the identity of the RES ONE Workspace Portable Relay Server.
    This can be an external certificate that is purchased from an official organization as well as a domain certificate that is authorized against an internal PKI.
    To be able to establish a connection, a client needs to be able to verify this certificate supplied by the server.
    This client can be a RES ONE Workspace Agent as well as a downstream RES ONE Workspace Portable Relay Server.
    An external certificate will automatically be trusted by default on both Microsoft Windows as well as on Linux machines, since the necessary root certificate will already be installed.
    However, a domain certificate will only be trusted by default on Microsoft Windows machines that are a part of that domain. It will not be trusted by default on Linux machines.
    To establish this trust on Linux, the root certificate used for this domain certificate needs to be installed on the Linux machine.

    The procedure below describes how to implement the certificates on Linux.
    The certificate needs to be available as PFX file and the root certificate as CER file.
    There are multiple ways to acquire these files. Below there is one example when a wildcard certificate is used on the RES ONE Workspace Relay Server for Microsoft Windows.

    Example: Export the wildcard certificate and root certificate from the RES ONE Workspace Relay Server for Microsoft Windows
    Export the certificate and save it as a PFX file.
    • Start Manage computer certificates from Control Panel.
    • Open the installed certificate in the Personal store.
    • Use the option Copy to File on the tab Details to start the Certificate Export Wizard.
    • Choose the options Yes, export the private key and Include all certificates during the export.
    • Save the certificate as PFX file (e.g.: wildcard.yourdomain.local.pfx for a wildcard certificate)
    Export the root certificate and save it as a CER file.
    • Start Manage computer certificates from Control Panel.
    • Open the installed certificate in the Personal store.
    • Select the root certificate on the tab Certification Path and click View Certificate.
    • Use the option Copy to File on the tab Details to start the Certificate Export Wizard.
    • Choose the format Base-64 encoded X.509 (.CER) during the export.
    • Save the certificate as CER file (e.g.: rootca.yourdomain.local.cer).
    Convert the certificate (PFX file) for the RES ONE Workspace Portable Relay Server for Linux
    Copy the certificate (PFX file) to the machine that runs the RES ONE Workspace Portable Relay Server for Linux.
    The certificate needs to be valid for the machine. So this can be a certificate on name or a wildcard certificate (e.g.: *.yourdomain.local).
    Change the name of the certificate in the examples below to the actual name of the certificate.
    • Generate the KEY and CRT files from the PFX file
    openssl pkcs12 -in nameorwildcard.yourdomain.local.pfx -out output.pem -nodes -password pass:passwordofpfx
    sed -n '/^-----BEGIN PRIVATE KEY-----/,/^-----END PRIVATE KEY-----/p' output.pem > relayserver.key
    sed -n '/^-----BEGIN CERTIFICATE-----/,/^-----END CERTIFICATE-----/p' output.pem > relayserver.crt
    rm -f output.pem
    • Copy the KEY and CRT file to /etc/res, set owner to res-relayserver and set permissions.
    cp relayserver.crt /etc/res/relayserver.crt
    cp relayserver.key /etc/res/relayserver.key
    chown res-relayserver:res-relayserver /etc/res/relayserver.*
    chmod 644 /etc/res/relayserver.crt
    chmod 600 /etc/res/relayserver.key

    Notes
    The file relayserver.crt should start with the host certificate, followed by all intermediate certificates (so not the root certificate).
    If there are no intermediate CA's involved, then the certificate chain file only contains the host certificate.

    The example commands use the default location of the CRT and KEY file.
    If different locations are specified in /etc/res/relayserver-config.xml, then these should be used.


    Install the root certificate on a RES ONE Workspace agent for Linux or downstream RES ONE Workspace Portable Relay Server for Linux
    This only applies to a scenario where a domain certificate is used.
    Install the root certificate so that the domain certificate will be trusted.
    Change the name of the root certificate in the examples below to the actual name of the root certificate.
    • Copy the root certificate (CER file) to the machine (e.g.: rootca.yourdomain.local.cer).
    • Use dos2unix to remove the Microsoft Windows style line-breaks.
    dos2unix rootca.yourdomain.local.cer
    • Install the root certificate on CentOS or Red Hat Enterprise Linux (RHEL).
    cp rootca.yourdomain.local.cer /etc/pki/ca-trust/source/anchors/rootca.yourdomain.local.cer
    chmod 644 /etc/pki/ca-trust/source/anchors/rootca.yourdomain.local.cer
    update-ca-trust
    • Install the root certificate and change the extension to CRT on Ubuntu.
    cp rootca.yourdomain.local.cer /usr/local/share/ca-certificates/rootca.yourdomain.local.crt
    chmod 644 /usr/local/share/ca-certificates/rootca.yourdomain.local.crt
    update-ca-certificates