# vault-cert-deploy
Deploy SSL certificates from HashiCorp's Vault secret server
Script is able to deploy certificates from KV store of Vault
or when you use issue version of script it use PKI secret storage.
As auth method is used [Approle](https://www.vaultproject.io/docs/auth/approle.html "Vault Approle Doc"), you need role and secret id
deployed to server from different systems/locations. More
about this in usecase section.
On the first look, it may be little bit strange combination of
config file and cli options. You can combine them in different
ways to support various types of deployments to meet the basic
security concepts.
## Why do I need Vault Server ?
We are using Let's Encrypt for almost all of our SSL/TLS certificates.
We also have complex infrastructure so we have to retrieve
certificates in central place and then we distribute them into
datacenters, clouds or any other applications.
## How deploy work ?
It deploy certificates to specified directory and create
two directories `certs` and `private`.
* certs has mode 0644
* private keys has mode 0640
* it deploys all secret content from vault, keys as files with suitable extension <secretname>.<secretKey>
## Installation
### Python PyPI
```
pip install vault-certificate-deploy
```
### Manual
Manual installation
```
git clone https://github.com/rvojcik/vault-certificate-deploy
cd vault-certificate-deploy
sudo python ./setup.py install
```
In the end
```
vault-cert-deploy --help
```
## Example configuration
Can be found in `config.example`.
Role and Secret id can be passed from script arguments.
You could combine `-n` and `--cert-list` parameters.
In `vault` section of configuration it is possible to
set `mount_point` of secret in Vault.
By default it is `cert`.
You could also change this option in arguments
# Vault Configuration
Script uses [Approle](https://www.vaultproject.io/docs/auth/approle.html "Vault Approle Doc") auth.
First enable AppRole auth if it's not
```
vault auth enable approle
```
You have to create your policy first.
Use Vault [documentation](https://www.vaultproject.io/docs/concepts/policies.html) around policies and then continue here.
Example policy with basic medium security can be
```
# Cert Deploy Policy
# Give ability to
# - read all certificates
# - don't permit list certificates
#
path "/certs/*" {
capabilities = ["read"]
}
```
Configure your role
```
vault write auth/approle/role/my-role \
secret_id_ttl=0 \
token_num_uses=0 \
token_ttl=20m \
token_max_ttl=30m \
policies="my-policy,default"
```
Retrieve your approle ID
```
vault read auth/approle/role/my-role/role-id
```
Get secret ID (onetime operation)
```
vault write -f auth/approle/role/my-role/secret-id
```
# Use Cases
It is important to don't have role-id and secret-id together
in one repository or configuration management.
## Puppet
I deploy my servers with installer which create file `/etc/vault_role_id`
which contain `role-id` of the approle.
Then I have Puppet Configuration management which deploy this system with
all files and `secret-id` in configuration file (`/etc/vault-deploy/config.conf`).
Puppet create also file with certs/secret names `/etc/ssl-deploy-certs.conf`
then you can run deploy like this:
```
vault-certificate-deploy.py -c /etc/vault-deploy/config.conf \
--cert-list /etc/ssl-deploy-certs.conf \
--role-id $(cat /etc/vault_role_id)
```
## Hooks
Scripts support definition of hooks directory (`hook_dir`) where you can plase any exacutable file. Every file in hooks directory is executed every time ssl certificates are deployed or changed. You could script any action you need.
### Why ?
I store Puppet configuration in Git, and therefore I have not
role-id and secret-id together in my repository.
I choose to deploy `secret-id` with puppet because when need to
rotate secret-id it is automaticly deployed by puppet to infrastructure.
## What is issue version of the script ?
Issue version of the command or script uses different Secret Storage
Engine. It uses [PKI](https://www.vaultproject.io/api/secret/pki/index.html) which gives you ability to create
your own CA or Intermediate CA. Vault handle both certs generation and issuing.
You have to specify PKI mount point with `--vault-pki` option.
This pki mount_point is used as subdirectory of storage path in your
config file. In this subdirectory we create same structure `certs` and `private`
like in other version of the script.
### What is difference in function ?
Issue command check if certificates you define exists, and it check their expiration time
defined by `--cert-min-ttl` option.
It basicaly means it generates and issue certificates for you, if they not exist, or if they are
close to expire. It is great automation capability in combination with Configuration
Management systems. You don't have to take care of the certificates anymore.
If certificates you define exists and are valid script just do nothing.
### Examples
Create certificate server1.domin.intra on PKI mounted in pki mount point of vault.
If you want to issue new certificate, you have to issue it against some role. In
our case this role is `test`.
More information about [PKI roles in documentation](https://www.vaultproject.io/docs/secrets/pki/index.html).
```
vault-certificate-issue-deploy --vault-pki pki -n server1.domain.intra --cert-role test
```
If we need some subject alternative name you can define it as `--cert-extra-options`
```
vault-certificate-issue-deploy --vault-pki pki -n server1.domain.intra --cert-role test --cert-extra-options "alt_names=console.domain.intra,console1.domain.intra,admin.domain.intra"
```
Result of this can be something like this
```
X509v3 Subject Alternative Name:
DNS:console.domain.intra, DNS:console1.domain.intra, DNS:admin.domain.intra
```
# Security Best Practices
* Never store your role-id and secret-id in your repository together
* Deploy secret-id in way it's quick and easy for you to rotate/change
* In production always use `verify_tls=yes`
* when deploy secret-id and role-id in files/config, always set correct permissions (eg. `0400`, `0600`)
* in vault set policy to your approle only for `read` capability, it's enough
* for highest security set individual approle for every server and set individual policy for every server and certificate
Raw data
{
"_id": null,
"home_page": "https://github.com/rvojcik/vault-certificate-deploy",
"name": "vault-certificate-deploy",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "vault_certificate_deploy,vault_cert_deploy,certificate,vault-certificate-deploy,vault-cert-deploy,hashicorp,certificates",
"author": "Robert Vojcik",
"author_email": "robert@vojcik.net",
"download_url": "https://files.pythonhosted.org/packages/e0/cc/69df83a561270c540e6dcddad4f75a6dd73e02b1de1b1f5388d8b6ad3f30/vault-certificate-deploy-1.4.2.tar.gz",
"platform": null,
"description": "# vault-cert-deploy\n\n\n\nDeploy SSL certificates from HashiCorp's Vault secret server\nScript is able to deploy certificates from KV store of Vault\nor when you use issue version of script it use PKI secret storage.\n\nAs auth method is used [Approle](https://www.vaultproject.io/docs/auth/approle.html \"Vault Approle Doc\"), you need role and secret id\ndeployed to server from different systems/locations. More\nabout this in usecase section.\n\nOn the first look, it may be little bit strange combination of \nconfig file and cli options. You can combine them in different \nways to support various types of deployments to meet the basic\nsecurity concepts.\n\n## Why do I need Vault Server ?\n\nWe are using Let's Encrypt for almost all of our SSL/TLS certificates.\nWe also have complex infrastructure so we have to retrieve \ncertificates in central place and then we distribute them into \ndatacenters, clouds or any other applications.\n\n## How deploy work ?\n\nIt deploy certificates to specified directory and create\ntwo directories `certs` and `private`.\n\n* certs has mode 0644\n* private keys has mode 0640\n* it deploys all secret content from vault, keys as files with suitable extension <secretname>.<secretKey>\n\n## Installation\n\n### Python PyPI\n```\npip install vault-certificate-deploy\n```\n\n### Manual\nManual installation\n\n```\ngit clone https://github.com/rvojcik/vault-certificate-deploy\ncd vault-certificate-deploy\nsudo python ./setup.py install \n```\n\nIn the end \n```\nvault-cert-deploy --help\n```\n\n## Example configuration\nCan be found in `config.example`. \n\nRole and Secret id can be passed from script arguments.\nYou could combine `-n` and `--cert-list` parameters.\n\nIn `vault` section of configuration it is possible to \nset `mount_point` of secret in Vault. \nBy default it is `cert`.\nYou could also change this option in arguments\n\n# Vault Configuration\n\nScript uses [Approle](https://www.vaultproject.io/docs/auth/approle.html \"Vault Approle Doc\") auth.\n\nFirst enable AppRole auth if it's not\n```\nvault auth enable approle\n```\n\nYou have to create your policy first.\nUse Vault [documentation](https://www.vaultproject.io/docs/concepts/policies.html) around policies and then continue here.\n\nExample policy with basic medium security can be\n```\n# Cert Deploy Policy\n# Give ability to\n# - read all certificates\n# - don't permit list certificates\n#\npath \"/certs/*\" {\n capabilities = [\"read\"]\n}\n\n```\n\nConfigure your role\n```\nvault write auth/approle/role/my-role \\\nsecret_id_ttl=0 \\\ntoken_num_uses=0 \\\ntoken_ttl=20m \\\ntoken_max_ttl=30m \\\npolicies=\"my-policy,default\"\n```\n\nRetrieve your approle ID\n```\nvault read auth/approle/role/my-role/role-id\n```\n\nGet secret ID (onetime operation)\n```\nvault write -f auth/approle/role/my-role/secret-id\n```\n\n# Use Cases\nIt is important to don't have role-id and secret-id together\nin one repository or configuration management.\n\n## Puppet\nI deploy my servers with installer which create file `/etc/vault_role_id`\nwhich contain `role-id` of the approle.\n\nThen I have Puppet Configuration management which deploy this system with \nall files and `secret-id` in configuration file (`/etc/vault-deploy/config.conf`). \n\nPuppet create also file with certs/secret names `/etc/ssl-deploy-certs.conf`\n\nthen you can run deploy like this:\n```\nvault-certificate-deploy.py -c /etc/vault-deploy/config.conf \\\n --cert-list /etc/ssl-deploy-certs.conf \\\n --role-id $(cat /etc/vault_role_id)\n```\n\n## Hooks\n\nScripts support definition of hooks directory (`hook_dir`) where you can plase any exacutable file. Every file in hooks directory is executed every time ssl certificates are deployed or changed. You could script any action you need.\n\n### Why ?\nI store Puppet configuration in Git, and therefore I have not \nrole-id and secret-id together in my repository.\nI choose to deploy `secret-id` with puppet because when need to \nrotate secret-id it is automaticly deployed by puppet to infrastructure.\n\n## What is issue version of the script ?\nIssue version of the command or script uses different Secret Storage\nEngine. It uses [PKI](https://www.vaultproject.io/api/secret/pki/index.html) which gives you ability to create\nyour own CA or Intermediate CA. Vault handle both certs generation and issuing. \n\nYou have to specify PKI mount point with `--vault-pki` option.\nThis pki mount_point is used as subdirectory of storage path in your\nconfig file. In this subdirectory we create same structure `certs` and `private`\nlike in other version of the script.\n\n### What is difference in function ?\nIssue command check if certificates you define exists, and it check their expiration time\ndefined by `--cert-min-ttl` option. \n\nIt basicaly means it generates and issue certificates for you, if they not exist, or if they are \nclose to expire. It is great automation capability in combination with Configuration\nManagement systems. You don't have to take care of the certificates anymore.\n\nIf certificates you define exists and are valid script just do nothing.\n\n### Examples\nCreate certificate server1.domin.intra on PKI mounted in pki mount point of vault.\nIf you want to issue new certificate, you have to issue it against some role. In \nour case this role is `test`.\n\nMore information about [PKI roles in documentation](https://www.vaultproject.io/docs/secrets/pki/index.html).\n```\nvault-certificate-issue-deploy --vault-pki pki -n server1.domain.intra --cert-role test\n```\n\nIf we need some subject alternative name you can define it as `--cert-extra-options`\n```\nvault-certificate-issue-deploy --vault-pki pki -n server1.domain.intra --cert-role test --cert-extra-options \"alt_names=console.domain.intra,console1.domain.intra,admin.domain.intra\"\n```\nResult of this can be something like this\n```\n X509v3 Subject Alternative Name: \n DNS:console.domain.intra, DNS:console1.domain.intra, DNS:admin.domain.intra\n```\n\n# Security Best Practices\n* Never store your role-id and secret-id in your repository together\n* Deploy secret-id in way it's quick and easy for you to rotate/change\n* In production always use `verify_tls=yes`\n* when deploy secret-id and role-id in files/config, always set correct permissions (eg. `0400`, `0600`)\n* in vault set policy to your approle only for `read` capability, it's enough\n* for highest security set individual approle for every server and set individual policy for every server and certificate\n\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "System for deploying certificates from Hashicorp Vault server",
"version": "1.4.2",
"project_urls": {
"Homepage": "https://github.com/rvojcik/vault-certificate-deploy"
},
"split_keywords": [
"vault_certificate_deploy",
"vault_cert_deploy",
"certificate",
"vault-certificate-deploy",
"vault-cert-deploy",
"hashicorp",
"certificates"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8f726d29e311c8efa1e71ddbfb3615c7918a3529cc15b18a452ee5fe96abcf79",
"md5": "0e2f8a28bb54b64d001c4855d2a18947",
"sha256": "37f4a6addee8cabe294c0de22c413bf477e97ee99e7535bddb26c24c47a6bc3c"
},
"downloads": -1,
"filename": "vault_certificate_deploy-1.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0e2f8a28bb54b64d001c4855d2a18947",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 28638,
"upload_time": "2023-11-02T14:30:04",
"upload_time_iso_8601": "2023-11-02T14:30:04.492930Z",
"url": "https://files.pythonhosted.org/packages/8f/72/6d29e311c8efa1e71ddbfb3615c7918a3529cc15b18a452ee5fe96abcf79/vault_certificate_deploy-1.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e0cc69df83a561270c540e6dcddad4f75a6dd73e02b1de1b1f5388d8b6ad3f30",
"md5": "7e3d82deb65b536fb708140192ea5c97",
"sha256": "1df5df5e0fb9de6ef3585125cfbccf26349908c6429141a2d7c452e7f3afb887"
},
"downloads": -1,
"filename": "vault-certificate-deploy-1.4.2.tar.gz",
"has_sig": false,
"md5_digest": "7e3d82deb65b536fb708140192ea5c97",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 27113,
"upload_time": "2023-11-02T14:30:07",
"upload_time_iso_8601": "2023-11-02T14:30:07.653553Z",
"url": "https://files.pythonhosted.org/packages/e0/cc/69df83a561270c540e6dcddad4f75a6dd73e02b1de1b1f5388d8b6ad3f30/vault-certificate-deploy-1.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-02 14:30:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rvojcik",
"github_project": "vault-certificate-deploy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "vault-certificate-deploy"
}
JSON
