PKI (Public Key Infrastructure)

PKI (Public Key Infrastructure) in VyOS is a centralized system for managing certificates, keys, and Certificate Authorities (CA). VyOS provides built-in tools for generating, storing, and managing the cryptographic material used in VPN, HTTPS, and other secure services.

Overview

PKI in VyOS is used for:

VPN authentication: IPsec, OpenVPN with certificates instead of PSK
HTTPS services: Secure web interface and REST API
Mutual authentication: mTLS for critical services
Centralized management: Your own CA for internal infrastructure
Certificate-based SSH: SSH authentication with certificates

PKI components

Component	Description	Use
CA (Certificate Authority)	Certificate authority	Signing certificates
Certificate	X.509 certificate	Identifying a device/service
Private Key	Private key	Encryption and signing
Certificate Request (CSR)	Certificate request	Obtaining a certificate from a CA
CRL (Certificate Revocation List)	List of revoked certificates	Validity checking

Typical workflow

Create a CA (root or intermediate)
Generate a private key for a service/device
Create a CSR (Certificate Signing Request)
Sign the CSR with your own CA or an external one
Install the certificate in VyOS
Configure services to use the certificate

Basic configuration

Creating your own CA

# Generate the private key for the CA
generate pki ca install ca-internal

# CA parameters (interactive):
# Country: RU
# State: Moscow
# Locality: Moscow
# Organization: My Company
# Common Name: My Company Root CA

# Check the created CA
show pki ca ca-internal

commit
save

Generating a server certificate

# Generate the private key and certificate
generate pki certificate sign ca-internal install vyos-server

# Parameters:
# Common Name: vyos.example.com
# Subject Alternative Names (optional): DNS:vyos.example.com,IP:192.168.1.1

# Check
show pki certificate vyos-server

commit
save

Importing an existing certificate

# Import a certificate from a file
generate pki certificate import vyos-cert certificate-file /tmp/certificate.pem

# Import a private key
generate pki key-pair import vyos-key private-key-file /tmp/private-key.pem

commit
save

Using Let’s Encrypt

# Import a Let's Encrypt certificate
generate pki certificate import letsencrypt-vyos \
  certificate-file /etc/letsencrypt/live/vyos.example.com/fullchain.pem \
  private-key-file /etc/letsencrypt/live/vyos.example.com/privkey.pem

# Configure HTTPS with Let's Encrypt
set service https certificates certificate letsencrypt-vyos

commit
save

Advanced configuration

Building a CA hierarchy (Root + Intermediate)

Root CA:

# Create the Root CA (offline, keep in a secure location)
generate pki ca install root-ca

# Parameters:
# Common Name: My Company Root CA
# Key size: 4096
# Validity: 3650 days (10 years)

commit
save

Intermediate CA:

# Create the Intermediate CA
generate pki ca sign root-ca install intermediate-ca

# Parameters:
# Common Name: My Company Intermediate CA
# Key size: 2048
# Validity: 1825 days (5 years)

commit
save

Signing certificates with the Intermediate CA:

# Certificates are signed by the intermediate CA
generate pki certificate sign intermediate-ca install server-cert

commit
save

Generating a certificate with SAN (Subject Alternative Names)

# Certificate with multiple names
generate pki certificate sign ca-internal install multi-san-cert

# When prompted for SAN, specify:
# DNS:vyos.example.com,DNS:router.example.com,IP:192.168.1.1,IP:10.0.0.1

commit
save

Wildcard certificate

# Wildcard certificate for a subdomain
generate pki certificate sign ca-internal install wildcard-cert

# Common Name: *.example.com
# Allows use for any subdomain: router.example.com, vpn.example.com, etc.

commit
save

Client certificates for VPN

# Certificate for a VPN client
generate pki certificate sign ca-internal install client-alice

# Parameters:
# Common Name: alice@example.com
# Extended Key Usage: clientAuth

# Export to hand off to the client
show pki certificate client-alice pem

commit
save

Certificate Revocation List (CRL)

# Create a CRL for the CA
generate pki crl ca-internal install crl-internal

# Revoke a certificate
set pki ca ca-internal crl revoke client-alice

# Update the CRL
generate pki crl ca-internal regenerate

commit
save

Configuring validity periods

# Generate with a custom validity period (365 days)
generate pki certificate sign ca-internal install short-term-cert valid-days 365

commit
save

Configuration examples

Example 1: IPsec VPN with certificates

# Create a CA
generate pki ca install vpn-ca

# Certificate for the local router
generate pki certificate sign vpn-ca install vyos-site-a

# Certificate for the remote router (to be exported)
generate pki certificate sign vpn-ca install vyos-site-b

# IPsec configuration with certificates
set vpn ipsec authentication psk-secret 'fallback-psk'
set vpn ipsec esp-group ESP-VPN proposal 1 encryption aes256
set vpn ipsec esp-group ESP-VPN proposal 1 hash sha256

set vpn ipsec ike-group IKE-VPN key-exchange ikev2
set vpn ipsec ike-group IKE-VPN proposal 1 encryption aes256
set vpn ipsec ike-group IKE-VPN proposal 1 hash sha256

# Site-to-Site with certificates
set vpn ipsec site-to-site peer site-b authentication mode x509
set vpn ipsec site-to-site peer site-b authentication x509 ca-certificate vpn-ca
set vpn ipsec site-to-site peer site-b authentication x509 certificate vyos-site-a
set vpn ipsec site-to-site peer site-b ike-group IKE-VPN
set vpn ipsec site-to-site peer site-b local-address 203.0.113.1
set vpn ipsec site-to-site peer site-b remote-address 198.51.100.1
set vpn ipsec site-to-site peer site-b tunnel 0 esp-group ESP-VPN
set vpn ipsec site-to-site peer site-b tunnel 0 local prefix 192.168.1.0/24
set vpn ipsec site-to-site peer site-b tunnel 0 remote prefix 192.168.2.0/24

commit
save

Example 2: OpenVPN with a CA and client certificates

# Create a CA for OpenVPN
generate pki ca install openvpn-ca

# Server certificate
generate pki certificate sign openvpn-ca install openvpn-server

# Client certificates
generate pki certificate sign openvpn-ca install client-user1
generate pki certificate sign openvpn-ca install client-user2

# DH parameters
generate pki dh install dh-2048 bits 2048

# OpenVPN server configuration
set interfaces openvpn vtun10 mode server
set interfaces openvpn vtun10 server subnet 10.8.0.0/24
set interfaces openvpn vtun10 tls ca-certificate openvpn-ca
set interfaces openvpn vtun10 tls certificate openvpn-server
set interfaces openvpn vtun10 tls dh-params dh-2048

commit
save

# Export the client certificate for the user
show pki ca openvpn-ca pem
show pki certificate client-user1 pem
show pki certificate client-user1 private key

Example 3: HTTPS with your own CA

# Create a CA
generate pki ca install web-ca

# Certificate for the web interface with SAN
generate pki certificate sign web-ca install web-server

# When creating it, specify the SAN:
# DNS:vyos.example.com,IP:192.168.1.1

# Configure HTTPS
set service https certificates certificate web-server

# Restart HTTPS service
restart https

commit
save

Example 4: Enterprise PKI with a hierarchy

# Root CA (created once, stored offline)
generate pki ca install company-root-ca
# CN: Company Name Root CA
# Validity: 7300 days (20 years)

# Intermediate CA for servers
generate pki ca sign company-root-ca install servers-ca
# CN: Company Name Servers CA
# Validity: 3650 days (10 years)

# Intermediate CA for clients
generate pki ca sign company-root-ca install clients-ca
# CN: Company Name Clients CA
# Validity: 3650 days (10 years)

# Server certificates are signed by servers-ca
generate pki certificate sign servers-ca install web-server
generate pki certificate sign servers-ca install vpn-server

# Client certificates are signed by clients-ca
generate pki certificate sign clients-ca install client-alice
generate pki certificate sign clients-ca install client-bob

commit
save

Example 5: Let’s Encrypt with auto-renewal

# Install certbot (on VyOS)
sudo apt-get update
sudo apt-get install certbot

# Obtain the certificate (HTTP-01 challenge)
sudo certbot certonly --standalone \
  --preferred-challenges http \
  --email admin@example.com \
  --agree-tos \
  -d vyos.example.com

# Import into VyOS
generate pki certificate import letsencrypt-vyos \
  certificate-file /etc/letsencrypt/live/vyos.example.com/fullchain.pem \
  private-key-file /etc/letsencrypt/live/vyos.example.com/privkey.pem

# Configure HTTPS
set service https certificates certificate letsencrypt-vyos

commit
save

Auto-renewal script /config/scripts/renew-letsencrypt.sh:

#!/bin/bash

# Renew the certificate
sudo certbot renew --quiet

# Check the renewal
if [ $? -eq 0 ]; then
    # Re-import into VyOS
    /usr/libexec/vyos/op_mode/pki.py import certificate \
      letsencrypt-vyos \
      /etc/letsencrypt/live/vyos.example.com/fullchain.pem \
      /etc/letsencrypt/live/vyos.example.com/privkey.pem

    # Restart HTTPS
    sudo systemctl restart vyos-http-api-server

    logger -t letsencrypt "Certificate renewed successfully"
else
    logger -t letsencrypt -p user.err "Certificate renewal failed"
fi

Task Scheduler for auto-renewal:

set system task-scheduler task renew-letsencrypt interval '0 3 * * *'
set system task-scheduler task renew-letsencrypt executable path '/config/scripts/renew-letsencrypt.sh'

Example 6: Wildcard certificate for multiple services

# Create a CA
generate pki ca install internal-ca

# Wildcard certificate
generate pki certificate sign internal-ca install wildcard-example-com
# CN: *.example.com

# Use it for various services
# HTTPS
set service https certificates certificate wildcard-example-com

# OpenVPN
set interfaces openvpn vtun0 tls certificate wildcard-example-com

commit
save

Monitoring and diagnostics

Viewing certificates and CAs

# Show all CAs
show pki ca

# Details of a specific CA
show pki ca ca-internal

# Export a CA to PEM
show pki ca ca-internal pem

# Show all certificates
show pki certificate

# Details of a specific certificate
show pki certificate vyos-server

# Export a certificate
show pki certificate vyos-server pem

# Export a private key
show pki certificate vyos-server private key

Checking the validity period

# Check the certificate
show pki certificate vyos-server

# The output includes:
# - Issuer (who issued it)
# - Subject (who it was issued to)
# - Valid From / Valid To (validity period)
# - Subject Alternative Names

Verifying the certificate chain

# Verify that the certificate was signed by the correct CA
show pki certificate vyos-server

# Verify with openssl (in the shell)
openssl verify -CAfile ca.pem certificate.pem

Testing HTTPS with a certificate

# From the client
curl -k https://192.168.1.1/
curl --cacert ca.crt https://vyos.example.com/

# Check certificate details
openssl s_client -connect vyos.example.com:443 -showcerts

Checking IPsec with certificates

# Check the configuration
show vpn ipsec sa

# IPsec logs
show log vpn ipsec

# Certificate details in IPsec
sudo swanctl --list-certs

Monitoring certificate expiration

Script /config/scripts/check-cert-expiry.sh:

#!/bin/bash

ALERT_DAYS=30
CERTS="vyos-server openvpn-server"

for cert in $CERTS; do
    # Get the expiration date
    EXPIRY=$(cli-shell-api showConfig pki certificate $cert | grep "Valid To" | awk '{print $3}')

    # Convert and check (simplified)
    # In production, use full-featured date parsing

    # If close to expiration, send an alert
    # echo "Certificate $cert expires on $EXPIRY" | mail -s "Cert Expiry Alert" admin@example.com

    logger -t cert-monitor "Checked certificate $cert"
done

Task Scheduler:

set system task-scheduler task cert-monitor interval '0 0 * * *'
set system task-scheduler task cert-monitor executable path '/config/scripts/check-cert-expiry.sh'

Troubleshooting

Problem: The certificate does not validate

Diagnostics:

# Check the certificate
show pki certificate vyos-server

# Check the CA
show pki ca ca-internal

# Check with openssl
openssl x509 -in certificate.pem -text -noout
openssl verify -CAfile ca.pem certificate.pem

Solution:

# Make sure the certificate was signed by the correct CA
# Check the chain: Certificate -> Intermediate CA -> Root CA

# Re-sign if necessary
generate pki certificate sign ca-internal install vyos-server

commit
save

Problem: IPsec does not work with certificates

Diagnostics:

# Check the configuration
show configuration vpn ipsec

# Logs
show log vpn ipsec | match certificate

# Details
sudo swanctl --list-certs
sudo ipsec statusall

Solution:

# Make sure the CA and certificate are configured
show pki ca vpn-ca
show pki certificate vyos-site-a

# Check the IPsec configuration
set vpn ipsec site-to-site peer site-b authentication mode x509
set vpn ipsec site-to-site peer site-b authentication x509 ca-certificate vpn-ca
set vpn ipsec site-to-site peer site-b authentication x509 certificate vyos-site-a

commit
save

# Restart IPsec
restart ipsec

Problem: HTTPS does not use the new certificate

Solution:

# Check the configuration
show configuration service https certificates

# Set the certificate
set service https certificates certificate new-cert

commit
save

# Restart HTTPS
restart https

Problem: The certificate has expired

Solution:

# Generate a new certificate
generate pki certificate sign ca-internal install vyos-server-new

# Update the service configuration
set service https certificates certificate vyos-server-new

# Delete the old one
delete pki certificate vyos-server

commit
save

Problem: The private key is corrupted

Solution:

# Create a new key-certificate pair
generate pki certificate sign ca-internal install new-cert

# Update all references to the old certificate

commit
save

Problem: The CA is not trusted by clients

Solution:

Export the CA and install it on the client systems:

# On VyOS
show pki ca ca-internal pem > company-ca.crt

# On a Linux client
sudo cp company-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# On Windows
# Import via certmgr.msc into "Trusted Root Certification Authorities"

# On macOS
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain company-ca.crt

Best practices

1. CA hierarchy

Use a Root + Intermediate CA:

# Root CA - offline, long validity period
# Intermediate CA - online, signs certificates

2. Validity periods

Reasonable periods:

# Root CA: 10-20 years
# Intermediate CA: 5-10 years
# Server certificates: 1-3 years
# Client certificates: 1-2 years

3. Key sizes

# CA: 4096 bits
# Server certificates: 2048 bits (balance of security/performance)
# Client certificates: 2048 bits

4. Subject Alternative Names

Always use SAN for compatibility:

# CN: vyos.example.com
# SAN: DNS:vyos.example.com,DNS:router.example.com,IP:192.168.1.1

5. Protecting private keys

# Restrict access to the configuration
sudo chmod 600 /config/config.boot

# Keep the Root CA offline
# Use a passphrase for critical keys (outside VyOS)

6. Certificate Revocation

Configure a CRL for revocation:

set pki ca ca-internal crl revoke compromised-cert
generate pki crl ca-internal regenerate

7. Expiration monitoring

Set up automatic checks:

set system task-scheduler task cert-monitor interval '0 0 * * *'

8. Documentation

Document all certificates:

# /config/pki-inventory.txt
# vyos-server: CN=vyos.example.com, Expires: 2026-10-14, Used by: HTTPS
# openvpn-server: CN=vpn.example.com, Expires: 2026-10-14, Used by: OpenVPN

9. Backups

Back up the PKI:

# Backup of all certificates and keys
show pki ca > /config/backup/pki-ca-backup.txt
show pki certificate > /config/backup/pki-cert-backup.txt

# Regular configuration backups
/opt/vyatta/sbin/vyatta-save-config.pl /config/backup/config.boot.$(date +%Y%m%d)

10. Testing before production

Test certificates before deployment:

# Validity check
openssl verify -CAfile ca.pem certificate.pem

# Validity period check
openssl x509 -in certificate.pem -noout -dates

# SAN check
openssl x509 -in certificate.pem -noout -text | grep "Subject Alternative Name" -A1

Useful commands

# Show all CAs
show pki ca

# Show all certificates
show pki certificate

# CA details
show pki ca ca-internal

# Certificate details
show pki certificate vyos-server

# Export a CA to PEM
show pki ca ca-internal pem

# Export a certificate
show pki certificate vyos-server pem

# Export a private key
show pki certificate vyos-server private key

# Generate a CA
generate pki ca install new-ca

# Generate a certificate
generate pki certificate sign ca-internal install new-cert

# Import a certificate
generate pki certificate import cert-name certificate-file /path/to/cert.pem

# Import a key
generate pki key-pair import key-name private-key-file /path/to/key.pem

# Configuration
show configuration pki

# OpenSSL commands for verification
openssl x509 -in cert.pem -text -noout
openssl verify -CAfile ca.pem cert.pem
openssl s_client -connect host:443 -showcerts

Integration with other features

PKI + IPsec VPN

set vpn ipsec site-to-site peer site-b authentication mode x509
set vpn ipsec site-to-site peer site-b authentication x509 ca-certificate vpn-ca
set vpn ipsec site-to-site peer site-b authentication x509 certificate site-a-cert

PKI + OpenVPN

set interfaces openvpn vtun0 tls ca-certificate openvpn-ca
set interfaces openvpn vtun0 tls certificate server-cert
set interfaces openvpn vtun0 tls dh-params dh-2048

PKI + HTTPS

set service https certificates certificate web-cert

PKI + SSH (certificates)

# Using an SSH CA for authentication (advanced setup)
# Requires additional OpenSSH configuration

Conclusion

PKI (Public Key Infrastructure) in VyOS provides centralized certificate management for all secure services. The built-in tools let you create your own CAs, generate certificates, manage their lifecycle, and integrate with external PKI systems.

Key benefits of PKI in VyOS:

Centralized certificate management
Your own CA for internal infrastructure
Support for a CA hierarchy (Root + Intermediate)
Integration with VPN (IPsec, OpenVPN)
Let’s Encrypt support
Certificate Revocation Lists (CRL)

Recommendations for production:

Use a CA hierarchy (Root offline + Intermediate online)
Apply reasonable validity periods
Use SAN for all certificates
Protect private keys
Set up expiration monitoring
Document all certificates
Create backups regularly
Test before production
Use a CRL to revoke compromised certificates

PKI in VyOS delivers enterprise-grade certificate management for building secure infrastructure with certificate-based authentication, eliminating the need for PSK (Pre-Shared Keys) and providing centralized control over cryptographic material.

Reviewed by OpenNix LLC · Last updated on 29 July 2026

NAT (Network Address Translation)VyOS Operation Mode