Commit cc80d6a2 authored by Rémi Denis-Courmont's avatar Rémi Denis-Courmont

tls: improve documentation

parent 5d92e169
......@@ -23,8 +23,11 @@
# define VLC_TLS_H
/**
* \ingroup sockets
* \defgroup tls Transport Layer Security
* @{
* \file
* This file defines Transport Layer Security API (TLS) in vlc
* Transport Layer Security (TLS) functions
*/
# include <vlc_network.h>
......@@ -43,9 +46,28 @@ struct vlc_tls
struct virtual_socket_t sock;
};
/**
* Initiates a client TLS session.
*
* Performs client side of TLS handshake through a connected socket, and
* establishes a secure channel. This is a blocking network operation.
*
* @param fd socket through which to establish the secure channel
* @param hostname expected server name, used both as Server Name Indication
* and as expected Common Name of the peer certificate
* @param service unique identifier for the service to connect to
* (only used locally for certificates database)
* @param alpn NULL-terminated list of Application Layer Protocols
* to negotiate, or NULL to not negotiate protocols
* @param alp storage space for the negotiated Application Layer
* Protocol or NULL if negotiation was not performed[OUT]
*
* @return TLS session, or NULL on error.
**/
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_tls_t *vlc_tls_SessionCreate (vlc_tls_creds_t *, int fd, const char *host,
const char *const *alpn);
int vlc_tls_SessionHandshake (vlc_tls_t *, const char *host, const char *serv,
......@@ -74,9 +96,37 @@ struct vlc_tls_creds
void (*close) (vlc_tls_t *);
};
/**
* Allocates TLS credentials for a client.
* Credentials can be cached and reused across multiple TLS sessions.
*
* @return TLS credentials object, or NULL on error.
**/
VLC_API vlc_tls_creds_t *vlc_tls_ClientCreate (vlc_object_t *);
/**
* Allocates server TLS credentials.
*
* @param cert_path required (Unicode) path to an x509 certificate,
* if NULL, anonymous key exchange will be used.
* @param key_path (UTF-8) path to the PKCS private key for the certificate,
* if NULL; cert_path will be used.
*
* @return TLS credentials object, or NULL on error.
*/
vlc_tls_creds_t *vlc_tls_ServerCreate (vlc_object_t *,
const char *cert, const char *key);
/**
* Releases TLS credentials.
*
* Releases data allocated with vlc_tls_ClientCreate() or
* vlc_tls_ServerCreate().
*
* @param srv object to be destroyed (or NULL)
*/
VLC_API void vlc_tls_Delete (vlc_tls_creds_t *);
/** @} */
#endif
......@@ -73,16 +73,6 @@ static void tls_unload(void *func, va_list ap)
deactivate (crd);
}
/**
* Allocates a whole server's TLS credentials.
*
* @param cert_path required (Unicode) path to an x509 certificate,
* if NULL, anonymous key exchange will be used.
* @param key_path (UTF-8) path to the PKCS private key for the certificate,
* if NULL; cert_path will be used.
*
* @return NULL on error.
*/
vlc_tls_creds_t *
vlc_tls_ServerCreate (vlc_object_t *obj, const char *cert_path,
const char *key_path)
......@@ -107,12 +97,6 @@ vlc_tls_ServerCreate (vlc_object_t *obj, const char *cert_path,
return srv;
}
/**
* Allocates TLS credentials for a client.
* Credentials can be cached and reused across multiple TLS sessions.
*
* @return TLS credentials object, or NULL on error.
**/
vlc_tls_creds_t *vlc_tls_ClientCreate (vlc_object_t *obj)
{
vlc_tls_creds_t *crd = vlc_custom_create (obj, sizeof (*crd),
......@@ -132,11 +116,6 @@ vlc_tls_creds_t *vlc_tls_ClientCreate (vlc_object_t *obj)
return crd;
}
/**
* Releases data allocated with vlc_tls_ClientCreate() or
* vlc_tls_ServerCreate().
* @param srv TLS server object to be destroyed, or NULL
*/
void vlc_tls_Delete (vlc_tls_creds_t *crd)
{
if (crd == NULL)
......@@ -180,22 +159,6 @@ void vlc_tls_SessionDelete (vlc_tls_t *session)
vlc_object_release (session);
}
/**
* Performs client side of TLS handshake through a connected socket, and
* establishes a secure channel. This is a blocking network operation.
*
* @param fd socket through which to establish the secure channel
* @param hostname expected server name, used both as Server Name Indication
* and as expected Common Name of the peer certificate
* @param service unique identifier for the service to connect to
* (only used locally for certificates database)
* @param alpn NULL-terminated list of Application Layer Protocols
* to negotiate, or NULL to not negotiate protocols
* @param alp storage space for the negotiated Application Layer
* Protocol or NULL if negotiation was not performed[OUT]
*
* @return NULL on error.
**/
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)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment