fixes #2173 New TLS cert API - replaces the properties for CN and ALTNAMES.

This will replace the NNG_OPT_TLS_PEER_ALTNAMES and NNG_OPT_TLS_PEER_CN
properties, and gives a bit more access to the certificate, as well as
direct access to the raw DER form, which should allow use in other APIs.

2 files changed, 29 insertions, 0 deletions

diff --git a/docs/ref/api/http.md b/docs/ref/api/http.md
index 04c3ee4a..bbe33c24 100644
--- a/docs/ref/api/http.md
+++ b/docs/ref/api/http.md
@@ -349,6 +349,26 @@ This function is most useful when called from a handler function.
 > This function is intended to facilitate uses cases that involve changing the protocol from HTTP, such as WebSocket.
 > Most applications will never need to use this function.
 
+### Obtaining TLS Connection Details
+
+```c
+nng_err nng_http_peer_cert(nng_http_conn *conn, nng_tls_cert **certp);
+```
+
+TODO: We need to document the cert API.
+
+The {{i:`nng_http_peer_cert`}} function will obtain the TLS certificate object for the peer, if one is available.
+This can then be used for additional authentication or identity specific logic.
+
+The certificate must be released with [`nng_tls_cert_free`] when no longer in use.
+See [`nng_tls_cert`] for more information about working with TLS certificates.
+
+> [!NOTE]
+> While it should be obvious that this function is only available when using HTTPS,
+> it also requires that peer authentication is in use, and may require that the underlying
+> TLS engine support peer certificate colleciton. (Some minimal configurations elide this
+> to save space in embedded environments.)
+
 ## Client API
 
 The NNG client API consists of an API for creating connections, and an API for performing
diff --git a/docs/ref/migrate/nng1.md b/docs/ref/migrate/nng1.md
index 5b85c41d..df062efd 100644
--- a/docs/ref/migrate/nng1.md
+++ b/docs/ref/migrate/nng1.md
@@ -156,6 +156,15 @@ The ability to configure multiple keys and certificates for a given TLS configur
 The intended purpose was to support alternative cryptographic algorithms, but this is not necessary, was never
 used, and was error prone.
 
+## TLS Peer Certificate APIs Replaced
+
+The `NNG_OPT_TLS_PEER_CN` and `NNG_OPT_TLS_PEER_ALT_NAMES` properties have been removed.
+They are replaced with functions like [`nng_pipe_peer_cert`], [`nng_stream_peer_cert`],
+and [`nng_http_peer_cert`] which return a new `nng_tls_cert` object.
+
+This object supports methods to get additional information about the certificate, as well
+as to obtain the raw DER content so that it can be imported for use in other APIs.
+
 ## Support for Local Addresses in Dial URLs Removed
 
 NNG 1.x had an undocumented ability to specify the local address to bind