Howto:Create a self-signed multi-domain certificate with XCA

From innovaphone wiki
Jump to navigation Jump to search

Applies To

This information applies to:

  • innovaphone PBX and innovaphone App Platform (server devices)
  • innovaphone IP phones, gateways and other client devices (trust lists)
  • XCA - X Certificate and Key Management, version 2.9.0 or newer
  • Windows 10/11 (XCA is also available for macOS and Linux)


More Information

This Howto explains how to use the free tool XCA to create a private key and a self-signed certificate that contains several host names in the Subject Alternative Name (SAN) extension. One certificate can then be used on all systems of an installation, for example a master PBX, a standby PBX and two App Platforms.

The following example host names are used throughout this article:

Host name (FQDN) Role
marine-master.karls.nl Master system
marine-standby.karls.nl Standby system (takes over when the master fails)
marine-ap1.karls.nl App Platform 1
marine-ap2.karls.nl App Platform 2

Problem Details

Every device that offers an encrypted service - a web interface over HTTPS, SIP over TLS, LDAPS, a secure WebSocket connection - needs an X.509 certificate together with the matching private key. The certificate tells a connecting client which host it is talking to and holds the public key used to set up the encrypted session. The private key stays on the device and proves that the device really owns the certificate.

Out of the box a device uses a factory-generated certificate. Such a certificate does not contain the host names under which the device is actually reached, so browsers and other clients show warnings such as Your connection is not private or certificate name mismatch, and strict TLS clients refuse the connection completely.

Modern clients ignore the Common Name (CN) of a certificate and only check the Subject Alternative Name (SAN) extension. A certificate is therefore valid for a host only if that host name appears in the SAN list. By putting all four names in the SAN extension, one certificate (and one private key) can be used on all four systems. A client that fails over from master to standby then sees the same, already trusted certificate.

Certificates can be created with the OpenSSL command line, but that requires configuration files, long command lines and careful handling of keys. XCA is a free, open-source graphical tool that does the same work in a few dialogs:

  • Free and open source (BSD licence), available for Windows, macOS and Linux.
  • Encrypted database - all keys, requests and certificates are stored in one password-protected database file (*.xdb), which is easy to back up.
  • Templates - predefined templates such as TLS_server set the correct key usage and extended key usage automatically.
  • SAN editor - Subject Alternative Names are entered in a table, so no OpenSSL syntax is needed.
  • All common formats - export to PEM, PEM + key, DER, PKCS#7 and PKCS#12 (PFX), as required by the target device.
  • Own CA possible - XCA can also act as a small private Certificate Authority if you later want to sign several device certificates with one root.

Self-signed or CA-signed? A self-signed certificate is signed with its own private key. It is ideal for closed, internal installations. Clients trust it once the certificate itself has been imported as trusted (see Making clients trust the certificate). For systems that are reached by arbitrary external clients, a certificate from a public CA is the better choice; XCA can also create the Certificate Signing Request (CSR) for that.

System Requirements

  • A Windows, macOS or Linux PC for XCA
  • XCA 2.9.0 or newer
  • DNS entries for all host names that will be part of the certificate
  • Administrative access to the certificate management of the innovaphone devices

Installation

Download XCA

Download XCA only from the official sources below. The author of XCA is Christian Hohnstädt; the project is hosted on GitHub.

Source Link
Official website https://hohnstaedt.de/xca/
Official download page https://hohnstaedt.de/xca/index.php/download
GitHub releases (all versions) https://github.com/chris2511/xca/releases
Latest release https://github.com/chris2511/xca/releases/latest
Source code https://github.com/chris2511/xca
Documentation / manual https://hohnstaedt.de/xca/index.php/documentation/manual

The release page of version 2.9.0 (released 28 March 2025) contains these files:

File Size Use
xca-2.9.0-win64.msi 25.7 MB Windows installer (recommended for Windows 10/11, 64-bit)
xca-portable-2.9.0.zip 17.8 MB Windows portable version - unzip and run, no installation or admin rights needed
xca-2.9.0-Darwin.dmg 30.7 MB macOS disk image
xca-2.9.0.tar.gz 1.9 MB Source code (for building on Linux/Unix)

On Linux XCA is normally installed from the distribution's package manager, for example sudo apt install xca on Debian/Ubuntu or sudo dnf install xca on Fedora. The version in the distribution can be older than the GitHub release.

Tip: check on the GitHub releases page whether a newer version than 2.9.0 is available, and always use the latest release.

Install XCA on Windows (MSI installer)

  1. Download xca-2.9.0-win64.msi.
  2. Double-click the downloaded file. If Windows SmartScreen asks, confirm that you want to run the installer.
  3. Click Next, accept the licence agreement and click Next again.
  4. Keep the default installation folder C:\Program Files\xca\ and click Next.
  5. Click Install and confirm the User Account Control prompt (administrator rights are required).
  6. Click Finish. XCA is now available in the Start menu as XCA.

Install XCA on Windows (portable version)

  1. Download xca-portable-2.9.0.zip.
  2. Unzip it into a folder of your choice, for example on a USB stick.
  3. Start xca.exe from that folder. No administrator rights are needed.

Install XCA on macOS and Linux

  • macOS: open the .dmg file and drag XCA into the Applications folder. On the first start, right-click the app and choose Open if macOS blocks it.
  • Linux: install the package of your distribution (see above) and start xca from the application menu or the terminal.

Check the installed version

Choose Help → About in XCA, or run the following command in a command prompt:

"C:\Program Files\xca\xca.exe" --version

The output should show Version 2.9.0 (or newer).

Configuration

Create a database

XCA stores everything in a database file. Create a separate database for each customer or installation, so that keys of different projects are never mixed.

  1. Start XCA and choose File → New DataBase.
  2. Choose a location and file name, for example marine-karls.xdb, and click Save.
  3. Enter a strong database password twice and click OK. This password encrypts all private keys in the database.
  4. The main window opens with the tabs Private Keys, Certificate signing requests, Certificates, Templates and Revocation lists. The status bar at the bottom shows which database is open.
XCA main window with an empty database

Important: store the database password in your password manager - without it the private keys in the database cannot be recovered. Back up the .xdb file regularly; it contains your private keys.

Set the options

XCA 2.9 warns when the database still uses the old PKCS#12 encryption algorithm. This algorithm is only used when you export PFX files, but it should be changed to a modern one.

Warning about the insecure PKCS#12 algorithm
  1. Click Change in the warning, or open File → Options at any time.
  2. On the Settings tab set Default hash algorithm to SHA256.
  3. Set PKCS12 encryption algorithm to AES-256-CBC.
  4. Leave the other settings at their default values and click OK.
XCA Options - SHA256 and AES-256-CBC selected

Optionally, on the Distinguished name tab you can choose which subject fields are shown by default when you create new certificates.

Create the private key

The private key is created first and stored in the database. The certificate is then built on this key.

  1. Open the Private Keys tab and click New Key.
  2. Enter a Name for the key, for example marine-karls-key. This is only the internal name inside XCA.
  3. Select Keytype: RSA and Keysize: 2048 bit.
  4. Click Create.
New Key dialog - RSA, 2048 bit

Choosing the key type and size: RSA 2048 bit is supported by every innovaphone device and client and is the safe default. RSA 4096 bit or EC (for example prime256v1) are also possible, if all devices that will use the certificate support them. Check the documentation of the target device first. A larger key results in a much higher CPU load and can cause delay issues.

XCA confirms that the key has been created, and the key appears in the list. The column Use shows 0, because no certificate uses the key yet.

Confirmation message
The new private key in the Private Keys tab

Create the self-signed certificate

Now a certificate is created that is signed with the private key and contains all four host names. Open the Certificates tab and click New Certificate. The dialog Create x509 Certificate opens. Work through the tabs from left to right.

Tab Source
  1. Under Signing select Create a self signed certificate.
  2. Check that Signature algorithm is SHA256.
  3. Under Template for the new certificate select [default] TLS_server.
  4. Click Apply all. This fills the extensions and key usage for a TLS server certificate.
Source tab - self-signed with the TLS_server template
Tab Subject
  1. Enter an Internal Name, for example marine-karls-cert.
  2. Fill in the distinguished name (example values below).
  3. Under Private key select the key created before: marine-karls-key (RSA:2048 bit). Do not click Generate a new key.
Field Example value
countryName NL
stateOrProvinceName (optional)
localityName (optional)
organizationName Karls
organizationalUnitName Marine
commonName marine-master.karls.nl
emailAddress (leave empty)
Subject tab with the distinguished name and the selected private key

Note: the commonName holds only one name. The other host names are added as Subject Alternative Names in the next step. The name in commonName must also be in the SAN list, because clients only check the SAN.

Tab Extensions - validity and Subject Alternative Name
  1. Check that X509v3 Basic Constraints - Type is End Entity (this is not a CA certificate).
  2. Leave X509v3 Subject Key Identifier and X509v3 Authority Key Identifier checked.
  3. Under Time range enter the validity, for example 3 Years, and click Apply. The Not before and Not after dates are updated.
  4. Click Edit next to X509v3 Subject Alternative Name.
Extensions tab - End Entity, 3 years validity and the SAN list

In the SAN editor:

  1. Uncheck Copy Common Name (the common name is entered explicitly as the first entry instead).
  2. Click Add, select type DNS and enter marine-master.karls.nl.
  3. Repeat for marine-standby.karls.nl, marine-ap1.karls.nl and marine-ap2.karls.nl.
  4. Click Validate to check the entries, then click Apply.
SAN editor with the four DNS names

Back on the Extensions tab, the field shows the result and a green check mark. You can also type this text directly into the field instead of using the editor:

DNS:marine-master.karls.nl, DNS:marine-standby.karls.nl, DNS:marine-ap1.karls.nl, DNS:marine-ap2.karls.nl

Validity period: for a self-signed certificate in a closed installation, 1 to 3 years is a common choice. Note the expiry date in your maintenance calendar. Some browsers do not accept server certificates valid for more than 398 days if they were issued by a public CA. This rule does not apply to self-signed certificates that you have trusted manually, but a shorter validity is still good practice.

Tab Key usage

The TLS_server template has already selected the correct values. Do not change them:

  • X509v3 Key Usage: Digital Signature, Non Repudiation, Key Encipherment, Key Agreement
  • X509v3 Extended Key Usage: TLS Web Server Authentication

If the certificate is also used for client connections (for example SIP-TLS between systems where the device also connects as client), additionally select TLS Web Client Authentication in the right-hand list.

Key usage tab - selected entries are highlighted
Create the certificate

The tabs Netscape, Advanced and Comment can be left as they are. Click OK. XCA confirms the creation and the certificate appears in the Certificates tab.

Confirmation message
The new certificate in the Certificates tab

Check the certificate

Double-click the certificate (or select it and click Show Details) and open the Extensions tab. Check that:

  • Basic Constraints show CA:FALSE.
  • Extended Key Usage shows TLS Web Server Authentication.
  • Subject Alternative Name contains all four DNS names.
Certificate details - Extensions tab

On the Status tab you find the serial number, the SHA-1 and SHA-256 fingerprints and the validity period. Write down the SHA-256 fingerprint; it can be used later to check that a device really presents this certificate.

Optionally, the exported file (see next step) can be checked with OpenSSL:

openssl x509 -in marine-karls-cert.pem -noout -subject -dates -ext subjectAltName

Result of the example certificate:

subject=C=NL, O=Karls, OU=Marine, CN=marine-master.karls.nl
notBefore=Oct 27 13:46:00 2026 GMT
notAfter=Oct 27 13:46:00 2029 GMT
X509v3 Subject Alternative Name:
    DNS:marine-master.karls.nl, DNS:marine-standby.karls.nl,
    DNS:marine-ap1.karls.nl, DNS:marine-ap2.karls.nl

Export the certificate

  1. In the Certificates tab select marine-karls-cert and click Export.
  2. Choose the Export Format that the target device expects (see the table below). For innovaphone server devices (PBX and App Platform) choose PEM + key (*.pem).
  3. Enter the Filename (or use the ... button) and click OK.
Export dialog - PEM + key
Export format When to use
PEM + key (*.pem) Certificate and unencrypted private key in one text file. Common for appliances and web servers that import a single PEM file. Use this type for innovaphone server devices (PBX and App Platform).
PKCS #12 (*.pfx) Certificate and key in one password-protected file. Used by Windows, IIS and many devices. XCA asks for an export password.
PEM (*.crt) Certificate only, without key. Use this to distribute trust to clients. Use this one for the trust list of innovaphone and 3rd-party client devices.
DER (*.cer) Certificate only, binary format. For clients that do not accept PEM.

The private key alone can be exported from the Private Keys tab (select the key, Export, format PEM private or PEM encrypted) if a device needs certificate and key as two separate files.

Security of exported files: a PEM + key file contains the private key unencrypted. Transfer it only over secure channels, upload it to the devices and then delete it from your PC. The original stays protected in the XCA database. Prefer PKCS#12 with a strong password when the file has to be sent or stored.

Install the certificate on the systems

Upload the exported file in the certificate management of each system - marine-master.karls.nl, marine-standby.karls.nl, marine-ap1.karls.nl and marine-ap2.karls.nl. Because all names are in one certificate, the same file is used on all four systems. Afterwards restart the service or device if the device requires it, and open https:// to check that the new certificate is presented.

Make sure that all four names resolve in DNS to the correct IP addresses; the certificate is only accepted when the client connects using one of the names in the SAN list (not by IP address).

Making clients trust the certificate

Because the certificate is self-signed, clients do not trust it automatically. Export the certificate without key (format PEM *.crt or DER *.cer) and import it on the clients as a trusted root certificate:

  • Windows: run certlm.msc (computer) or certmgr.msc (user), right-click Trusted Root Certification Authorities → Certificates, choose All Tasks → Import and select the .crt file. In a domain this can be distributed by Group Policy.
  • macOS: open the .crt file in Keychain Access, add it to the System keychain and set When using this certificate to Always Trust.
  • Firefox: Settings → Privacy & Security → Certificates → View Certificates → Authorities → Import.
  • innovaphone and other devices (phones, gateways): upload the .crt file into the list of trusted certificates of the device.

Maintenance and best practices

  • Backup: keep a copy of the .xdb database file and its password in a safe place.
  • Renewal: before expiry, select the certificate in XCA and use right-click → Renewal to issue a new certificate with the same key and names, or create a new one as described above. Export and upload it again.
  • Adding a host: if a fifth system is added, create a new certificate with the extended SAN list; an existing certificate cannot be changed.
  • Expiry warning: XCA colours certificates that are close to expiry. In File → Options you can set the warning threshold and export a vCalendar reminder (export format vCalendar *.ics).
  • One database per installation: this keeps keys of different customers separated.
Summary of the example values
Item Value
Database marine-karls.xdb (password protected)
Private key marine-karls-key - RSA 2048 bit
Certificate (internal name) marine-karls-cert
Type Self-signed, End Entity, template TLS_server
Signature algorithm SHA256 with RSA
Subject C=NL, O=Karls, OU=Marine, CN=marine-master.karls.nl
Subject Alternative Names DNS:marine-master.karls.nl
DNS:marine-standby.karls.nl
DNS:marine-ap1.karls.nl
DNS:marine-ap2.karls.nl
Validity 3 years
Export for devices PEM + key (*.pem) or PKCS#12 (*.pfx)
Export for clients PEM (*.crt) or DER (*.cer), certificate only

Known Problems

Browser still shows a certificate warning

The certificate is self-signed, so each client must trust it explicitly (see Making clients trust the certificate). Also make sure the device is opened by one of the host names in the SAN list and not by its IP address.

Certificate name mismatch after adding a new system

The SAN list of an existing certificate cannot be extended. Create a new certificate that contains all host names and install it on all systems.

Higher CPU load with large keys

RSA keys larger than 2048 bit cause a much higher CPU load on the devices during TLS handshakes and can lead to delays. Use RSA 2048 bit unless a larger key is explicitly required.

As an alternative to larger RSA keys, use an elliptic-curve (EC) key. In the New Key dialog select Keytype: EC and the curve prime256v1 (also known as secp256r1 or NIST P-256) instead of an RSA key size. A P-256 key offers a security level comparable to RSA 3072 bit, but with much smaller keys and a clearly lower CPU load during the TLS handshake. The certificate is then created in the same way as described above; XCA signs it with ECDSA (ecdsa-with-SHA256).

Before switching to an EC key, check that all devices and clients that use or trust the certificate support EC (ECDSA) certificates - older firmware versions and some 3rd-party clients only support RSA. Do not use the curve secp521r1, as it is no longer offered by many browsers and TLS clients.

Related Articles