pmg-ssl-certificate.adoc

   1 [[sysadmin_certificate_management]]
   2 Certificate Management
   3 ----------------------
   4
   5 Access to the administration web-interface is always encrypted through `https`.
   6 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 an user and the web-interface or between
   9 nodes 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} knows 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 those 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 Webinterface.
  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 upload that certificate simply over the web interface.
  43
  44 [thumbnail="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 from 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 its staging
  60 environment. 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="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 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 plugins task 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 basis building block for 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 certain content 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 these cases.  The
  98 challenge is fulfilled by creating a certain DNS record in the domain's zone.
  99
 100 [thumbnail="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="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 circa 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 webserver spawned on port 80.
 129
 130 NOTE: The name `standalone` means that it can provide the validation on it's
 131 own, without any third party service. So, this plugin works also for cluster
 132 nodes.
 133
 134 There are a few prerequisites to use it 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="pmg-gui-acme-create-challenge-plugin.png"]
 164
 165 Add a new challenge plugin, here you can select your API provider, enter the
 166 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
 176 those you will see a bigger text area, simply copy all the credentials
 177 `KEY`=`VALUE` pairs in there.
 178
 179 DNS Validation through CNAME Alias
 180 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 181
 182 A special `alias` mode can be used to handle the 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
 191 Combination of Plugins
 192 ^^^^^^^^^^^^^^^^^^^^^^
 193
 194 Combining `http-01` and `dns-01` validation is possible in case your node is
 195 reachable via multiple domains with different requirements / DNS provisioning
 196 capabilities. Mixing DNS APIs from multiple providers or instances is also
 197 possible by specifying different plugin instances per domain.
 198
 199 TIP: Accessing the same service over multiple domains increases complexity and
 200 should be avoided if possible.
 201
 202 [[sysadmin_certs_acme_automatic_renewal]]
 203 Automatic renewal of ACME certificates
 204 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 205
 206 If a node has been successfully configured with an ACME-provided certificate
 207 (either via pmgconfig or via the web-interface/API), the certificate will be
 208 automatically renewed by the `pmg-daily.service`. Currently, renewal is
 209 triggered if the certificate either already expired or if it will expire in the
 210 next 30 days.
 211
 212 Manually Change Certificate over Command-Line
 213 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 214
 215 If you want to get rid of certificate verification warnings, you have to
 216 generate a valid certificate for your server.
 217
 218 Login to your {pmg} via ssh or use the console:
 219
 220 ----
 221 openssl req -newkey rsa:2048 -nodes -keyout key.pem -out req.pem
 222 ----
 223
 224 Follow the instructions on the screen, see this example:
 225
 226 ----
 227 Country Name (2 letter code) [AU]: AT
 228 State or Province Name (full name) [Some-State]:Vienna
 229 Locality Name (eg, city) []:Vienna
 230 Organization Name (eg, company) [Internet Widgits Pty Ltd]: Proxmox GmbH
 231 Organizational Unit Name (eg, section) []:Proxmox Mail Gateway
 232 Common Name (eg, YOUR name) []: yourproxmox.yourdomain.com
 233 Email Address []:support@yourdomain.com
 234
 235 Please enter the following 'extra' attributes to be sent with your certificate request
 236 A challenge password []: not necessary
 237 An optional company name []: not necessary
 238 ----
 239
 240 After you finished this certificate request you have to send the file
 241 `req.pem` to your Certification Authority (CA). The CA will issue the
 242 certificate (BASE64 encoded) based on your request – save this file as
 243 `cert.pem` to your {pmg}.
 244
 245 To activate the new certificate, do the following on your {pmg}:
 246
 247 ----
 248 cat key.pem cert.pem >/etc/pmg/pmg-api.pem
 249 ----
 250
 251 Then restart the API servers:
 252
 253 ----
 254 systemctl restart pmgproxy
 255 ----
 256
 257 Test your new certificate by using your browser.
 258
 259 NOTE: To transfer files from and to your {pmg}, you can use secure copy: If you
 260 desktop is Linux, you can use the `scp` command line tool. If your desktop PC
 261 is windows, please use a scp client like WinSCP (see https://winscp.net/).
 262
 263 Change Certificate for Cluster Setups
 264 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 265
 266 If you change the API certificate of an active cluster node manually, you also
 267 need to update the pinned fingerprint inside the cluster configuration.
 268
 269 You can do that by executing the following command on the host where the
 270 certificate changed:
 271
 272 ----
 273 pmgcm update-fingerprints
 274 ----
 275
 276 Note, this will be done automatically if using the integrated ACME (for
 277 example, through Let's Encrypt) feature.