From: Jay Satiro <raysatiro@yahoo.com>
Date: Sat, 12 Aug 2023 07:29:25 +0000 (-0400)
Subject: CURLINFO_CERTINFO.3: better explain curl_certinfo struct
X-Git-Tag: curl-8_3_0~153
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8843bef3180f3a631d16ce9f2a895adbeacbed7a;p=thirdparty%2Fcurl.git

CURLINFO_CERTINFO.3: better explain curl_certinfo struct

Closes https://github.com/curl/curl/pull/11666
---

diff --git a/docs/libcurl/opts/CURLINFO_CERTINFO.3 b/docs/libcurl/opts/CURLINFO_CERTINFO.3
index 97ed1fb73a..b06b3ee4de 100644
--- a/docs/libcurl/opts/CURLINFO_CERTINFO.3
+++ b/docs/libcurl/opts/CURLINFO_CERTINFO.3
@@ -33,13 +33,23 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CERTINFO,
                            struct curl_certinfo **chainp);
 .fi
 .SH DESCRIPTION
-Pass a pointer to a \fIstruct curl_certinfo *\fP and you will get it set to
-point to a struct that holds a number of linked lists with info about the
-certificate chain, assuming you had \fICURLOPT_CERTINFO(3)\fP enabled when the
-request was made. The struct reports how many certs it found and then you can
-extract info for each of those certs by following the linked lists. The info
-chain is provided in a series of data in the format "name:content" where the
-content is for the specific named data. See also the \fIcertinfo.c\fP example.
+Pass a pointer to a \fIstruct curl_certinfo *\fP and it will be set to point to
+a struct that holds info about the server's certificate chain, assuming you had
+\fICURLOPT_CERTINFO(3)\fP enabled when the request was made.
+
+.nf
+struct curl_certinfo {
+  int num_of_certs;
+  struct curl_slist **certinfo;
+};
+.fi
+
+The \fIcertinfo\fP struct member is an array of linked lists of certificate
+information. The \fInum_of_certs\fP struct member is the number of certificates
+which is the number of elements in the array. Each certificate's list has items
+with textual information in the format "name:content" such as "Subject:Foo",
+"Issuer:Bar", etc. The items in each list will vary depending on the SSL
+backend and the certificate.
 .SH PROTOCOLS
 All TLS-based
 .SH EXAMPLE
@@ -74,10 +84,12 @@ if(curl) {
   curl_easy_cleanup(curl);
 }
 .fi
+
+See also the \fIcertinfo.c\fP example.
 .SH AVAILABILITY
-This option is only working in libcurl built with OpenSSL, Schannel or
-Secure Transport support. Schannel support added in 7.50.0. Secure Transport
-support added in 7.79.0.
+This option is only working in libcurl built with OpenSSL, GnuTLS, Schannel or
+Secure Transport. GnuTLS support added in 7.42.0. Schannel support added in
+7.50.0. Secure Transport support added in 7.79.0.
 
 Added in 7.19.1
 .SH RETURN VALUE
diff --git a/include/curl/curl.h b/include/curl/curl.h
index a35e686e69..898cbda839 100644
--- a/include/curl/curl.h
+++ b/include/curl/curl.h
@@ -2824,13 +2824,14 @@ CURL_EXTERN void curl_slist_free_all(struct curl_slist *list);
  */
 CURL_EXTERN time_t curl_getdate(const char *p, const time_t *unused);
 
-/* info about the certificate chain, only for OpenSSL, GnuTLS, Schannel and
-   NSS builds. Asked for with CURLOPT_CERTINFO / CURLINFO_CERTINFO */
+/* info about the certificate chain, for SSL backends that support it. Asked
+   for with CURLOPT_CERTINFO / CURLINFO_CERTINFO */
 struct curl_certinfo {
   int num_of_certs;             /* number of certificates with information */
   struct curl_slist **certinfo; /* for each index in this array, there's a
-                                   linked list with textual information in the
-                                   format "name: value" */
+                                   linked list with textual information for a
+                                   certificate in the format "name:content".
+                                   eg "Subject:foo", "Issuer:bar", etc. */
 };
 
 /* Information about the SSL library used and the respective internal SSL