keyvault-certdeploy is a tool used to facilitate X.509 certificate deployment to Linux systems with Azure Key Vault, supporting RSA and ECDSA certificates, local deployment and update hooks. Originally built to work around shortcomings in the Azure certificiate provisioning via VM secrets, it's possible to provision systems outside of Azure as well, provided they have access to the corresponding vault. It can be used to push certificates to Key Vault from a Let's Encrypt deployment hook and to refresh VM certificates on boot or to periodically poll for updates via cronjob.
- Azure Key Vault vault and an account with write permissions to vault secrets (for uploading new certs) and a read-only secret permissions for fetching certs.
- Go >=1.19 and goreleaser for building.
To support importing ECC keys and ECDSA certificates, it does not use Key Vault's internal mechanism for key and certificate management and stores key and certificate in a single PEM-encoded secret. Thus, it cannot be used with HSM-backed keys or Key Vault's automatic certificate renewal.
keyvault-certdeploy uses the automatic environment authentication from the Azure Golang SDK to authenticate itself to Key Vault. Credentials can be either provided through environment variables or, if running in a Azure VM, through Managed Service Identity (MSI). No environment variables need to be set when using MSI.
Required access policies to vault:
- To push certificates: Secret Get & Set
- To fetch (dump & sync) certificates: Secret Get
- To list certificates: Secret Get & List
- To delete certificates (delete & prune): Secret Delete, Get & List
Either download a compiled release, use the emgag/keyvault-certdeploy docker image or see build instructions in this README.
Also checkout example ansible role for deploying keyvault-certdeploy and individual certificates or the systemd unit files for running keyvault-certdeploy as an onboot- and/or periodic service.
See keyvault-certdeploy.yml.dist for a sample configuration.
X.509-Certificate deployment helper for Azure Key Vault
Usage:
keyvault-certdeploy [command]
Available Commands:
delete Deletes certificate from vault
dump Dump certificate and key from vault to current directory or dir, if supplied
help Help about any command
list List certificates in vault
prune Remove expired certificates from vault
push Push a certificate to the vault
sync Sync configured certificates from vault to system
Flags:
-c, --config string Config file (default locations are $HOME/.config/keyvault-certdeploy.yml, /etc/keyvault-certdeploy/keyvault-certdeploy.yml, $PWD/keyvault-certdeploy.yml)
-h, --help help for keyvault-certdeploy
-q, --quiet Be quiet
-v, --verbose Be more verbose
--version version for keyvault-certdeploy
Use "keyvault-certdeploy [command] --help" for more information about a command.
Deletes certificate from vault
Usage:
keyvault-certdeploy delete <subject> <keyalgo> [flags]
Flags:
-h, --help help for delete
-y, --yes Don't confirm before deleting
This command removes a single certificate from vault.
Dump certificate and key from vault to current directory or dir, if supplied
Usage:
keyvault-certdeploy dump <subject> <keyalgo> [flags]
Flags:
--cert string Name of the leaf certificate file (default "cert.pem")
--chain string Name of the certificate chain file (default "chain.pem")
-d, --dir string Directory to save files to (default ".")
--fullchain string Name of the full certificate chain file (default "fullchain.pem")
--fullchainprivkey string Name of the full certificate chain + private key file (default "fullchain.privkey.pem")
-h, --help help for dump
--key string Name of the private key file (default "privkey.pem")
The files generated by this command follow the same convention as common Let's Encrypt utilities like certbot or dehydrated:
privkey.pem: the private key for the certificate.fullchain.pem: the certificate file containing all CA certificates as well as the leaf certificates. That's usually the one to use in TLS configurations of the services (e.g. in nginx'sssl_certificate)chain.pem: the CA certificates only, e.g. for OCSP stapling.cert.pem: just the leaf certificate.
See certbot's documentation about this for more info.
Additionally, following files will be generated as well:
fullchain.privkey.pem: the concatenation of fullchain and privkey.
List certificates in vault
Usage:
keyvault-certdeploy list [flags]
This command will list all certificates in configured vault.
Remove expired certificates from vault
Usage:
keyvault-certdeploy prune [flags]
Flags:
-d, --days int Delete certificates after this many days of being expired (default 7)
-h, --help help for prune
-n, --noop Just list expired certificates, don't actually remove the certs
-y, --yes Don't confirm before pruning
Automatically remove all certificates which expired -d days ago from vault.
Push a certificate to the vault
Usage:
keyvault-certdeploy push <privkey.pem> <fullchain.pem> [flags]
To push a certificate to the vault, the push command requires a key- and a certificates file. It's designed to work with the PEM files generated by Let's Encrypt utilities (privkey.pem & fullchain.pem).
Sync configured certificates from vault to system
Usage:
keyvault-certdeploy sync [flags]
Flags:
-f, --force Force update even if version on disk matches the one in vault
-h, --help help for sync
--nohooks Disable running hooks after cert update
This command will fetch all certificates configured in the certs list in the config file and run hooks if a certificate was updated. Hooks will only run once per sync run, after all certificates are processed. Duplicate hooks are ignored.
Certificates are pushed to the vault as an unencrypted, single PEM-formated file containing the ECC or RSA private key, the chain certificates and the leaf certificate. The secret is named SubjectCN-PublicKeyAlgo (all lowercase, e.g. example.org-rsa), its content type is set to application/x-pem-file and following tags are defined:
- fingerprint: SHA256 fingerprint (hex-encoded string)
- keyalgo: Either ECDSA or RSA
- notafter: UNIX timestamp of the certificate expire date
- subjectcn: The certificate's subject common name
$ git clone github.com/emgag/keyvault-certdeploy
$ cd keyvault-certdeploy
$ make snapshot
will download the source and build binary called keyvault-certdeploy in ./dist directory and a locally tagged docker image.
keyvault-certdeploy is licensed under the MIT License.