4 files changed, 23 insertions, 16 deletions
diff --git a/docs/man/nng_ipc_options.5.adoc b/docs/man/nng_ipc_options.5.adoc
index 516fbe80..79a302e8 100644
--- a/docs/man/nng_ipc_options.5.adoc
+++ b/docs/man/nng_ipc_options.5.adoc
@@ -25,7 +25,6 @@ nng_ipc_options - IPC-specific options
 #define NNG_OPT_IPC_PEER_UID            "ipc:peer-uid"
 #define NNG_OPT_IPC_PEER_ZONEID         "ipc:peer-zoneid"
 #define NNG_OPT_IPC_PERMISSIONS         "ipc:permissions"
-#define NNG_OPT_IPC_SECURITY_DESCRIPTOR "ipc:security-descriptor"
 ----
 
 == DESCRIPTION
@@ -75,6 +74,7 @@ permission.
 
 [[NNG_OPT_IPC_SECURITY_DESCRIPTOR]]((`NNG_OPT_IPC_SECURITY_DESCRIPTOR`))::
 (`PSECURITY_DESCRIPTOR`)
+TODO: REWRITE THIS TO REFLECT new nng_listener_get_security_security_descriptor.
 This write-only option may be used on listeners on Windows platforms to
 configure the `SECURITY_DESCRIPTOR` that is used when creating the underlying
 named pipe.
diff --git a/docs/ref/migrate/nng1.md b/docs/ref/migrate/nng1.md
index eac60379..152c464b 100644
--- a/docs/ref/migrate/nng1.md
+++ b/docs/ref/migrate/nng1.md
@@ -209,4 +209,15 @@ accessors functions are provided:
 - `u_host` is removed - use [`nng_url_hostname`] and [`nng_url_port`] to construct if needed
 - `u_rawurl` is removed - a "cooked" URL can be obtained from the new [`nng_url_sprintf`] function.
 
+## Security Descriptors (Windows Only)
+
+The `NNG_OPT_IPC_SECURITY_DESCRIPTOR` option is removed, and replaced
+with the functions [`nng_listener_get_security_descriptor`] and
+[`nng_stream_listener_get_security_descriptor`].
+
+Security descriptor support is only relevant to Windows,
+and is presently only supported for IPC when Named Pipes are used.
+Planned future changes to switch to UNIX domain sockets may eliminate
+support for security descriptors altogether in NNG.
+
 {{#include ../xref.md}}
diff --git a/docs/ref/tran/ipc.md b/docs/ref/tran/ipc.md
index c186cadd..ec0a2700 100644
--- a/docs/ref/tran/ipc.md
+++ b/docs/ref/tran/ipc.md
@@ -67,9 +67,9 @@ prevent unauthorized access, or that checks against the peer credentials are mad
 
 ### Socket Address
 
-When using an [`nng_sockaddr`][sockaddr] structure,
-the actual structure is of type [`nng_sockaddr_ipc`][sockaddr_ipc],
-except for abstract sockets, which use [`nng_sockaddr_abstract`][sockaddr_abstract].
+When using an [`nng_sockaddr`] structure,
+the actual structure is of type [`nng_sockaddr_ipc`],
+except for abstract sockets, which use [`nng_sockaddr_abstract`].
 
 ### Transport Options
 
@@ -77,7 +77,6 @@ The following transport options are supported by this transport,
 where supported by the underlying platform.
 
 - [`NNG_OPT_IPC_PERMISSIONS`][NNG_OPT_IPC_PERMISSIONS]
-- [`NNG_OPT_IPC_SECURITY_DESCRIPTOR`][NNG_OPT_IPC_SECURITY_DESCRIPTOR]
 - [`NNG_OPT_LOCADDR`][NNG_OPT_LOCADDR]
 - [`NNG_OPT_REMADDR`][NNG_OPT_REMADDR]
 - [`NNG_OPT_PEER_GID`][NNG_OPT_PEER_GID]
@@ -85,14 +84,10 @@ where supported by the underlying platform.
 - [`NNG_OPT_PEER_UID`][NNG_OPT_PEER_UID]
 - [`NNG_OPT_PEER_ZONEID`][NNG_OPT_PEER_ZONEID]
 
-[NNG_OPT_IPC_PERMISSIONS]: TODO.md
-[NNG_OPT_IPC_SECURITY_DESCRIPTOR]: TODO.md
-[NNG_OPT_LOCADDR]: TODO.md
-[NNG_OPT_REMADDR]: TODO.md
-[NNG_OPT_PEER_GID]: TODO.md
-[NNG_OPT_PEER_PID]: TODO.md
-[NNG_OPT_PEER_UID]: TODO.md
-[NNG_OPT_PEER_ZONEID]: TODO.md
-[sockaddr]: TODO.md
-[sockaddr_ipc]: TODO.md
-[sockaddr_abstract]: TODO.md
+### Other Configuration Parameters
+
+On Windows systems, the security descriptor for the listener,
+which can be used to control access, can be set using the function
+[`nng_listener_set_security_descriptor`].
+
+{{#include ../xref.md}}
diff --git a/docs/ref/xref.md b/docs/ref/xref.md
index 5e030bed..d5b7c9f0 100644
--- a/docs/ref/xref.md
+++ b/docs/ref/xref.md
@@ -100,6 +100,7 @@
 [`nng_dialer_get_url`]: /TODO.md
 [`nng_tls_config`]: /TODO.md
 [`nng_tls_config_own_cert`]: /TODO.md
+[`nng_listener_set_security_descriptor`]: /TODO.md
 
 <!-- Macros -->