pmg-ssl-certificate.adoc

   1 [[sysadmin_certificate_management]]
   2 Certificate Management
   3 ----------------------
   4
   5 Access to the web-based administration interface is always encrypted through
   6 `https`.  Each {pmg} host creates by default its own (self-signed) certificate.
   7 This certificate is used for encrypted communication with the host's `pmgproxy`
   8 service, for any API call between a user and the web-interface or between nodes
   9 in a cluster.
  10
  11 Certificate verification in a {pmg} cluster is done based on pinning the
  12 certificate fingerprints in the cluster configuration and verifying that they
  13 match on connection.
  14
  15 [[sysadmin_certs_api_gui]]
  16 Certificates for the API and SMTP
  17 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18
  19 {pmg} uses two different certificates:
  20
  21 * `/etc/pmg/pmg-api.pem`: the required certificate used for {pmg} API requests.
  22 * `/etc/pmg/pmg-tls.pem`: the optional certificate used for SMTP TLS
  23   connections, see xref:pmgconfig_mailproxy_tls[mailproxy TLS configuration]
  24   for details.
  25
  26 You have the following options for these certificates:
  27
  28 1. Keep using the default self-signed certificate in `/etc/pmg/pmg-api.pem`.
  29 2. Use an externally provided certificate (for example, signed by a commercial
  30 Certificate Authority (CA)).
  31 3. Use an ACME provider like Let's Encrypt to get a trusted certificate with
  32 automatic renewal; this is also integrated in the {pmg} API and web interface.
  33
  34 Certificates are managed through the {pmg} web-interface/API or using the
  35 the `pmgconfig` CLI tool.
  36
  37 [[sysadmin_certs_upload_custom]]
  38 Upload Custom Certificate
  39 ~~~~~~~~~~~~~~~~~~~~~~~~~
  40
  41 If you already have a certificate which you want to use for a {pmg} host, you
  42 can simply upload that certificate over the web interface.
  43
  44 [thumbnail="screenshot/pmg-gui-certs-upload-custom.png"]
  45
  46 Note that any certificate key files must not be password protected.
  47
  48 [[sysadmin_certs_get_trusted_acme_cert]]
  49 Trusted certificates via Let's Encrypt (ACME)
  50 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  51
  52 {PMG} includes an implementation of the **A**utomatic **C**ertificate
  53 **M**anagement **E**nvironment (**ACME**) protocol, allowing {pmg} admins to
  54 use an ACME provider like Let's Encrypt for easy setup of TLS certificates,
  55 which are accepted and trusted by modern operating systems and web browsers
  56 out of the box.
  57
  58 Currently, the two ACME endpoints implemented are the
  59 https://letsencrypt.org[Let's Encrypt (LE)] production and staging
  60 environments. Our ACME client supports validation of `http-01` challenges using
  61 a built-in web server and validation of `dns-01` challenges using a DNS plugin
  62 supporting all the DNS API endpoints https://acme.sh[acme.sh] does.
  63
  64 [[sysadmin_certs_acme_account]]
  65 ACME Account
  66 ^^^^^^^^^^^^
  67
  68 [thumbnail="screenshot/pmg-gui-acme-create-account.png"]
  69
  70 You need to register an ACME account per cluster, with the endpoint you want to
  71 use. The email address used for that account will serve as the contact point for
  72 renewal-due or similar notifications from the ACME endpoint.
  73
  74 You can register or deactivate ACME accounts over the web interface
  75 `Certificates -> ACME Accounts` or using the `pmgconfig` command-line tool.
  76 ----
  77  pmgconfig acme account register <account-name> <mail@example.com>
  78 ----
  79
  80 TIP: Because of https://letsencrypt.org/docs/rate-limits/[rate-limits] you
  81 should use LE `staging` for experiments or if you use ACME for the very first
  82 time until all is working there, and only then switch over to the production
  83 directory.
  84
  85 [[sysadmin_certs_acme_plugins]]
  86 ACME Plugins
  87 ^^^^^^^^^^^^
  88
  89 The ACME plugin's role is to provide automatic verification that you, and thus
  90 the {pmg} cluster under your operation, are the real owner of a domain. This is
  91 the basic building block of automatic certificate management.
  92
  93 The ACME protocol specifies different types of challenges, for example the
  94 `http-01`, where a web server provides a file with a specific token to prove
  95 that it controls a domain. Sometimes this isn't possible, either because of
  96 technical limitations or if the address of a record is not reachable from the
  97 public internet. The `dns-01` challenge can be used in such cases. This
  98 challenge is fulfilled by creating a certain DNS record in the domain's zone.
  99
 100 [thumbnail="screenshot/pmg-gui-acme-create-challenge-plugin.png"]
 101
 102 {pmg} supports both of those challenge types out of the box, you can configure
 103 plugins either over the web interface under `Certificates -> ACME Challenges`,
 104 or using the `pmgconfig acme plugin add` command.
 105
 106 ACME Plugin configurations are stored in `/etc/pmg/acme/plugins.cfg`.
 107 A plugin is available for all nodes in the cluster.
 108
 109 Domains
 110 ^^^^^^^
 111
 112 You can add new or manage existing domain entries under `Certificates`, or
 113 using the `pmgconfig` command.
 114
 115 [thumbnail="screenshot/pmg-gui-acme-add-domain.png"]
 116
 117 After configuring the desired domain(s) for a node and ensuring that the
 118 desired ACME account is selected, you can order your new certificate over the
 119 web-interface. On success, the interface will reload after roughly 10 seconds.
 120
 121 Renewal will happen xref:sysadmin_certs_acme_automatic_renewal[automatically].
 122
 123 [[sysadmin_certs_acme_http_challenge]]
 124 ACME HTTP Challenge Plugin
 125 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 126
 127 There is always an implicitly configured `standalone` plugin for validating
 128 `http-01` challenges via the built-in web server spawned on port 80.
 129
 130 NOTE: The name `standalone` means that it can provide the validation on its
 131 own, without any third party service. So this plugin also works for cluster
 132 nodes.
 133
 134 There are a few prerequisites to use this for certificate management with Let's
 135 Encrypts ACME.
 136
 137 * You have to accept the ToS of Let's Encrypt to register an account.
 138 * **Port 80** of the node needs to be reachable from the internet.
 139 * There **must** be no other listener on port 80.
 140 * The requested (sub)domain needs to resolve to a public IP of the {pmg} host.
 141
 142
 143 [[sysadmin_certs_acme_dns_challenge]]
 144 ACME DNS API Challenge Plugin
 145 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 146
 147 On systems where external access for validation via the `http-01` method is
 148 not possible or desired, it is possible to use the `dns-01` validation method.
 149 This validation method requires a DNS server that allows provisioning of `TXT`
 150 records via an API.
 151
 152 [[sysadmin_certs_acme_dns_api_config]]
 153 Configuring ACME DNS APIs for validation
 154 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 155
 156 {pmg} re-uses the DNS plugins developed for the `acme.sh`
 157 footnote:[acme.sh https://github.com/acmesh-official/acme.sh] project. Please
 158 refer to its documentation for details on configuration of specific APIs.
 159
 160 The easiest way to configure a new plugin with the DNS API is using the web
 161 interface (`Certificates -> ACME Accounts/Challenges`).
 162
 163 [thumbnail="screenshot/pmg-gui-acme-create-challenge-plugin.png"]
 164
 165 Here you can add a new challenge plugin by selecting your API provider and
 166 entering the credential data to access your account over their API.
 167
 168 TIP: See the acme.sh
 169 https://github.com/acmesh-official/acme.sh/wiki/dnsapi#how-to-use-dns-api[How to use DNS API]
 170 wiki for more detailed information about getting API credentials for your
 171 provider. Configuration values do not need to be quoted with single or double
 172 quotes; for some plugins that is even an error.
 173
 174 As there are many DNS providers and API endpoints, {pmg} automatically generates
 175 the form for the credentials, but not all providers are annotated yet. For those
 176 you will see a bigger text area, into which you simply need to copy all the
 177 credential's `KEY`=`VALUE` pairs.
 178
 179 DNS Validation through CNAME Alias
 180 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 181
 182 A special `alias` mode can be used to handle validation on a different
 183 domain/DNS server, in case your primary/real DNS does not support provisioning
 184 via an API. Manually set up a permanent `CNAME` record for
 185 `_acme-challenge.domain1.example` pointing to `_acme-challenge.domain2.example`,
 186 and set the `alias` property in the {pmg} node configuration file
 187 `/etc/pmg/node.conf` to `domain2.example` to allow the DNS server of
 188 `domain2.example` to validate all challenges for `domain1.example`.
 189
 190 [[sysadmin_certs_acme_dns_wildcard]]
 191 Wildcard Certificates
 192 ^^^^^^^^^^^^^^^^^^^^^
 193
 194 Wildcard DNS names start with a `*.` prefix and are considered valid for all
 195 (one-level) subdomain names of the verified domain. So a certificate for
 196 `*.domain.example` is valid for `foo.domain.example` and
 197 `bar.domain.example`, but not for `baz.foo.domain.example`.
 198
 199 Currently, you can only create wildcard certificates with the
 200 https://letsencrypt.org/docs/challenge-types/#dns-01-challenge[DNS challenge type].
 201
 202
 203 Combination of Plugins
 204 ^^^^^^^^^^^^^^^^^^^^^^
 205
 206 Combining `http-01` and `dns-01` validation is possible in case your node is
 207 reachable via multiple domains with different requirements / DNS provisioning
 208 capabilities. Mixing DNS APIs from multiple providers or instances is also
 209 possible by specifying different plugin instances per domain.
 210
 211 TIP: Accessing the same service over multiple domains increases complexity and
 212 should be avoided if possible.
 213
 214 [[sysadmin_certs_acme_automatic_renewal]]
 215 Automatic renewal of ACME certificates
 216 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 217
 218 If a node has been successfully configured with an ACME-provided certificate
 219 (either via pmgconfig or via the web-interface/API), the certificate will be
 220 renewed automatically by the `pmg-daily.service`. Currently, renewal is
 221 triggered if the certificate either has already expired or if it will expire in
 222 the next 30 days.
 223
 224 Manually Change Certificate over the Command Line
 225 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 226
 227 If you want to get rid of certificate verification warnings, you have to
 228 generate a valid certificate for your server.
 229
 230 Log in to your {pmg} via ssh or use the console:
 231
 232 ----
 233 openssl req -newkey rsa:2048 -nodes -keyout key.pem -out req.pem
 234 ----
 235
 236 Follow the instructions on the screen, for example:
 237
 238 ----
 239 Country Name (2 letter code) [AU]: AT
 240 State or Province Name (full name) [Some-State]:Vienna
 241 Locality Name (eg, city) []:Vienna
 242 Organization Name (eg, company) [Internet Widgits Pty Ltd]: Proxmox GmbH
 243 Organizational Unit Name (eg, section) []:Proxmox Mail Gateway
 244 Common Name (eg, YOUR name) []: yourproxmox.yourdomain.com
 245 Email Address []:support@yourdomain.com
 246
 247 Please enter the following 'extra' attributes to be sent with your certificate request
 248 A challenge password []: not necessary
 249 An optional company name []: not necessary
 250 ----
 251
 252 After you have finished the certificate request, you have to send the file
 253 `req.pem` to your Certification Authority (CA). The CA will issue the
 254 certificate (BASE64 encoded), based on your request – save this file as
 255 `cert.pem` to your {pmg}.
 256
 257 To activate the new certificate, do the following on your {pmg}:
 258
 259 ----
 260 cat key.pem cert.pem >/etc/pmg/pmg-api.pem
 261 ----
 262
 263 Then restart the API servers:
 264
 265 ----
 266 systemctl restart pmgproxy
 267 ----
 268
 269 Test your new certificate, using your browser.
 270
 271 NOTE: To transfer files to and from your {pmg}, you can use secure copy: If your
 272 desktop runs Linux, you can use the `scp` command-line tool. If your desktop PC
 273 runs windows, please use an scp client like WinSCP (see https://winscp.net/).
 274
 275 Change Certificate for Cluster Setups
 276 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 277
 278 If you change the API certificate of an active cluster node manually, you also
 279 need to update the pinned fingerprint inside the cluster configuration.
 280
 281 You can do that by executing the following command on the host where the
 282 certificate changed:
 283
 284 ----
 285 pmgcm update-fingerprints
 286 ----
 287
 288 Note, this will be done automatically if using the integrated ACME (for
 289 example, through Let's Encrypt) feature.