From 9b8361d9abddb32a343ba325421bad13be2837b8 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Wed, 8 Apr 2026 11:02:47 +0300
Subject: [PATCH] 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 | 23 +++++++++++++++++++++++
 lisp/url/url.el   |  5 +++++
 src/gnutls.c      | 39 ++++++++++++++++++++++++++++++++-------
 3 files changed, 60 insertions(+), 7 deletions(-)

diff --git a/doc/misc/url.texi b/doc/misc/url.texi
index 0613294024e..a07aa805fa9 100644
--- a/doc/misc/url.texi
+++ b/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
diff --git a/lisp/url/url.el b/lisp/url/url.el
index c8ee686a410..002ce7bef7d 100644
--- a/lisp/url/url.el
+++ b/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).
diff --git a/src/gnutls.c b/src/gnutls.c
index 44d2f7f4db2..4a4567a5174 100644
--- a/src/gnutls.c
+++ b/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;