git.seregonwar.com

include/pal_tls.h

1	/*
2	* pal_tls.h — TLS session abstraction (mbedTLS backend)
3	*
4	* Thin opaque layer used by pal_curl for HTTPS.
5	* Wraps mbedTLS state; exposes send/recv primitives that match pal_curl's I/O model.
6	*
7	* Certificate verification is DISABLED by default (no system CA store on PS4/PS5).
8	* Enable it by supplying a PEM CA bundle in pal_tls_cfg_t.ca_chain_pem.
9	*
10	* ── mbedTLS version ──────────────────────────────────────────────────────
11	* Targets mbedTLS 3.x. For mbedTLS 2.x define PAL_MBEDTLS_2X before including.
12	*
13	* ── Thread-safety ────────────────────────────────────────────────────────
14	* NOT thread-safe. Call pal_tls_global_init() once from the main thread
15	* before spawning threads that use TLS.
16	*/
17
18	#ifndef PAL_TLS_H
19	#define PAL_TLS_H
20
21	#include <stddef.h>
22	#include <stdint.h>
23
24	#ifdef __cplusplus
25	extern "C" {
26	#endif
27
28	/* ── Error codes ─────────────────────────────────────────────────────── */
29	#define PAL_TLS_OK 0
30	#define PAL_TLS_ERR_PARAM -1
31	#define PAL_TLS_ERR_NOMEM -2
32	#define PAL_TLS_ERR_HANDSHAKE -3
33	#define PAL_TLS_ERR_SEND -4
34	#define PAL_TLS_ERR_RECV -5
35	#define PAL_TLS_ERR_CERT -6
36	#define PAL_TLS_ERR_INIT -7
37
38	/* ── Configuration ───────────────────────────────────────────────────── */
39	typedef struct {
40	const char hostname; /< SNI + cert CN; must not be NULL. /
41	const char ca_chain_pem; /< PEM CA bundle; NULL disables verification. /
42	int verify_peer; /*< Non-zero to require cert validation. /
43	} pal_tls_cfg_t;
44
45	/* ── Opaque session ──────────────────────────────────────────────────── */
46	typedef struct pal_tls_session pal_tls_session_t;
47
48	/* ── Global lifecycle (one call per process) ─────────────────────────── */
49
50	/**
51	* @brief Seed the global CSPRNG used by all TLS sessions.
52	*
53	* Must complete before the first pal_tls_connect(). Idempotent.
54	*
55	* @return PAL_TLS_OK or PAL_TLS_ERR_INIT.
56	*
57	* @note Thread-safety: NOT thread-safe; call before spawning TLS threads.
58	*/
59	int pal_tls_global_init(void);
60
61	/** Counterpart to pal_tls_global_init(). */
62	void pal_tls_global_cleanup(void);
63
64	/* ── Session lifecycle ───────────────────────────────────────────────── */
65
66	/**
67	* @brief Perform a TLS client handshake on an existing connected TCP socket.
68	*
69	* Caller retains ownership of fd; does NOT close it on failure.
70	*
71	* @param[in] fd Connected, blocking TCP socket.
72	* @param[in] cfg Non-NULL config; cfg->hostname must not be NULL.
73	*
74	* @return New session on success, NULL on any failure.
75	*
76	* @pre fd is connected and blocking.
77	* @post On success the session is ready for pal_tls_send/recv.
78	*
79	* @note Thread-safety: NOT thread-safe.
80	* @note WCET: unbounded (network).
81	*/
82	pal_tls_session_t pal_tls_connect(int fd, const pal_tls_cfg_t cfg);
83
84	/**
85	* @brief Send exactly len bytes through a TLS session.
86	*
87	* Retries on MBEDTLS_ERR_SSL_WANT_WRITE.
88	*
89	* @return Bytes written (> 0), or negative PAL_TLS_ERR_*.
90	*
91	* @note Thread-safety: NOT thread-safe.
92	*/
93	int pal_tls_send(pal_tls_session_t sess, const void buf, size_t len);
94
95	/**
96	* @brief Receive up to len bytes from a TLS session.
97	*
98	* Returns 0 on clean peer closure.
99	*
100	* @note Thread-safety: NOT thread-safe.
101	*/
102	int pal_tls_recv(pal_tls_session_t sess, void buf, size_t len);
103
104	/**
105	* @brief Send close_notify and free all session resources.
106	*
107	* Does NOT close the underlying fd. Safe on NULL.
108	*
109	* @note Thread-safety: NOT thread-safe.
110	*/
111	void pal_tls_close(pal_tls_session_t *sess);
112
113	#ifdef __cplusplus
114	}
115	#endif
116	#endif /* PAL_TLS_H */
117

Seregon/zftpd