step-ca + step-cli install info and other useful tips

[heinemannj]

Introduction

Public key encryption provides a secure method of transmitting data over insecure networks. It allows for secure communication by using a pair of keys:

• a public key for encryption and
• a private key for decryption.

TLS (Transport Layer Security) certificates, which are based on public key encryption, ensure the authenticity and integrity of data exchanged between a server and a client. They provide trust and verification, protecting against unauthorized access, data tampering, and eavesdropping, thus establishing secure and encrypted connections.

Smallstep step-ca and step-cli are Certificate Authority (CA) management tools for Windows, Linux, and macOS designed to simplify the process of creation, management, and revocation of certificates for use with TLS, mutual TLS (mTLS) authentication, document signing, and other X.509 authentication as well as SSH keys through a variety of provisioners.

See:

• https://smallstep.com/docs/step-ca/

step-ca init options

step-ca is built for robust certificate management in distributed systems. Running step-ca effectively in production requires some knowledge of its strengths and limitations.

When you initialize a two-tier CA, two private keys are generated:

• one intermediate private key, and
• one root private key.

It is very important that these private keys be kept secret.

• The intermediate key is used by the CA to sign certificates.
• The root key is not needed for day-to-day CA operation and should be stored offline.

A functional DNS infrastructure is required when provisioning TLS certificates for internal domains.

Certificates are created for a host's DNS name(s), which ACME uses to verify the client. You will have to adapt all below instructions to follow your own DNS structure.

See:

• https://smallstep.com/docs/step-cli/reference/ca/init/
• https://smallstep.com/docs/step-cli/reference/ca/provisioner/update/
• https://smallstep.com/docs/step-ca/certificate-authority-server-production/

Default settings

Option	Setting	Description
Deployment Type	standalone	An instance of step-ca that does not connect to any cloud services. You manage authority keys and configuration yourself.
SSH	true	Create keys to sign SSH certificates.
DNS names or IP addresses	FQDN=$(hostname -f) DomainName=$(hostname -d) IP=$(hostname -I)	These DNS names and IP addresses will be included in the CA certificates.
Listener Address	:443	This will bind to all IPs on port 443. If you proxy the app using Nginx or a load balancer, you can bind to the internal IP 127.0.0.1 and/or use another port.
PKI Name	MyHomePKI	The name of the new PKI. For larger deployments, you should make this name descriptive to distinguish between test, dev, and production environments.
Password File	/etc/step-ca/encryption/ca.pwd	Auto-generated strong password used by step-ca-service daemon.
Provisioner Password File	/etc/step-ca/encryption/provisioner.pwd	Auto-generated strong password used by PKI and ACME provisioners.
PKI Provisioner	pki@$DomainName	This is the equivalent of the superuser or root user of the PKI server.
ACME Provisioner	acme@$DomainName	Enable ACME Challenges.
X509MinDur	48h (2 days)	The minimum duration for an x509 certificate. Value must be a sequence of decimal numbers, each with optional fraction, and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
X509MaxDur	87600h (10 years)	The maximum duration for an x509 certificate. Value must be a sequence of decimal numbers, each with optional fraction, and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
X509DefaultDur	168h (7 days)	The default duration for an x509 certificate. Value must be a sequence of decimal numbers, each with optional fraction, and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

Above options can be partitually changed during the setup.

step-ca config files:

• /etc/step-ca/config/ca.json (main CA config file, containing all provisioner settings)
• /etc/step-ca/config/defaults.json (default configuration, containing the root fingerprint generated during step-ca init)

step-ca cert files:

• /etc/step-ca/certs/root_ca.crt
• /etc/step-ca/certs/intermediate_ca.crt

step-ca key files:

• /etc/step-ca/secrets/root_ca_key
• /etc/step-ca/secrets/intermediate_ca_key

See:

• https://smallstep.com/docs/step-ca/configuration/#basic-configuration-options

SystemD Service

systemctl status step-ca.service

systemd config file:

• /etc/systemd/system/step-ca.service

Trust your root CA

You’ll need to do this for every single computer which you use to access your sites, or you’ll get a certificate error. But once you add the root certificate, then you can continue to add homelab services without needing to individually trust each one on each user’s system.

Debian and others Linux OSs

wget --no-check-certificate https://{ca-host}.{DomainName}/roots.pem -O /usr/local/share/ca-certificates/{PKIName}_Root_CA.crt
update-ca-certificates

Windows workstation

• Download root and intermediate certificates
  https://{ca-host}.{DomainName}/roots.pem
https://{ca-host}.{DomainName}/1.0/intermediates.pem
• Copy to a network share and rename both
• Install the root CA by double click on the cert file
• Install on Local Computer
• Choose automatic selection and finish the import
• Same procedure for the Intermediate CA
• Reboot the workstation if necessary

step-ca URLs

• https://{ca-host}.{DomainName}/roots.pem
• https://{ca-host}.{DomainName}/1.0/intermediates.pem
• https://{ca-host}.{DomainName}/provisioners
• https://{ca-host}.{DomainName}/acme/acme@{DomainName}/directory

Useful commands

Cert db export

$STEPHOME/step-badger-x509Certs.sh
$STEPHOME/step-badger-sshCerts.sh

Cert inspect

step certificate inspect <cert-file>

See:

• ls -lisa $STEPHOME/certs/
• ls -lisa $STEPPATH/certs/

Cert request

$STEPHOME/step-ca-request.sh

Possible future improvement:

## Create a certificate to secure the www.example.com service and set the key type to RSA with a size of 4096 bits
step ca certificate www.example.com web-svc.crt web-svc.key --kty RSA --size 4096

Cert revocation

step ca revoke {serialnumber}

ACME client setup

PROXMOX VE LXCs

• Install step-cli Addon

PROXMOX VE Node

node > System > Certificates > ACME > Add Domain

node > System > Certificates > ACME > Add ACME Account
Account Name: acme
E-Mail: acme@{DomainName}
ACME Directory: Custom
URL: https://{ca-host}.{DomainName}/acme/acme@{DomainName}/directory
Query URL

Register

node > System > Certificates > ACME > Order Certificates Now

PROXMOX Backup Server

• In GUI Custom ACME Directory actually not implemented
• Use below shell commands

wget --no-check-certificate https://{ca-host}.{DomainName}/roots.pem -O /usr/local/share/ca-certificates/{PKIName}_Root_CA.crt
update-ca-certificates

proxmox-backup-manager acme account register default acme@{DomainName} --directory https://{ca-host}.{DomainName}/acme/acme@{DomainName}/directory

PROXMOX Datacenter Manager

• In GUI Custom ACME Directory actually not implemented
• In shell commands as well

See:
https://forum.proxmox.com/threads/cli-based-tool-to-handle-acme-requests.178263/
https://forum.proxmox.com/threads/pdm-acme-account-to-local-ca.177358/

References

step-ca

step-ca is a private certificate authority (X.509 & SSH) & ACME server for secure automated certificate management, so you can use TLS everywhere & SSO for SSH.

• https://smallstep.com/docs/step-ca/
• https://github.com/smallstep/certificates
• https://smallstep.com/docs/step-ca/acme-basics/
• https://smallstep.com/docs/step-cli/reference/ca/init/
• https://smallstep.com/docs/step-cli/reference/ca/provisioner/update/
• https://smallstep.com/docs/step-ca/certificate-authority-server-production/

step-cli

step-cli is an easy-to-use CLI tool for building, operating, and automating Public Key Infrastructure (PKI) systems and workflows.
It's also a client for the step-ca online Certificate Authority (CA) server.

• https://smallstep.com/docs/step-cli/
• https://github.com/smallstep/cli

step-badger

Exporting data out of the badger database of step-ca.

• https://github.com/lukasz-lobocki/step-badger