tls: split server-specific session creation function...

...from common code. And document.

include/vlc_tls.h

@@ -73,9 +73,27 @@ VLC_API vlc_tls_t *vlc_tls_ClientSessionCreate (vlc_tls_creds_t *, int fd,
                                          const char *host, const char *service,
                                          const char *const *alpn, char **alp);
 
-VLC_API vlc_tls_t *vlc_tls_SessionCreate (vlc_tls_creds_t *, int fd,
-                                          const char *host,
-                                          const char *const *alpn);
+/**
+ * Creates a TLS server session.
+ *
+ * Allocates a Transport Layer Security (TLS) session as the server side, using
+ * cryptographic keys pair and X.509 certificates chain already loaded with
+ * vlc_tls_ServerCreate().
+ *
+ * Unlike vlc_tls_ClientSessionCreate(), this function does not perform any
+ * actual network I/O. vlc_tls_SessionHandshake() must be used to perform the
+ * TLS handshake before sending and receiving data through the TLS session.
+ *
+ * This function is non-blocking and is not a cancellation point.
+ *
+ * @param creds server credentials, i.e. keys pair and X.509 certificates chain
+ * @param alpn NULL-terminated list of Application Layer Protocols
+ *             to negotiate, or NULL to not negotiate protocols
+ *
+ * @return TLS session, or NULL on error.
+ */
+VLC_API vlc_tls_t *vlc_tls_ServerSessionCreate(vlc_tls_creds_t *creds, int fd,
+                                               const char *const *alpn);
 
 /**
  * Destroys a TLS session down.

src/libvlccore.sym

@@ -431,7 +431,7 @@ vlc_tls_ClientCreate
 vlc_tls_ServerCreate
 vlc_tls_Delete
 vlc_tls_ClientSessionCreate
-vlc_tls_SessionCreate
+vlc_tls_ServerSessionCreate
 vlc_tls_SessionDelete
 vlc_tls_Read
 vlc_tls_Write

src/network/httpd.c

@@ -2042,7 +2042,7 @@ static void httpdLoop(httpd_host_t *host)
         {
             const char *alpn[] = { "http/1.1", NULL };
 
-            p_tls = vlc_tls_SessionCreate(host->p_tls, fd, NULL, alpn);
+            p_tls = vlc_tls_ServerSessionCreate(host->p_tls, fd, alpn);
         }
         else
             p_tls = NULL;

src/network/tls.c

@@ -128,8 +128,9 @@ void vlc_tls_Delete (vlc_tls_creds_t *crd)
 
 /*** TLS  session ***/
 
-vlc_tls_t *vlc_tls_SessionCreate (vlc_tls_creds_t *crd, int fd,
-                                  const char *host, const char *const *alpn)
+static vlc_tls_t *vlc_tls_SessionCreate(vlc_tls_creds_t *crd, int fd,
+                                        const char *host,
+                                        const char *const *alpn)
 {
     vlc_tls_t *sock = vlc_tls_SocketOpen(VLC_OBJECT(crd), fd);
     if (unlikely(sock == NULL))
@@ -145,12 +146,15 @@ vlc_tls_t *vlc_tls_SessionCreate (vlc_tls_creds_t *crd, int fd,
     session->obj = crd->p_parent;
     session->p = sock;
 
-    int val = crd->open(crd, session, sock, host, alpn);
-    if (val != VLC_SUCCESS)
+    int canc = vlc_savecancel();
+
+    if (crd->open(crd, session, sock, host, alpn) != VLC_SUCCESS)
     {
         free(session);
-        session= NULL;
+        session = NULL;
     }
+
+    vlc_restorecancel(canc);
     return session;
 }
 
@@ -180,17 +184,13 @@ vlc_tls_t *vlc_tls_ClientSessionCreate (vlc_tls_creds_t *crd, int fd,
                                         const char *host, const char *service,
                                         const char *const *alpn, char **alp)
 {
-    vlc_tls_t *session;
-    int canc, val;
+    int val;
 
-    canc = vlc_savecancel();
-    session = vlc_tls_SessionCreate (crd, fd, host, alpn);
+    vlc_tls_t *session = vlc_tls_SessionCreate(crd, fd, host, alpn);
     if (session == NULL)
-    {
-        vlc_restorecancel(canc);
         return NULL;
-    }
 
+    int canc = vlc_savecancel();
     mtime_t deadline = mdate ();
     deadline += var_InheritInteger (crd, "ipv4-timeout") * 1000;
 
@@ -230,6 +230,12 @@ error:
     return session;
 }
 
+vlc_tls_t *vlc_tls_ServerSessionCreate(vlc_tls_creds_t *crd, int fd,
+                                       const char *const *alpn)
+{
+    return vlc_tls_SessionCreate(crd, fd, NULL, alpn);
+}
+
 ssize_t vlc_tls_Read(vlc_tls_t *session, void *buf, size_t len, bool waitall)
 {
     struct pollfd ufd;

test/modules/misc/tls.c

@@ -113,7 +113,7 @@ static int securepair(vlc_thread_t *th, vlc_tls_t **restrict client,
     val = tlspair(insecurev);
     assert(val == 0);
 
-    server = vlc_tls_SessionCreate(server_creds, insecurev[0], NULL, alpnv[0]);
+    server = vlc_tls_ServerSessionCreate(server_creds, insecurev[0], alpnv[0]);
     assert(server != NULL);
 
     val = vlc_clone(th, tls_echo, server, VLC_THREAD_PRIORITY_LOW);