From 806cd4fbbaa7ddd2d273658b683d50cb482ede7d Mon Sep 17 00:00:00 2001
From: Anthony Hu <anthony@wolfssl.com>
Date: Fri, 4 Mar 2022 15:32:11 -0500
Subject: [PATCH] doxygen for myUnknownExtCallback()

---
 doc/dox_comments/header_files/asn_public.h | 52 ++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/doc/dox_comments/header_files/asn_public.h b/doc/dox_comments/header_files/asn_public.h
index 97ca254f4..2c15c1cba 100644
--- a/doc/dox_comments/header_files/asn_public.h
+++ b/doc/dox_comments/header_files/asn_public.h
@@ -1937,3 +1937,55 @@ WOLFSSL_API int wc_SetTimeCb(wc_time_cb f);
     \sa wc_SetTimeCb
 */
 WOLFSSL_API time_t wc_Time(time_t* t);
+
+/*!
+    \ingroup ASN
+
+    \brief This function registers a callback that will be used anytime
+    wolfSSL encounters an unknown X.509 extension in a certificate while parsing
+    a certificate. The prototype of the callback should be:
+
+    \return 0 Returned on success.
+
+    \param cert the DecodedCert struct that is to be associated with this
+    callback.
+    \param cb function to register as the time callback.
+
+    _Example_
+    \code
+    int ret = 0;
+    // Unkown extension callback prototype
+    int myUnknownExtCallback(const word16* oid, word32 oidSz, int crit,
+                             const unsigned char* der, word32 derSz);
+
+    // Register it
+    ret = wc_SetUnknownExtCallback(cert, myUnknownExtCallback);
+    if (ret != 0) {
+        // failed to set the callback
+    }
+
+    // oid: Array of integers that are the dot separated values in an oid.
+    // oidSz: Number of values in oid.
+    // crit: Whether the extension was mark critical.
+    // der: The der encoding of the content of the extension.
+    // derSz: The size in bytes of the der encoding.
+    int myCustomExtCallback(const word16* oid, word32 oidSz, int crit,
+                            const unsigned char* der, word32 derSz) {
+
+        // Logic to parse extension goes here.
+
+        // NOTE: by returning zero, we are accepting this extension and
+        // informing wolfSSL that it is acceptable. If you find an extension
+        // that you do not find acceptable, you should return an error. The
+        // standard behavior upon encountering an unknown extension with the
+        // critical flag set is to return ASN_CRIT_EXT_E. For the sake of
+        // brevity, this example is always accepting every extension; you
+        // should use different logic.
+        return 0;
+    }
+    \endcode
+
+    \sa ParseCert
+*/
+WOLFSSL_ASN_API int wc_SetUnknownExtCallback(DecodedCert* cert,
+                                             wc_UnknownExtCallback cb);