Vault Certbot

Vault Certbot is a small program that will perform certificate generation and renewal across topology using Hashicorp Vault. Using HTTP/1.1 to comunicate, Vault Certbot offers centralized control of certificate configuration accross topology.

HTTPS communication between Vault Certbot is not yet supported.

---

Environment variables:

• LISTEN_ADDR: Required for Certbot Server. Address for the certbot to listen to. For example: http://localhost:3000
• SERVER_ADDR: Required for Certbot Client. HTTP Address of Certbot Server.
• CHECK_INTERVAL_SEC: Interval for certificates expiry check in seconds. (default=3600)
• NODE: The name of current node for placement configuration.
• VAUT_ADDR: Hashicorp Vault http(s) address.
• ROLE_ID_PATH: Path to Hashicorp Vault role-id.
• SECRET_ID_PATH: Path to Hashicorp Vault secret-id.
• OUT_DIR: Directory for generated certificates and snapshot.json file.
• HOOS_DIR: Direcory for hooks.
• UNSAFE: Set to "true" to disable Hashicorp Vault certificate verification. (optional)

Vault certbot wil also automatically load .env file in the same directory.

Certbot Server

Certbot Server is the certbot that holds snapshot.json file. It will open a HTTP Server for Certbot Clients to request snapshot.json and request resource locking. Certbot Server will also perform certificate generation and renewals.

In certificates directory, create snapshot.json file that contains list of certificates options for certbot to maintain. Below is an example of a valid snapshot.json.

{
  "version": 1,
  "resources": {
    "nomad": 2
  },
  "certs": {
    "nomad-node1": {
      "issuer-ref": "670d10f5-73aa-c742-1150-808d40f98c64",
      "role": "nomad-servers",
      "placements": ["node1"],
      "common_name": "nomad.internal",
      "private_key_format": "pem",
      "ttl": "86400",
      "hook": {
        "script": "restart-nomad.sh",
        "args": [],
        "resources": {
          "nomad": 1
        }
      }
    }
  }
}

The snapshot.json above will generate certificate at path/to/out-dir/nomad-node1. After certificate was generated, Certbot will run the script specified in the hook attribute. Before executing the script, Certbot will lock the required resources, to avoid outage.

The snapshot.json above will allow two certbots to execute restart-nomad.sh script at the same time.

Certbot Client

Certbot Client is a satteess certbot that will request snapshot.json and resource locking to the Certbot Server allowing easy modification for certificate configuration for the entire topology.

Snapshot

type Snapshot struct {
	Version   int                   `json:"version"`
	Resources map[string]int        `json:"resources"`
	Certs     map[string]CertConfig `json:"certs,omitempty"`
}

type CertConfig struct {
	Role                 string    `json:"role"`
	Placements           *[]string `json:"placements,omitempty"`
	Hook                 *Hook     `json:"hook,omitempty"`
	AltNames             string    `json:"alt_names,omitempty"`
	CommonName           string    `json:"common_name,omitempty"`
	Csr                  string    `json:"csr,omitempty"`
	ExcludeCnFromSans    bool      `json:"exclude_cn_from_sans,omitempty"`
	Format               string    `json:"format,omitempty"`
	IpSans               []string  `json:"ip_sans,omitempty"`
	NotAfter             string    `json:"not_after,omitempty"`
	OtherSans            []string  `json:"other_sans,omitempty"`
	PrivateKeyFormat     string    `json:"private_key_format,omitempty"`
	RemoveRootsFromChain bool      `json:"remove_roots_from_chain,omitempty"`
	SerialNumber         string    `json:"serial_number,omitempty"`
	Ttl                  string    `json:"ttl,omitempty"`
	UriSans              []string  `json:"uri_sans,omitempty"`
	UserIds              []string  `json:"user_ids,omitempty"`
}

type Hook struct {
	Script    string         `json:"script"`
	Args      []string       `json:"args"`
	Resources map[string]int `json:"resources"`
}