Improve documentation of 'url-retrieve' and GnuTLS peer status

* doc/misc/url.texi (Retrieving URLs): Describe the ':peer' entry
of the STATUS argument passed to CALLBACK of 'url-retrieve'.

* lisp/url/url.el (url-retrieve):
* src/gnutls.c (Fgnutls_peer_status): Doc fixes.
(Bug#80762)

doc/misc/url.texi

@@ -332,6 +332,29 @@ This means that the request was redirected to the URL
 @item (:error (@var{error-symbol} . @var{data}))
 This means that an error occurred.  If so desired, the error can be
 signaled with @code{(signal @var{error-symbol} @var{data})}.
+
+@cindex status of GnuTLS connection, as provided by @code{url-retrieve}
+@findex gnutls-peer-status-warning-describe
+@findex gnutls-peer-status
+@item  (:peer @var{gnutls-information})
+This means that GnuTLS was used for a TLS connection to the peer.  The
+@var{gnutls-information} has the following form:
+
+@lisp
+ ((:warnings @var{warning}@dots{})
+  (:certificates @var{certificate}@dots{} @var{peer-data}))
+@end lisp
+
+@noindent
+where the @var{warning}s are warnings, if any, emitted by GnuTLS for the
+connection, and @var{certificate}s is the list of certificates used for
+the TLS connection followed by the properties of the connection in
+@var{peer-data}.  Both @var{warning}s and @var{peer-data} are in the
+form of a key-value pairs (i.e., they are plists).  The value of each
+key in the @code{:warnings} list is a symbol whose description can be
+obtained by using @code{gnutls-peer-status-warning-describe}, and the
+various keys of the @var{peer-data} list and their values are documented
+in the doc string of @code{gnutls-peer-status}.
 @end table
 
 When the callback function is called, the current buffer is the one

lisp/url/url.el

@@ -142,6 +142,11 @@ occurred.  Each pair is one of:
 symbol that says something about where the error occurred, and
 DATA is a list (possibly nil) that describes the error further.
 
+\(:peer GNUTLS-INFO) - GnuTLS information for the retrieval request.
+This will be present only if GnuTLS was used to make an HTTPS request,
+in which case GNUTLS-INFO is the list returned by `gnutls-peer-status'
+describing the state of TLS connection with the peer.
+
 Return the buffer URL will load into, or nil if the process has
 already completed (i.e. URL was a mailto URL or similar; in this case
 the callback is not called).

src/gnutls.c

@@ -1383,18 +1383,43 @@ DEFUN ("gnutls-peer-status-warning-describe", Fgnutls_peer_status_warning_descri
 }
 
 DEFUN ("gnutls-peer-status", Fgnutls_peer_status, Sgnutls_peer_status, 1, 1, 0,
-       doc: /* Describe a GnuTLS PROC peer certificate and any warnings about it.
+       doc: /* Describe GnuTLS peer certificate of PROC and any warnings about it.
 
 The return value is a property list with top-level keys :warnings and
 :certificates.
 
-The :warnings entry is a list of symbols you can get a description of
-with `gnutls-peer-status-warning-describe', and :certificates is the
-certificate chain for the connection, with the host certificate
-first, and intermediary certificates (if any) following it.
+The :warnings entry is a list of symbols whose descriptions can be
+obtained with `gnutls-peer-status-warning-describe'.
 
-In addition, for backwards compatibility, the host certificate is also
-returned as the :certificate entry.  */)
+The :certificates entry is the certificate chain for the connection,
+with the host certificate first and intermediary certificates (if any)
+following it.  In addition, for backwards compatibility, the host
+certificate is also returned as the :certificate entry.
+
+The list in :certificates entry can also include one or more of the
+properties of the TLS connection, when applicable, using the following
+keys:
+
+  :cipher              a string naming the cipher algorithm, or "NULL"
+
+  :compression         a string naming the compression algorithm, or "NULL"
+
+  :diffie-hellman-prime-bits
+		       the number if bits used in Diffie-Hellman key exchange,
+			 an integer
+
+  :encrypt-then-mac    t if encrypt-then-mac negotiation was successful,
+                         nil otherwise
+
+  :key-exchange        key exchange algorithm, a string
+
+  :mac                 a string naming the MAC algorithm, or "NULL"
+
+  :protocol            TLS protocol version as a string
+
+  :safe-renegotiation  t if safe renegotiation is used, otherwise nil
+
+*/)
   (Lisp_Object proc)
 {
   Lisp_Object warnings = Qnil, result = Qnil;