<p><b>@miri64</b> requested changes on this pull request.</p>

<p>Only reviewed the API and its documentation so far. Not the more general documentation on top.</p><hr>

<p>In <a href="https://github.com/RIOT-OS/RIOT/pull/11909#discussion_r309276911">sys/include/net/sock/dtls.h</a>:</p>
<pre style='color:#555'>> +#include <stdlib.h>
+#include <sys/types.h>
+
+#include "net/sock.h"
+#include "net/sock/udp.h"
+#include "net/credman.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief   Type for a DTLS sock object
+ *
+ * @note    API implementors: `struct sock_dtls` needs to be defined by
+ *          implementation-specific `sock_dtls_types.h`.
</pre>
⬇️ Suggested change
<pre style="color: #555">- *          implementation-specific `sock_dtls_types.h`.
+ *          an implementation-specific `sock_dtls_types.h`.
</pre>

<p>or</p>
⬇️ Suggested change
<pre style="color: #555">- *          implementation-specific `sock_dtls_types.h`.
+ *          the implementation-specific `sock_dtls_types.h`.
</pre>


<hr>

<p>In <a href="https://github.com/RIOT-OS/RIOT/pull/11909#discussion_r309280610">sys/include/net/sock/dtls.h</a>:</p>
<pre style='color:#555'>> +
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief   Type for a DTLS sock object
+ *
+ * @note    API implementors: `struct sock_dtls` needs to be defined by
+ *          implementation-specific `sock_dtls_types.h`.
+ */
+typedef struct sock_dtls sock_dtls_t;
+
+/**
+ * @brief Information about the established session with
+ *        the remote endpoint. Used when sending and
</pre>
<p>Typically a <code>@brief</code> is only one sentence. More information can be added to the <code>@details</code> section (which is implicitly created for non-specified paragraphs):</p>
⬇️ Suggested change
<pre style="color: #555">- *        the remote endpoint. Used when sending and
+ *        the remote endpoint.
+ *
+ * This session object is used when sending and receiving data to the endpoint.
</pre>

<p>However, this information is somewhat obvious (as you don't do much else with a <code>sock</code>) so maybe the last sentence can be dropped completely.</p>

<hr>

<p>In <a href="https://github.com/RIOT-OS/RIOT/pull/11909#discussion_r309280952">sys/include/net/sock/dtls.h</a>:</p>
<pre style='color:#555'>> + * @brief   Type for a DTLS sock object
+ *
+ * @note    API implementors: `struct sock_dtls` needs to be defined by
+ *          implementation-specific `sock_dtls_types.h`.
+ */
+typedef struct sock_dtls sock_dtls_t;
+
+/**
+ * @brief Information about the established session with
+ *        the remote endpoint. Used when sending and
+ *        receiving data to the endpoint
+ */
+typedef struct sock_dtls_session sock_dtls_session_t;
+
+/**
+ * @brief Must be called once before any other use
</pre>
<p>Exactly once or at least once? Who typically calls it? Why do I need to call it?</p>

<hr>

<p>In <a href="https://github.com/RIOT-OS/RIOT/pull/11909#discussion_r309281510">sys/include/net/sock/dtls.h</a>:</p>
<pre style='color:#555'>> + * @brief Information about the established session with
+ *        the remote endpoint. Used when sending and
+ *        receiving data to the endpoint
+ */
+typedef struct sock_dtls_session sock_dtls_session_t;
+
+/**
+ * @brief Must be called once before any other use
+ */
+void sock_dtls_init(void);
+
+/**
+ * @brief Creates a new DTLS sock object
+ *
+ * @param[out] sock     The resulting DTLS sock object
+ * @param[in] udp_sock  Existing UDP sock to be used
</pre>
⬇️ Suggested change
<pre style="color: #555">- * @param[in] udp_sock  Existing UDP sock to be used
+ * @param[in] udp_sock  Existing UDP sock to be used underneath
</pre>

<p>?</p>

<hr>

<p>In <a href="https://github.com/RIOT-OS/RIOT/pull/11909#discussion_r309281739">sys/include/net/sock/dtls.h</a>:</p>
<pre style='color:#555'>> + *        the remote endpoint. Used when sending and
+ *        receiving data to the endpoint
+ */
+typedef struct sock_dtls_session sock_dtls_session_t;
+
+/**
+ * @brief Must be called once before any other use
+ */
+void sock_dtls_init(void);
+
+/**
+ * @brief Creates a new DTLS sock object
+ *
+ * @param[out] sock     The resulting DTLS sock object
+ * @param[in] udp_sock  Existing UDP sock to be used
+ * @param[in] tag       Credential tag of the sock. Used to get the right
</pre>
<p>What does "right" mean in this context?</p>

<hr>

<p>In <a href="https://github.com/RIOT-OS/RIOT/pull/11909#discussion_r309281924">sys/include/net/sock/dtls.h</a>:</p>
<pre style='color:#555'>> +void sock_dtls_init(void);
+
+/**
+ * @brief Creates a new DTLS sock object
+ *
+ * @param[out] sock     The resulting DTLS sock object
+ * @param[in] udp_sock  Existing UDP sock to be used
+ * @param[in] tag       Credential tag of the sock. Used to get the right
+ *                      credential from pool.
+ * @param[in] method    Defines the method for the client or server to use.
+ *
+ * @return  0 on success.
+ * @return  value < 0 on error
+ */
+int sock_dtls_create(sock_dtls_t *sock, sock_udp_t *udp_sock,
+                     credman_tag_t tag,unsigned method);
</pre>
⬇️ Suggested change
<pre style="color: #555">-                     credman_tag_t tag,unsigned method);
+                     credman_tag_t tag, unsigned method);
</pre>


<hr>

<p>In <a href="https://github.com/RIOT-OS/RIOT/pull/11909#discussion_r309282245">sys/include/net/sock/dtls.h</a>:</p>
<pre style='color:#555'>> +/**
+ * @brief Must be called once before any other use
+ */
+void sock_dtls_init(void);
+
+/**
+ * @brief Creates a new DTLS sock object
+ *
+ * @param[out] sock     The resulting DTLS sock object
+ * @param[in] udp_sock  Existing UDP sock to be used
+ * @param[in] tag       Credential tag of the sock. Used to get the right
+ *                      credential from pool.
+ * @param[in] method    Defines the method for the client or server to use.
+ *
+ * @return  0 on success.
+ * @return  value < 0 on error
</pre>
<p>What values? Please specify, it might be important for the user to know.</p>

<hr>

<p>In <a href="https://github.com/RIOT-OS/RIOT/pull/11909#discussion_r309282530">sys/include/net/sock/dtls.h</a>:</p>
<pre style='color:#555'>> + */
+typedef struct sock_dtls_session sock_dtls_session_t;
+
+/**
+ * @brief Must be called once before any other use
+ */
+void sock_dtls_init(void);
+
+/**
+ * @brief Creates a new DTLS sock object
+ *
+ * @param[out] sock     The resulting DTLS sock object
+ * @param[in] udp_sock  Existing UDP sock to be used
+ * @param[in] tag       Credential tag of the sock. Used to get the right
+ *                      credential from pool.
+ * @param[in] method    Defines the method for the client or server to use.
</pre>
<p>What kind of method are you referring to here?</p>

<hr>

<p>In <a href="https://github.com/RIOT-OS/RIOT/pull/11909#discussion_r309283043">sys/include/net/sock/dtls.h</a>:</p>
<pre style='color:#555'>> + * @param[in] tag       Credential tag of the sock. Used to get the right
+ *                      credential from pool.
+ * @param[in] method    Defines the method for the client or server to use.
+ *
+ * @return  0 on success.
+ * @return  value < 0 on error
+ */
+int sock_dtls_create(sock_dtls_t *sock, sock_udp_t *udp_sock,
+                     credman_tag_t tag,unsigned method);
+
+/**
+ * @brief Initialises the server to listen for incoming connections
+ *
+ * @param[in] sock      DTLS sock to listen to
+ */
+void sock_dtls_init_server(sock_dtls_t *sock);
</pre>
<p>In accordance with <code>gnrc_tcp</code>: maybe name it <code>gnrc_dtls_listen()</code>? Not sure, if we already talked about this <g-emoji class="g-emoji" alias="sweat_smile" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f605.png">😅</g-emoji>...</p>

<hr>

<p>In <a href="https://github.com/RIOT-OS/RIOT/pull/11909#discussion_r309283322">sys/include/net/sock/dtls.h</a>:</p>
<pre style='color:#555'>> + * @brief Initialises the server to listen for incoming connections
+ *
+ * @param[in] sock      DTLS sock to listen to
+ */
+void sock_dtls_init_server(sock_dtls_t *sock);
+
+/**
+ * @brief Establish DTLS session to a server. Execute the handshake step in
+ *        DTLS.
+ *
+ * @param[in]  sock     DLTS sock to use
+ * @param[in]  ep       Endpoint to establish session with
+ * @param[out] remote   The established session, cannot be NULL
+ *
+ * @return  0 on success
+ * @return  value < 0 on other errors
</pre>
<p>Are there more than the ones defined below? If yes, define them instead of being vague.</p>

<hr>

<p>In <a href="https://github.com/RIOT-OS/RIOT/pull/11909#discussion_r309283501">sys/include/net/sock/dtls.h</a>:</p>
<pre style='color:#555'>> + *
+ * @return  0 on success.
+ * @return  value < 0 on error
+ */
+int sock_dtls_create(sock_dtls_t *sock, sock_udp_t *udp_sock,
+                     credman_tag_t tag,unsigned method);
+
+/**
+ * @brief Initialises the server to listen for incoming connections
+ *
+ * @param[in] sock      DTLS sock to listen to
+ */
+void sock_dtls_init_server(sock_dtls_t *sock);
+
+/**
+ * @brief Establish DTLS session to a server. Execute the handshake step in
</pre>
<p>One sentence per <code>@brief</code></p>

<hr>

<p>In <a href="https://github.com/RIOT-OS/RIOT/pull/11909#discussion_r309284638">sys/include/net/sock/dtls.h</a>:</p>
<pre style='color:#555'>> + * @return  -EINVAL, if sock_udp_ep_t::addr of @p remote->ep is an
+ *          invalid address.
+ * @return  -EINVAL, if sock_udp_ep_t::port of @p remote->ep is 0.
+ * @return  -ENOMEM, if no memory was available to send @p data.
+ */
+ssize_t sock_dtls_send(sock_dtls_t *sock, sock_dtls_session_t *remote,
+                       const void *data, size_t len);
+
+/**
+ * @brief Destroys DTLS sock created by `sock_dtls_create`
+ *
+ * @pre `(sock != NULL)`
+ *
+ * @param sock          DTLS sock to destroy
+ */
+void sock_dtls_destroy(sock_dtls_t *sock);
</pre>
⬇️ Suggested change
<pre style="color: #555">-void sock_dtls_destroy(sock_dtls_t *sock);
+void sock_dtls_close(sock_dtls_t *sock);
</pre>

<p>to be in line with the other <code>sock</code> APIs?</p>

<hr>

<p>In <a href="https://github.com/RIOT-OS/RIOT/pull/11909#discussion_r309285255">sys/include/net/sock/dtls.h</a>:</p>
<pre style='color:#555'>> + * @return  -ENOBUFS, if buffer space is not large enough to store received
+ *          credentials.
+ * @return  -ETIMEDOUT, if timed out when trying to establish session.
+ */
+int sock_dtls_establish_session(sock_dtls_t *sock, sock_udp_ep_t *ep,
+                                sock_dtls_session_t *remote);
+
+/**
+ * @brief Close an existing DTLS session
+ *
+ * @pre `(sock != NULL) && (ep != NULL)`
+ *
+ * @param[in] sock      @ref sock_dtls_t, which the session is established on
+ * @param[in] remote    Remote session to close
+ */
+void sock_dtls_close_session(sock_dtls_t *sock, sock_dtls_session_t *remote);
</pre>
<p>Not to be confused with <code>sock_dtls_close()</code> (in case we rename <code>sock_dtls_destroy()</code>) how about naming this then <code>sock_dtls_term_session</code> or <code>sock_dtls_terminate_session()</code> to avoid confusion.</p>

<hr>

<p>In <a href="https://github.com/RIOT-OS/RIOT/pull/11909#discussion_r309285677">sys/include/net/sock/dtls.h</a>:</p>
<pre style='color:#555'>> + * @brief Close an existing DTLS session
+ *
+ * @pre `(sock != NULL) && (ep != NULL)`
+ *
+ * @param[in] sock      @ref sock_dtls_t, which the session is established on
+ * @param[in] remote    Remote session to close
+ */
+void sock_dtls_close_session(sock_dtls_t *sock, sock_dtls_session_t *remote);
+
+/**
+ * @brief Decrypts and reads a message from a remote peer.
+ *
+ * @param[in] sock      DTLS sock to use.
+ * @param[out] remote   Remote DTLS session of the received data.
+ *                      Cannot be NULL.
+ * @param[out] data     Buffer where the data should be stored.
</pre>
<p>What kind of data?</p>

<hr>

<p>In <a href="https://github.com/RIOT-OS/RIOT/pull/11909#discussion_r309286177">sys/include/net/sock/dtls.h</a>:</p>
<pre style='color:#555'>> + * @pre `(sock != NULL) && (ep != NULL)`
+ *
+ * @param[in] sock      @ref sock_dtls_t, which the session is established on
+ * @param[in] remote    Remote session to close
+ */
+void sock_dtls_close_session(sock_dtls_t *sock, sock_dtls_session_t *remote);
+
+/**
+ * @brief Decrypts and reads a message from a remote peer.
+ *
+ * @param[in] sock      DTLS sock to use.
+ * @param[out] remote   Remote DTLS session of the received data.
+ *                      Cannot be NULL.
+ * @param[out] data     Buffer where the data should be stored.
+ * @param[in] maxlen    Maximum memory available at @p data.
+ * @param[in] timeout   Timeout for receive in microseconds.
</pre>
⬇️ Suggested change
<pre style="color: #555">- * @param[in] timeout   Timeout for receive in microseconds.
+ * @param[in] timeout   Receive timeout in microseconds.
</pre>


<hr>

<p>In <a href="https://github.com/RIOT-OS/RIOT/pull/11909#discussion_r309286469">sys/include/net/sock/dtls.h</a>:</p>
<pre style='color:#555'>> +
+/**
+ * @brief Decrypts and reads a message from a remote peer.
+ *
+ * @param[in] sock      DTLS sock to use.
+ * @param[out] remote   Remote DTLS session of the received data.
+ *                      Cannot be NULL.
+ * @param[out] data     Buffer where the data should be stored.
+ * @param[in] maxlen    Maximum memory available at @p data.
+ * @param[in] timeout   Timeout for receive in microseconds.
+ *                      If 0 and no data is available, the function returns
+ *                      immediately.
+ *                      May be SOCK_NO_TIMEOUT to wait until data
+ *                      is available.
+ *
+ * @note Function may block if data not available and @p timeout != 0
</pre>
⬇️ Suggested change
<pre style="color: #555">- * @note Function may block if data not available and @p timeout != 0
+ * @note Function may block if data is not available and @p timeout != 0
</pre>


<hr>

<p>In <a href="https://github.com/RIOT-OS/RIOT/pull/11909#discussion_r309286743">sys/include/net/sock/dtls.h</a>:</p>
<pre style='color:#555'>> + * @return  -ENOMEM, if no memory was available to receive @p data.
+ * @return  -ETIMEDOUT, if @p timeout expired.
+ */
+ssize_t sock_dtls_recv(sock_dtls_t *sock, sock_dtls_session_t *remote,
+                       void *data, size_t maxlen, uint32_t timeout);
+
+/**
+ * @brief Encrypts and sends a message to a remote peer
+ *
+ * @param[in] sock      DTLS sock to use
+ * @param[in] remote    DTLS session to use. A new session will be established
+ *                      if no session exist between client and server.
+ * @param[in] data      Pointer where the data to be send are stored
+ * @param[in] len       Length of @p data to be send
+ *
+ * @note Function may block
</pre>
<p>In which cases does it block?</p>

<p style="font-size:small;-webkit-text-size-adjust:none;color:#666;">—<br />You are receiving this because you are subscribed to this thread.<br />Reply to this email directly, <a href="https://github.com/RIOT-OS/RIOT/pull/11909?email_source=notifications&email_token=ABE7WYAP3ZNL5YA7KCZ6XV3QCGVY7A5CNFSM4IGRA3OKYY3PNVWWK3TUL52HS4DFWFIHK3DMKJSXC5LFON2FEZLWNFSXPKTDN5WW2ZLOORPWSZGOCAE6OGY#pullrequestreview-269084443">view it on GitHub</a>, or <a href="https://github.com/notifications/unsubscribe-auth/ABE7WYDRCBQJI6LC5C45HE3QCGVY7ANCNFSM4IGRA3OA">mute the thread</a>.<img src="https://github.com/notifications/beacon/ABE7WYCR4UQLFG6WD6NP42DQCGVY7A5CNFSM4IGRA3OKYY3PNVWWK3TUL52HS4DFWFIHK3DMKJSXC5LFON2FEZLWNFSXPKTDN5WW2ZLOORPWSZGOCAE6OGY.gif" height="1" width="1" alt="" /></p>
<script type="application/ld+json">[
{
"@context": "http://schema.org",
"@type": "EmailMessage",
"potentialAction": {
"@type": "ViewAction",
"target": "https://github.com/RIOT-OS/RIOT/pull/11909?email_source=notifications\u0026email_token=ABE7WYAP3ZNL5YA7KCZ6XV3QCGVY7A5CNFSM4IGRA3OKYY3PNVWWK3TUL52HS4DFWFIHK3DMKJSXC5LFON2FEZLWNFSXPKTDN5WW2ZLOORPWSZGOCAE6OGY#pullrequestreview-269084443",
"url": "https://github.com/RIOT-OS/RIOT/pull/11909?email_source=notifications\u0026email_token=ABE7WYAP3ZNL5YA7KCZ6XV3QCGVY7A5CNFSM4IGRA3OKYY3PNVWWK3TUL52HS4DFWFIHK3DMKJSXC5LFON2FEZLWNFSXPKTDN5WW2ZLOORPWSZGOCAE6OGY#pullrequestreview-269084443",
"name": "View Pull Request"
},
"description": "View this Pull Request on GitHub",
"publisher": {
"@type": "Organization",
"name": "GitHub",
"url": "https://github.com"
}
}
]</script>