From 6182ffa1d46d7592c5bca9e345e46165a6d0efda Mon Sep 17 00:00:00 2001 From: Cory McWilliams Date: Wed, 28 Feb 2024 19:12:41 -0500 Subject: [PATCH] Docs for tls.h and trace.h. --- src/tls.h | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++ src/trace.h | 75 +++++++++++++++++++++++++++++- 2 files changed, 201 insertions(+), 2 deletions(-) diff --git a/src/tls.h b/src/tls.h index 4fe79c74..84c93f9f 100644 --- a/src/tls.h +++ b/src/tls.h @@ -9,9 +9,19 @@ #include #include +/** +** A TLS context. May have many tf_tls_session_t instances. +*/ typedef struct _tf_tls_context_t tf_tls_context_t; + +/** +** A TLS session. Belongs to one tf_tls_context_t and represents a single connection. +*/ typedef struct _tf_tls_session_t tf_tls_session_t; +/** +** The state of a TLS handshake. +*/ typedef enum _tf_tls_handshake_t { k_tls_handshake_done, @@ -19,31 +29,149 @@ typedef enum _tf_tls_handshake_t k_tls_handshake_failed, } tf_tls_handshake_t; +/** +** Possible error statuses from tf_tls_session_read_plain. +*/ typedef enum _tf_tls_read_t { k_tls_read_zero = -1, k_tls_read_failed = -2, } tf_tls_read_t; +/** +** Create a TLS context. Clean up with tf_tls_context_destroy(). +** @return A new TLS context. +*/ tf_tls_context_t* tf_tls_context_create(); + +/** +** Set the TLS context's server certificate. +** @param context The TLS context. +** @param certificate The certificate in PEM format. +** @return true if set successfully. +*/ bool tf_tls_context_set_certificate(tf_tls_context_t* context, const char* certificate); + +/** +** Set the TLS context's server certificate's private key. +** @param context The TLS context. +** @param private_key The private key in PEM format. +** @return true if set successfully. +*/ bool tf_tls_context_set_private_key(tf_tls_context_t* context, const char* private_key); + +/** +** Add a trusted certificate. +** @param context The TLS context. +** @param certificate The certificate in PEM format. +** @return true if the certificate was added to the trusted list successfully. +*/ bool tf_tls_context_add_trusted_certificate(tf_tls_context_t* context, const char* certificate); + +/** +** Create a TLS session from a context. Once created, call +** tf_tls_session_handshake() until it returns k_tls_handshake_done. Call +** tf_tls_session_[read/write]_[plain/encrypted]() as data is available. +** @param context The TLS context. Clean up with tf_tls_session_destroy(). +** @return A new TLS session. +*/ tf_tls_session_t* tf_tls_context_create_session(tf_tls_context_t* context); + +/** +** Destroy a TLS context. +** @param context The TLS contextx created by tf_tls_context_create(). +*/ void tf_tls_context_destroy(tf_tls_context_t* context); +/** +** Destroy a TLS session. +** @param session A TLS sesssion created by tf_tls_context_create_session(). +*/ void tf_tls_session_destroy(tf_tls_session_t* session); + +/** +** Set the remote hostname for a session. +** @param session The TLS session. +** @param hostname The hostname. +*/ void tf_tls_session_set_hostname(tf_tls_session_t* session, const char* hostname); + +/** +** Begin an outgoing TLS session. +** @param session The TLS session. +*/ void tf_tls_session_start_accept(tf_tls_session_t* session); + +/** +** Begin an incoming TLS session. +** @param session The TLS session. +*/ void tf_tls_session_start_connect(tf_tls_session_t* session); + +/** +** Begin the clean shutdown process for a TLS session. +** @param session The TLS session. +*/ void tf_tls_session_shutdown(tf_tls_session_t* session); + +/** +** Get the certificate from the remote end of a TLS session if available. +** @param session The TLS session. +** @param buffer A buffer to receive the certificate. +** @param bytes The size of the buffer. +** @return The size of the returned certificate, or -1 on failure. +*/ int tf_tls_session_get_peer_certificate(tf_tls_session_t* session, char* buffer, size_t bytes); + +/** +** Update the TLS handshake. Call repeatedly as new data is available until it returns done. +** @param session The TLS session. +** @return The current state of the handshake process. +*/ tf_tls_handshake_t tf_tls_session_handshake(tf_tls_session_t* session); +/** +** Read decrypted data from the TLS session. +** @param session The TLS session. +** @param buffer A buffer to receive the data. +** @param bytes The size of the buffer. +** @return The number of bytes returned. +*/ int tf_tls_session_read_plain(tf_tls_session_t* session, char* buffer, size_t bytes); + +/** +** Write unencrypted data to the TLS session. +** @param session The TLS session. +** @param buffer The data to encrypt. +** @param bytes The size of the data. +** @return 1 on success, 0 on failure. +*/ int tf_tls_session_write_plain(tf_tls_session_t* session, const char* buffer, size_t bytes); + +/** +** Read encrypted data from the TLS session that needs to be sent. +** @param session The TLS session. +** @param buffer A buffer to receive the data. +** @param bytes The size of the buffer. +** @return The number of bytes returned. +*/ int tf_tls_session_read_encrypted(tf_tls_session_t* session, char* buffer, size_t bytes); + +/** +** Write encrypted data to the TLS session. +** @param session The TLS session. +** @param buffer The encrypted data. +** @param bytes The number of bytes written. +*/ int tf_tls_session_write_encrypted(tf_tls_session_t* session, const char* buffer, size_t bytes); + +/** +** Retrieve the last error from a TLS session. +** @param session The TLS session. +** @param buffer A buffer to receive the error text. +** @param bytes The size of the buffer. +** @return true if an error was retrieved. +*/ bool tf_tls_session_get_error(tf_tls_session_t* session, char* buffer, size_t bytes); /** @} */ diff --git a/src/trace.h b/src/trace.h index bffb7ecf..b28bd28a 100644 --- a/src/trace.h +++ b/src/trace.h @@ -3,32 +3,103 @@ /** ** \defgroup trace Performance Tracing ** Generates trace output that is compatible with speedscope.app, -** chrome://tracing or ui.perfetto.dev for scrutining what each thread is doing -** for optimization purposes. +** chrome://tracing or ui.perfetto.dev for scrutinizing what each thread is +** doing for optimization purposes. ** @{ */ #include #include +/** +** A trace instance. +*/ typedef struct _tf_trace_t tf_trace_t; + +/** +** An SQLite database instance. +*/ typedef struct sqlite3 sqlite3; +/** +** Create a trace instance. Can be used to produce a Chrome trace event +** document for analyzing performance. Clean up with tf_trace_destroy(). +** @return A trace instance. +*/ tf_trace_t* tf_trace_create(); + +/** +** Destroy a trace instance that was created with tf_trace_create(). +*/ void tf_trace_destroy(tf_trace_t* trace); +/** +** Set the name of the current process. +** @param trace The trace instance. +** @param name The name of the process. +*/ void tf_trace_set_process_name(tf_trace_t* trace, const char* name); +/** +** Record counter values. +** @param trace The trace instance. +** @param name The counter group name. +** @param argc The number of counters. +** @param arg_names The counter names. +** @param arg_values The counter values. +*/ void tf_trace_counter(tf_trace_t* trace, const char* name, int argc, const char** arg_names, const int64_t* arg_values); + +/** +** Begin tracing a time interval. End with tf_trace_end(). +** @param trace The trace instance. +** @param name The interval name. +*/ void tf_trace_begin(tf_trace_t* trace, const char* name); + +/** +** End tracing the next time interval previously started with tf_trace_begin(). +** @param trace The trace instance. +*/ void tf_trace_end(tf_trace_t* trace); +/** +** Export all currently stored trace data to a string. +** @param trace The trace instance. +** @return A string representation of the trace data. +*/ char* tf_trace_export(tf_trace_t* trace); +/** +** A callback to collect trace data. +** @param trace The trace instance. +** @param buffer The trace data. +** @param size The size of the trace data. +** @param user_data User data registered with the callback. +*/ typedef void(tf_trace_write_callback_t)(tf_trace_t* trace, const char* buffer, size_t size, void* user_data); + +/** +** Replace the trace recording behavior. +** @param trace The trace instance. +** @param callback A callback that will be called instead of collecting the trace data in a buffer. +** @param user_data User data to pass to the callback. +*/ void tf_trace_set_write_callback(tf_trace_t* trace, tf_trace_write_callback_t* callback, void* user_data); + +/** +** Inject raw trace data. +** @param trace The trace instance. +** @param buffer The trace data. +** @param size The size of the trace data. +*/ void tf_trace_raw(tf_trace_t* trace, const char* buffer, size_t size); +/** +** Register for trace-worthy events from sqlite and record them going forward. +** @param trace The trace instance. +** @param sqlite The SQLite database. +*/ void tf_trace_sqlite(tf_trace_t* trace, sqlite3* sqlite); /** @} */