Certificate Management and Usage

This document presents the WeOS certificate repository, its usage and how to manage it.

What is the Certificate Repository?

The WeOS certificate repository holds cryptographic certificates and keys used by WeOS services utilising asymmetric and symmetric cryptography. An example is the WeOS Web server, which by default uses a unique, self-signed certificate for its HTTPS service.

It is possible to import your own certificates and associated private keys to be used for Web/HTTPS or for OpenVPN tunnels. OpenVPN certificates and secret keys may also be generated by WeOS.

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

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 implicitly at reboot.

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

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

Built-in trusted 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 utilises 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
...

Certificates & keys management

Certificates and keys can be managed from both CLI and Web interfaces.

CLI Syntax

pki [no] cert [show] [all] [full]: Manage certificates and keys.
no: Delete a complete certificate bundle by its label.
show: Dump certificate information: attributes & meta data. Options:

full - display local key’s and certificate’s
all - display all keys & certificates (including WeOS built-in)
HASH - display info about certificate with specified HASH
LABEL - display info about certificate with specified LABEL

pki [show] | [generate [OPTS] | import [OPTS] URI: Manage PKI.
generate: Generate certificates and OpenVPN secret keys (PSK). Signing, or self-signed CA not supported yet. Options:

ovpn - Generate OpenVPN secret key (PSK or TLS-AUTH).
label NAME - (Mandatory) Specify label name for the generated key.

import

Import PKCS12 certificate bundles, stand-alone PEM/DER or OpenVPN static key files. For PEM/DER, it is required to provide the type: private, public or CA. This to ensure the certificate is put to proper use.

Import format options:

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.

Other import options:
label NAME - (Optional) Specify label name for the imported certificate(s) and/or key.
password PASSWORD - Password for imported certificate/key (if encrypted).

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 zero-12-34-50.local       web-default

example:/#> pki cert show full
TYPE     HASH     EXPIRES     NAME                 DIST LABEL
Pub      52ff4f77 Jan 19 2038 zero-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 by label/hash

example:/#> pki cert remove

Use force parameter to avoid questions:

example:/#> pki cert remove force