docs/certificate-management.rst

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