From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <s.ivanov@proxmox.com>
Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68])
 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
 key-exchange X25519 server-signature RSA-PSS (2048 bits))
 (No client certificate requested)
 by lists.proxmox.com (Postfix) with ESMTPS id DCE456B9AA
 for <pmg-devel@lists.proxmox.com>; Wed, 17 Mar 2021 21:19:27 +0100 (CET)
Received: from firstgate.proxmox.com (localhost [127.0.0.1])
 by firstgate.proxmox.com (Proxmox) with ESMTP id CD81FA66F
 for <pmg-devel@lists.proxmox.com>; Wed, 17 Mar 2021 21:18:57 +0100 (CET)
Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com
 [212.186.127.180])
 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
 key-exchange X25519 server-signature RSA-PSS (2048 bits))
 (No client certificate requested)
 by firstgate.proxmox.com (Proxmox) with ESMTPS id 8E07FA664
 for <pmg-devel@lists.proxmox.com>; Wed, 17 Mar 2021 21:18:56 +0100 (CET)
Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1])
 by proxmox-new.maurer-it.com (Proxmox) with ESMTP id 11D4545920
 for <pmg-devel@lists.proxmox.com>; Wed, 17 Mar 2021 21:18:56 +0100 (CET)
From: Stoiko Ivanov <s.ivanov@proxmox.com>
To: pmg-devel@lists.proxmox.com
Date: Wed, 17 Mar 2021 21:18:34 +0100
Message-Id: <20210317201834.13739-1-s.ivanov@proxmox.com>
X-Mailer: git-send-email 2.20.1
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
X-SPAM-LEVEL: Spam detection results:  0
 AWL 0.063 Adjusted score from AWL reputation of From: address
 KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment
 RCVD_IN_DNSWL_MED        -2.3 Sender listed at https://www.dnswl.org/,
 medium trust
 SPF_HELO_NONE           0.001 SPF: HELO does not publish an SPF Record
 SPF_PASS               -0.001 SPF: sender matches SPF record
Subject: [pmg-devel] [PATCH pmg-docs] certs: pmg uses fingerprint pinning
X-BeenThere: pmg-devel@lists.proxmox.com
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Proxmox Mail Gateway development discussion
 <pmg-devel.lists.proxmox.com>
List-Unsubscribe: <https://lists.proxmox.com/cgi-bin/mailman/options/pmg-devel>, 
 <mailto:pmg-devel-request@lists.proxmox.com?subject=unsubscribe>
List-Archive: <http://lists.proxmox.com/pipermail/pmg-devel/>
List-Post: <mailto:pmg-devel@lists.proxmox.com>
List-Help: <mailto:pmg-devel-request@lists.proxmox.com?subject=help>
List-Subscribe: <https://lists.proxmox.com/cgi-bin/mailman/listinfo/pmg-devel>, 
 <mailto:pmg-devel-request@lists.proxmox.com?subject=subscribe>
X-List-Received-Date: Wed, 17 Mar 2021 20:19:27 -0000

the patch also addresses small stylistic nits.

Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
---
will send the stylistic changes also for pve-docs once approved
 pmg-ssl-certificate.adoc | 27 +++++++++++++--------------
 1 file changed, 13 insertions(+), 14 deletions(-)

diff --git a/pmg-ssl-certificate.adoc b/pmg-ssl-certificate.adoc
index 7824f22..82a395d 100644
--- a/pmg-ssl-certificate.adoc
+++ b/pmg-ssl-certificate.adoc
@@ -3,12 +3,11 @@ Certificate Management
 ----------------------
 
 Access to the administration web-interface is always encrypted through `https`.
-Each {pmg} host creates by default its own (self-signed) Certificate Authority
-(CA) and generates a certificate for the node which gets signed by the
-aforementioned CA.
-These certificates are used for encrypted communication with
-the cluster's `pmgproxy` service for any API call, between an user and the
-web-interface or between nodes in a cluster.
+Each {pmg} host creates by default its own (self-signed) certificate. This
+certificate is used for encrypted communication with the host's `pmgproxy`
+service for any API call, between an user and the web-interface or between
+nodes in a cluster. Certificate verification in a {pmg} cluster is done based
+on pinning the certificate fingerprints in the cluster configuration.
 
 [[sysadmin_certs_api_gui]]
 Certificates for the API and SMTP
@@ -41,7 +40,7 @@ can upload that certificate simply over the web interface.
 
 [thumbnail="pmg-gui-certs-upload-custom.png"]
 
-Note that any certificates key file must not be password protected.
+Note that any certificate key files must not be password protected.
 
 [[sysadmin_certs_get_trusted_acme_cert]]
 Trusted certificates via Let's Encrypt (ACME)
@@ -65,7 +64,7 @@ ACME Account
 [thumbnail="pmg-gui-acme-create-account.png"]
 
 You need to register an ACME account per cluster with the endpoint you want to
-use. The email address used for that account will server as contact point for
+use. The email address used for that account will serve as contact point for
 renewal-due or similar notifications from the ACME endpoint.
 
 You can register or deactivate ACME accounts over the web interface
@@ -88,12 +87,12 @@ the {pmg} cluster under your operation, are the real owner of a domain. This is
 the basis building block for automatic certificate management.
 
 The ACME protocol specifies different types of challenges, for example the
-`http-01` where a webserver provides a file with a certain value to prove that
+`http-01` where a webserver provides a file with a certain content to prove that
 it controls a domain. Sometimes this isn't possible, either because of
 technical limitations or if the address a domain points to is not reachable
-from the public internet. For such cases, one could use the `dns-01` challenge.
-This challenge also provides a certain value, but through a DNS record on the
-authority name server of the domain, rather than over a text file.
+from the public internet. The `dns-01` challenge can be used in these cases.
+The challenge is fulfilled by creating a certain DNS record in the domain's
+zone.
 
 [thumbnail="pmg-gui-acme-create-challenge-plugin.png"]
 
@@ -211,8 +210,8 @@ next 30 days.
 Manually Change Certificate over Command-Line
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you want to get rid of these warnings, you have to generate a valid
-certificate for your server.
+If you want to get rid of certificate verification warnings, you have to
+generate a valid certificate for your server.
 
 Login to your {pmg} via ssh or use the console:
 
-- 
2.20.1