Generating certificate for signing access tokens/secured SSL connection

There are 2 types of certificates used to improve security with two different usages - certificates for signing access tokens (signing certificate) and certificates for secured HTTPS connection (SSL certificate for SSL server authentication). While under normal circumstances, the same certificate can be used for both HTTPS and client token signature, it is not always the case so it is important to distinguish between them.

A signing certificate is used to sign access tokens used by clients during communication with the server. The server validates whether access tokens are signed with the correct certificate. This feature ensures that only access tokens created by YSoft SafeQ are accepted.

  • The same signing certificate must be used during the installation of every job service in the near roaming group.

  • The signing certificate is NOT the certificate that is used for HTTPS.

A signing certificate can be generated using a PowerShell script included in the YSoft SafeQ Job Service package - generateCertificate.ps1.

For SSL server authentication (required for secured HTTPS connection), SSL certificate is used for Job Service and Client V3 when they are in server mode and SSL authentication is turned on. It is expected to provide a certificate during installation but if that's not the case the certificate is generated automatically during installation since it is required for secured HTTPS communication. GenerateCertificate.ps1 script for generation of signing certificates may be used to manually create SSL certificates as well. Automatically generated, self-signed certificate doesn't have correct SAN and subject and therefore doesn't satisfy all requirements since server identity is not guaranteed. Therefore when using such certificates server authentication (certificate validation) must be turned off. The minimal requirement for SSL certificates is to have proper SAN but using a bare certificate like that is not recommended.

As a good practice the following setup is recommended for a Server certificate:

  1. Key Usage (at least):

  2. enhanced Key Usage (at least):

  3. SAN: SAN must contain all addresses/domain names that will be used to connect the server. E.g. if someone adds a printer using IP address 1.2.3.4, then this address has to be in SAN otherwise the connection will be aborted. If someone else will use DNS record myserver1.company.com to access the same machine, then this value must be also in the SAN (note that wildcard records such as *.company.com will work as well).

  4. CN: Also known as the Fully Qualified Domain Name (FQDN), is usually composed of Host Domain Name (recommended form) and acts as a fallback for SAN. If SAN is present then there are no requirements for CN. On the other hand, if there is no SAN in the certificate at all, then CN is validated against the address (IP or DNS) that was used to establish the connection.


The script has the following arguments.

How to

  1. Run script - generateCertificate.ps1

    Example of script usage

    Do not use this example for production. The password in the example is not secure.

    .\generateCertificate.ps1 -Subject "YSoft SafeQ" -FriendlyName "YSoft SafeQ Signing Certificate" -Password "123456" -SubjectAlternativeNames "*.company.com", "1.2.3.4"

    The certificate will be stored in a file named after FriendlyName (e.g. "YSoft SafeQ Signing Certificate.pfx").

Script arguments

Argument name

Description

Required

-Subject

Name of the person or entity to whom the certificate is being issued. This field can also include the certificate recipient's organization, organization unit, locality, state or province, and country/region. Will be used as CN therefore preferred form is FQDN (fully qualified domain name).

yes

-FriendlyName

The name under which you will see the certificate in the Microsoft Management Console. It is not a unique identifier.

yes

-Password

Password used for private key encryption.

yes

-SubjectAlternativeNames

All addresses/domain names that will be used to connect the server. While not recommended, it is possible to use the localhost address as well (e.g. when a non-spooling client is connected via HTTPS over localhost to Client V3 installed locally).

no/yes*

*is not required to run the script or to use the minimum version of the signing certificate but is required to be included in a valid SSL certificate.