Certificate and Key Management and Usage

This document presents the WeOS certificates repository its usage and how to manage it with examples. Certificates and keys can be managed from both CLI and Web interfaces. When using CLI use the /pki/#> and /pki/cert/#> for management.

Security

Improper timekeeping or time-related attacks can lead to various security vulnerabilities, such as expired certificates being considered valid or incorrect timestamps on logs and transactions. Attackers may exploit these vulnerabilities to bypass security mechanisms, disrupt services, or manipulate data integrity. Ensuring accurate and secure time synchronization is critical to maintaining the reliability and security of the PKI system.

What is the Certificate Repository?

The WeOS certificate repository holds cryptographic certificates and keys used by WeOS services utilizing asymmetric and symmetric cryptography, all-together called PKI Artifacts. An example of such can be found in the WeOS Web server, which by default uses a unique, self-signed certificate (and associated private key) for its HTTPS service.

It is possible to import your own certificates and associated private keys to be used for Web/HTTPS or other services, e.g. tunnels. Certificate or OpenVPN keys may also be generated directly by WeOS. Lastly certificates could enrolled from external servers.

WeOS includes a set of default trusted CAs, used by certain WeOS client services such as DDNS, when contacting certificate based Internet services.

PKI Artifacts

The following groups of PKI artifacts can be stored in the system:

Local certificates: These are end-entity certificates that prove the validity of the system’s keys. The system inherently trusts these certificates. Associated private keys should be present in the system’s secure storage. These certificates can be imported, generated, or enrolled. End-entity certificates must have their respective chain certificates existing in the Trusted Local CA Store (see below).
Trusted Global Root CA Store: This is a built-in Mozilla Root Store of remote CA certificates that comes with the system. The store is updated with each release of the system. The content of this store cannot be changed in between releases, but some applications within the system can choose to distrust the store. More about it here.
Trusted Local CA Store: This is a store of remote CA certificates that is editable by the user. The content of this store can be changed between releases. A selection of certificates from the Global Root Store can be copied into this one to limit the trust scope.
OpenVPN Pre-Shared Keys (keys): These are static pre-shared keys shared between the client and server to secure communication without requiring a full public key infrastructure (PKI).

Each of these groups has its own namespace. Thus, it is possible to have a local end-entity certificate, a CA certificate, and an OpenVPN key all holding the same label. What a label is, is explained in the next section.

Labels

A label is used to identify a PKI artifact. Labels are used when configuring applications that use PKI credentials. In a given namespace, a label uniquely represents a credential or a bundle of credentials in the case of the Local CA store.

Certificate Chaining

Certificate chaining is a process in Public Key Infrastructure (PKI) where a trust relationship is established from an end-entity certificate (like a user’s or server’s certificate) up to a trusted root certificate authority (CA). Each certificate in the chain is signed by the one above it, forming a “chain of trust.”

      +----------+                    +---------+     
      | Root1-CA | root1-ca.pem          | Root2-CA|     
      |          |                    |         |     
      +--+-------+                    +--+------+     
         |                               |            
         | Root1 signs Int1              | Root2 signs Int2
         |                               |            
      +--v-------+                    +--v------+     
      | Int1-CA  |                    | Int2-CA |     
      |          |                    |         |     
      +--+-------+                    +-------+-+     
         |                                    |       
         | Int1 signs alice.pem               | Int2 signs bob.pem
         |                                    |       
    +----v---+  alice.pem + chain1          +-v------+
    |        +------------------------------>        |
    | Alice  |          bob.pem + chain2    | Bob    |
    |        <------------------------------+        |
    +--------+                              +--------+

Figure 1: Certificate chaining.

In the Figure 1, Root1-CA and Root2-CA are trusted root authorities (the trust anchors). Int1-CA and Int2-CA are intermediate CAs, each signed by their respective root. Alice and Bob have certificates (alice.pem and bob.pem) signed by the intermediates.

Alice imported root2-ca.pem, Root2-CA’s self-signed certificate. This way she gave trust in all certificates whose chain if trusts ends in root2-ca.pem. Bob did the same with root1-ca.pem.

When Alice presents her certificate alice.pem, she also provides the chain1 (int1-ca.pem + root1-ca.pem), allowing others to verify her identity by following the signatures up to Root1-CA. The same applies to Bob with Root2-CA. This chaining ensures that trust in the root CA extends to the end-entity certificates.

If Alice presents only the end-entity certificate, alice.pem, she assumes that Bob is in possession of Alice’s chain1 (int1-ca.pem, root1-ca.pem), which is not guaranteed and is not best practice.

When configuring a service in WeOS, e.g., a tunnel, the user configures only the end-entity certificate (alice.pem), and the system will attempt building the chain using existing certificates from the Local CA Store. If building fails the tunnel is not created. Thus, all necessary certs must be present in the system. These can be enrolled from an external server or imported manually.

Note

It is important that local end-entity certificates have their respective chain certificates existing in the system.

The unit’s default Web certificate

The default certificate is always present in WeOS, and when it is deleted, a new one will be generated automatically at reboot.

example:/#> pki cert show full
TYPE     HASH     EXPIRES     NAME                 DIST LABEL
Pub      52ff4f77 Jan 19 2038 lynx-12-34-50.local       web-default
Key      N/A      N/A         web-default               web-default

It is possible to import (see below) a custom Web server certificate to the repository, and configure the Web server to use that certificate.

Built-in Trusted Global Root-CAs

Included in the WeOS image is a set of trusted root CAs, based on Mozilla’s list of trusted root CAs. This list of root CAs is provided for convenience, and is used by WeOS services using HTTPS to securely access Internet services. An example is the WeOS DDNS client, which utilizes HTTPS to contact the DDNS provider.

The DDNS client trusts DDNS providers with a certificate issued by any of the built-in trusted root CAs by default. It is possible to configure the DDNS client to only trust certificates issued by CAs manually imported to the certificate repository.

The example below shows how to display the list of trusted CAs.

example:/#> pki cert show all
TYPE     HASH     EXPIRES     NAME                 DIST LABEL
CA-auto  2b349938 Dec 31 2030 AffirmTrust C~ercial      AffirmTrust_Commercial
CA-auto  93bc0acc Dec 31 2030 AffirmTrust N~orking      AffirmTrust_Networking
CA-auto  b727005e Dec 31 2040 AffirmTrust Premium       AffirmTrust_Premium
CA-auto  ce5e74ef Jan 17 2038 Amazon Root CA 1          Amazon_Root_CA_1
CA-auto  6d41d539 May 26 2040 Amazon Root CA 2          Amazon_Root_CA_2
...

Enrollment of Certificates

Automated issuance of digital certificates is popular because it saves time and enables devices to request, obtain, and renew certificates without manual intervention, which is particularly useful in enterprise environments where a large number of devices require certificates for secure communication and authentication purposes.

The system supports Simple Certificate Enrolment Protocol (SCEP) according to RFC 8894. Enrollment is divided into two distinct phases: a manual phase and an automated phase. During the manual phase, users configure certificates and enrollment servers. In the automated phase, a background task periodically communicates with the enrollment server to request certificates. For a more in depth description of the SCEP protocol configuration see Section SCEP.

Enrollment process relies on external servers that must be accessible from the device. To achieve that other parts of the User Guide, like configuration details of the Firewall and Ethernet Ports might be relevant.

CLI Syntax

PKI exec context

Management of certificates and keys can be done in PKI exec context:

example:/#> pki
example:/pki/#>

generate [expire <DAYS>] [modulus <BITS>] [ovpn] label <NAME>

Generate a self-signed X.509 RSA type certificate or an OpenVPN static key (PSK).

expire <DAYS>: Optional certificate validity period in days. Default 365. Applicable only for self-signed certificates.
modulus <BITS>: Optional key size in bits. Default 1024. Applicable only for self-signed certificates.
[ovpn]: Flag causing generation of a static OpenVPN key instead of a x509 certificate. When selected expire and modulus are skipped.
label NAME: A unique label of the certificate or key to be generated.

Examples:

Generate a self-signed certificate:

generate expire 365 modulus 2048 label mycert

Generate an OpenVPN static key (PSK):
```
generate ovpn label mykey
```

import <pkcs|pem|der|ovpn> type <key|pub|ca> [password <SECRET>] [label <NAME>] <URI>

Import a certificate or key from a source (HTTP/FTP/SCP/USB). The software supports importing PKCS#12, PEM and DER certificates. The latter two require the user to provide the type: private, public or CA. This to ensure the certificate is put to proper use. You may also import OpenVPN (ovpn) static keys.

Security

When importing a private key make sure the process is not intercepted during the import process, this can lead to security breaches. The private key is stored securely when device is off and decrypted on boot. Never import an untrusted key or certificate without validation, this can lead to a security breach.

<pkcs|pem|der|ovpn>

Select format of PKI artifacts to be imported.

pkcs - import PKCS12 bundle.
pem - import PEM certificate, CA certificate or private key. Additional PEM/DER options: ‘type public’ (import as certificate), ‘type ca’ (import as CA certificate), and ‘type private’ (import as private key).
der - import DER certificate, CA certificate or private key. Same options as for ‘pem’.
ovpn - import OpenVPN static key.

type <key|pub|ca>

Select type of PKI to be imported.

password <SECRET>

Password for imported certificate/key (Optional when encrypted).

label <NAME>

A unique label of the certificate or key to be generated.

Source (HTTP/FTP/SCP/USB) of the PKI artifact.

remove [force] [LABEL [LABEL ...]] [HASH [HASH ...]]

Remove all or only selected PKI artifacts. Without any input arguments the command removes ALL artifacts. If a label is specified and there are many different types of PKI artifacts having the same label (e.g. key and certificate) you will be prompted before deleting each of them.

force: Force removal of without any questions
LABEL: Label(s) of the PKI artifact to be removed.
HASH: Subject hash of a certificate to be removed.

trigger

Trigger the pki daemon to re-read the config and send enrollment/renewal requests to the server if needed.

show [all | full] [HASH] [LABEL]

Show the complete state of PKI in the system.

Status of PKI daemon.
Status of enrollment server.
List of revocation distribution points.
List all PKI artifacts in the system including (certificates, keys, openvpn-keys)

all: Display all certificates from the Built-in Trusted Global Root-CA Store.
full: Display all certificates from the Trusted Local CA Store.
HASH: Details of selected PKI artifacts
LABEL: Details of selected PKI artifacts

PKI-cert exec context

There are also certificate specific commands in the cert context:

example:/pki/#> cert
example:/pki/cert/#>

enroll <LABEL>

Enroll a certificate from an enrollment server. This topic is described in details here.

LABEL: Unique label of a certificate to enroll. See here for details.

show [all | full | HASH | LABEL]

Dump certificate information: attributes & meta data.

all: Display all certificates from the preinstalled Trusted Global Root-CA Store.
full: Display all certificates from the Trusted Local CA Store.
HASH: Details of selected PKI artifacts
LABEL: Details of selected PKI artifacts

remove [force] [LABEL [LABEL ...]] [HASH [HASH ...]]

Deleting certificate and keys.

force: Force removal of without any questions
LABEL: Label(s) of the PKI artifact to be removed.
HASH: Subject hash of a certificate to be removed.

Examples

Import a PKCS#12 or a PEM certificate

example:/#> pki import pkcs password "secret string" ftp://1.2.3.4/bundle.p12
example:/#> pki import pem type public usb://remote.crt

Import an OpenVPN static key (PSK or TLS-AUTH)

example:/#> pki import ovpn ftp://1.2.3.4/ovpn.key

Generate an OpenVPN static key (PSK or TLS-AUTH)

example:/#> pki generate ovpn label NAME

Show all certificates or display a given label/hash

example:/#> pki cert show
TYPE     HASH     EXPIRES     NAME                 DIST LABEL
Pub      52ff4f77 Jan 19 2038 lynx-12-34-50.local       web-default

example:/#> pki cert show full
TYPE     HASH     EXPIRES     NAME                 DIST LABEL
CA-local fa27d441 Sep  5 2034 OpenXPKI Root~240902 SCEP enroll2+ca
Pub      52ff4f77 Jan 19 2038 lynx-12-34-50.local       web-default
Key      N/A      N/A         web-default               web-default

example:/#> pki cert show all
Press Ctrl-C or Q(uit) to quit viewer, Space for next page,  for next line.
TYPE     HASH     EXPIRES     NAME                 DIST LABEL
CA-auto  a94d09e5 Dec 31 2030 ACCVRAIZ1                 ACCVRAIZ1
CA-auto  cd8c0d63 Jan  1 2030 N/A                       AC_RAIZ_FNMT-RCM
CA-auto  b81b93f0 Dec 20 2043 AC RAIZ FNMT-~EGUROS      AC_RAIZ_FNMT-RCM_SERVIDORES_SEGUROS
CA-auto  b433981b Aug 30 2039 ANF Secure Se~oot CA      ANF_Secure_Server_Root_CA
CA-auto  930ac5d2 Sep 22 2030 Actalis Authe~oot CA      Actalis_Authentication_Root_CA
CA-auto  2b349938 Dec 31 2030 AffirmTrust C~ercial      AffirmTrust_Commercial
CA-auto  93bc0acc Dec 31 2030 AffirmTrust N~orking      AffirmTrust_Networking
CA-auto  b727005e Dec 31 2040 AffirmTrust Premium       AffirmTrust_Premium
CA-auto  9c8dfbd4 Dec 31 2040 AffirmTrust P~um ECC      AffirmTrust_Premium_ECC
CA-auto  ce5e74ef Jan 17 2038 Amazon Root CA 1          Amazon_Root_CA_1
CA-auto  6d41d539 May 26 2040 Amazon Root CA 2          Amazon_Root_CA_2
CA-auto  8cb5ee0f May 26 2040 Amazon Root CA 3          Amazon_Root_CA_3
--More-- (17% of 10619 bytes)

Remove certificate and key by label/hash

Removing of certificates and keys is done from the pki exec context:

example:/#> pki cert show full
TYPE     HASH     EXPIRES     NAME                 DIST LABEL
Pub      52ff4f77 Jan 19 2038 lynx-12-34-50.local       web-default
Key      N/A      N/A         web-default               web-default
example:/#> pki remove web-default
Remove certificate 'web-default', are you sure (y/N)? y
Removing certificate 'web-default'
Remove private key 'web-default', are you sure (y/N)? y
Removing private key 'web-default'

Use force parameter to avoid questions:

example:/#> pki cert remove force [...]

To remove all PKI artifacts

example:/#> pki remove
Remove ALL PKI artifacts, are you REALLY sure (y/N)?