diff options
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/api/http.md | 20 | ||||
| -rw-r--r-- | docs/ref/migrate/nng1.md | 9 |
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 |