SKCA Agent · Apache/proxy · targets.d

SKCA Agent

Агент устанавливается на Apache/proxy серверы, синхронизирует внутренние сертификаты, Let's Encrypt сертификаты, CA bundle и CRL без публикации секретов на публичной странице.

Что делает агент

Internal certificates

Генерирует локальный key/CSR, получает cert, chain и fullchain из SKCA и обновляет Apache.

Let's Encrypt

Запрашивает выпуск или продление через SKCA API и доставляет cert/key/chain/fullchain на публичные vhost.

Trust bundle / CRL

Синхронизирует CA bundle и CRL для client certificate authentication.

Быстрая установка Linux

Команды создают каталоги агента, скачивают бинарник и базовый конфиг. Реальные client credentials выдаёт администратор.

Linux

curl -fsS https://<ca-host>/agent/download/linux-amd64 -o /usr/local/bin/skca-agent
chmod 0755 /usr/local/bin/skca-agent
install -d -m 0750 /etc/skca-agent/targets.d
install -d -m 0750 /var/lib/skca-agent
install -d -m 0750 /run/skca-agent
curl -fsS https://<ca-host>/agent/configs/base.env -o /etc/skca-agent/skca-agent.env
systemctl enable --now skca-agent.service

Примеры конфигурации

Base service configbase.env

Base daemon config. It defines the SKCA URL, client identity, token placeholder, polling, state directories, unix socket, and reload command.

base.env

download

SKCA_AGENT_SERVER_URL=https://skca.example.internal:8444
SKCA_AGENT_CLIENT_ID=change-me
SKCA_AGENT_TOKEN=change-me
SKCA_AGENT_MODE=service
SKCA_AGENT_POLL_INTERVAL=1h
SKCA_AGENT_TARGETS_DIR=/etc/skca-agent/targets.d
SKCA_AGENT_STATE_DIR=/var/lib/skca-agent
SKCA_AGENT_RUN_DIR=/run/skca-agent
SKCA_AGENT_SOCKET=/run/skca-agent/skca-agent.sock
SKCA_AGENT_RELOAD_COMMAND=/usr/bin/systemctl reload httpd
SKCA_AGENT_INSECURE_SKIP_VERIFY=false
SKCA_AGENT_LOG_LEVEL=info

Parameter	Required	Example	Default
`SKCA_AGENT_SERVER_URL`	required	`https://skca.example.internal:8444`	none
`SKCA_AGENT_CLIENT_ID`	required	`change-me`	none
`SKCA_AGENT_TOKEN`	required	`change-me or {{CLIENT_TOKEN}}`	none
`SKCA_AGENT_TARGETS_DIR`	required	`/etc/skca-agent/targets.d`	/etc/skca-agent/targets.d
`SKCA_AGENT_SOCKET`	optional	`/run/skca-agent/skca-agent.sock`	/run/skca-agent/skca-agent.sock
`SKCA_AGENT_RELOAD_COMMAND`	optional	`/usr/bin/systemctl reload httpd`	empty

Internal certificate targetinternal-certificate.env

Issues an internal certificate through a CSR. The private key is generated and kept on the agent host; SKCA returns cert.pem, chain.pem, and fullchain.pem.

internal-certificate.env

download

SKCA_AGENT_TARGET_TYPE=internal-certificate
SKCA_AGENT_TARGET_NAME=internal-hq
SKCA_AGENT_ENABLED=true
SKCA_AGENT_POLICY_ID=change-me
SKCA_AGENT_CERT_NAME=internal-hq
SKCA_AGENT_COMMON_NAME=service.hq.example.internal
SKCA_AGENT_DNS_SANS=service.hq.example.internal
SKCA_AGENT_KEY_TYPE=rsa
SKCA_AGENT_KEY_BITS=2048
SKCA_AGENT_CERT_DIR=/etc/pki/skca/internal
SKCA_AGENT_KEY_PATH=/etc/pki/skca/internal/privkey.pem
SKCA_AGENT_CSR_PATH=/etc/pki/skca/internal/request.csr
SKCA_AGENT_CERT_PATH=/etc/pki/skca/internal/cert.pem
SKCA_AGENT_CHAIN_PATH=/etc/pki/skca/internal/chain.pem
SKCA_AGENT_FULLCHAIN_PATH=/etc/pki/skca/internal/fullchain.pem
SKCA_AGENT_RENEW_BEFORE_DAYS=21
SKCA_AGENT_RELOAD_AFTER_UPDATE=true

Parameter	Required	Example	Default
`SKCA_AGENT_POLICY_ID`	required	`change-me`	none
`SKCA_AGENT_COMMON_NAME`	required	`service.hq.example.internal`	none
`SKCA_AGENT_DNS_SANS`	optional	`site1.example,site2.example`	Common Name only
`SKCA_AGENT_KEY_PATH`	required	`/etc/pki/skca/internal/privkey.pem`	none
`SKCA_AGENT_CERT_PATH`	required	`/etc/pki/skca/internal/cert.pem`	none
`SKCA_AGENT_CHAIN_PATH`	recommended	`/etc/pki/skca/internal/chain.pem`	empty
`SKCA_AGENT_FULLCHAIN_PATH`	recommended	`/etc/pki/skca/internal/fullchain.pem`	empty

Let's Encrypt targetletsencrypt-certificate.env

Requests or renews a public Let's Encrypt certificate through SKCA. The agent never talks to Let's Encrypt directly; SKCA checks policy, runs ACME, and returns cert/key/chain/fullchain material.

letsencrypt-certificate.env

download

SKCA_AGENT_TARGET_TYPE=letsencrypt-certificate
SKCA_AGENT_TARGET_NAME=public-site
SKCA_AGENT_ENABLED=true
SKCA_AGENT_LE_DOMAIN=www.example.com
SKCA_AGENT_LE_ENVIRONMENT=production
SKCA_AGENT_CERT_PATH=/etc/pki/skca/letsencrypt/cert.pem
SKCA_AGENT_CHAIN_PATH=/etc/pki/skca/letsencrypt/chain.pem
SKCA_AGENT_FULLCHAIN_PATH=/etc/pki/skca/letsencrypt/fullchain.pem
SKCA_AGENT_KEY_PATH=/etc/pki/skca/letsencrypt/privkey.pem
SKCA_AGENT_RELOAD_AFTER_UPDATE=true

Parameter	Required	Example	Default
`SKCA_AGENT_LE_DOMAIN`	required	`www.example.com`	SKCA_AGENT_DOMAIN fallback
`SKCA_AGENT_DNS_SANS`	optional	`www.example.com`	domain only
`SKCA_AGENT_LE_ENVIRONMENT`	optional	`production`	production
`SKCA_AGENT_LE_CHALLENGE_TYPE`	optional	`http-01`	http-01
`SKCA_AGENT_CERT_PATH`	required	`/etc/pki/skca/le/www.example.com/cert.pem`	none
`SKCA_AGENT_CHAIN_PATH`	required	`/etc/pki/skca/le/www.example.com/chain.pem`	none
`SKCA_AGENT_FULLCHAIN_PATH`	required	`/etc/pki/skca/le/www.example.com/fullchain.pem`	none
`SKCA_AGENT_KEY_PATH`	required	`/etc/pki/skca/le/www.example.com/privkey.pem`	none

Trust bundle targettrust-bundle.env

Downloads CA bundle and generated CRL for Apache client certificate authentication.

trust-bundle.env

download

SKCA_AGENT_TARGET_TYPE=trust-bundle
SKCA_AGENT_TARGET_NAME=hq-client-auth
SKCA_AGENT_ENABLED=true
SKCA_AGENT_CA_BUNDLE_NAME=hq-client-auth
SKCA_AGENT_CRL_NAME=hq-client-auth
SKCA_AGENT_CA_BUNDLE_PATH=/etc/pki/skca/trust/hq-client-ca-bundle.pem
SKCA_AGENT_CRL_PATH=/etc/pki/skca/crl/hq-client-ca.crl
SKCA_AGENT_RELOAD_AFTER_UPDATE=true

Parameter	Required	Example	Default
`SKCA_AGENT_CA_BUNDLE_NAME`	one of bundle/crl	`hq-client-auth`	empty
`SKCA_AGENT_CRL_NAME`	one of bundle/crl	`hq-client-auth`	empty
`SKCA_AGENT_CA_BUNDLE_PATH`	required when bundle name is set	`/etc/pki/skca/trust/hq-client-ca-bundle.pem`	empty
`SKCA_AGENT_CRL_PATH`	required when CRL name is set	`/etc/pki/skca/crl/hq-client-ca.crl`	empty

Many domains SAN targetmany-domains.env

Issues one internal certificate for many hostnames by listing every DNS SAN explicitly. Use several target files when services have different owners or reload boundaries.

many-domains.env

download

SKCA_AGENT_TARGET_TYPE=internal-certificate
SKCA_AGENT_TARGET_NAME=internal-many-domains
SKCA_AGENT_ENABLED=true
SKCA_AGENT_POLICY_ID=change-me
SKCA_AGENT_CERT_NAME=internal-many-domains
SKCA_AGENT_COMMON_NAME=site01.hq.skpc.ru
SKCA_AGENT_DNS_SANS=site01.hq.skpc.ru,site02.hq.skpc.ru,site03.hq.skpc.ru,site04.hq.skpc.ru,site05.hq.skpc.ru,site06.hq.skpc.ru,site07.hq.skpc.ru,site08.hq.skpc.ru,site09.hq.skpc.ru,site10.hq.skpc.ru,site11.hq.skpc.ru,site12.hq.skpc.ru,site13.hq.skpc.ru,site14.hq.skpc.ru,site15.hq.skpc.ru
SKCA_AGENT_KEY_PATH=/etc/pki/skca/internal/many-domains/privkey.pem
SKCA_AGENT_CSR_PATH=/etc/pki/skca/internal/many-domains/request.csr
SKCA_AGENT_CERT_PATH=/etc/pki/skca/internal/many-domains/cert.pem
SKCA_AGENT_CHAIN_PATH=/etc/pki/skca/internal/many-domains/chain.pem
SKCA_AGENT_FULLCHAIN_PATH=/etc/pki/skca/internal/many-domains/fullchain.pem
SKCA_AGENT_RENEW_BEFORE_DAYS=30
SKCA_AGENT_RELOAD_AFTER_UPDATE=true

Parameter	Required	Example	Default
`SKCA_AGENT_COMMON_NAME`	required	`site01.hq.skpc.ru`	none
`SKCA_AGENT_DNS_SANS`	required	`site01.hq.skpc.ru,site02.hq.skpc.ru`	none
`SKCA_AGENT_POLICY_ID`	required	`change-me`	none
`SKCA_AGENT_RELOAD_AFTER_UPDATE`	optional	`true`	false

Сертификат на 15 доменов без wildcard

Используйте DNS SAN через запятую: CN остаётся основным доменом, а все SAN должны быть разрешены политикой выпуска. Если домены относятся к разным сервисам или требуют разных reload-команд, лучше завести несколько target-файлов.

SKCA_AGENT_COMMON_NAME = основной домен.
SKCA_AGENT_DNS_SANS = все имена через запятую.
Wildcard используйте только если это явно разрешено политикой и границей сервиса.

Apache examples

Internal HTTPS vhost

SSLCertificateFile /etc/pki/skca/internal/fullchain.pem
SSLCertificateKeyFile /etc/pki/skca/internal/privkey.pem

Public LE vhost

SSLCertificateFile /etc/pki/skca/le/www.example.com/fullchain.pem
SSLCertificateKeyFile /etc/pki/skca/le/www.example.com/privkey.pem

Client certificate auth with CRL

SSLCACertificateFile /etc/pki/skca/trust/hq-client-ca-bundle.pem
SSLCARevocationFile /etc/pki/skca/crl/hq-client-ca.crl
SSLVerifyClient require