include/boost/corosio/openssl_stream.hpp

93.3% Lines (14 / 15) 50.0% Branches (19 / 38) 100.0% Functions (11 / 11)

[ ] prev/next file n p prev/next uncovered line

openssl_stream.hpp

f(x) Functions (11)

Function Calls Lines Branches Blocks

Line	Branch	Hits	Source Code
1			//
2			// Copyright (c) 2025 Vinnie Falco ([email protected])
3			// Copyright (c) 2026 Michael Vandeberg
4			// Copyright (c) 2026 Steve Gerbino
5			//
6			// Distributed under the Boost Software License, Version 1.0. (See accompanying
7			// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
8			//
9			// Official repository: https://github.com/cppalliance/corosio
10			//
11
12			#ifndef BOOST_COROSIO_OPENSSL_STREAM_HPP
13			#define BOOST_COROSIO_OPENSSL_STREAM_HPP
14
15			#include <boost/corosio/detail/config.hpp>
16			#include <boost/corosio/tls_context.hpp>
17			#include <boost/corosio/tls_stream.hpp>
18			#include <boost/capy/detail/buffer_array.hpp>
19			#include <boost/capy/concept/stream.hpp>
20			#include <boost/capy/io/any_stream.hpp>
21			#include <boost/capy/results.hpp>
22			#include <boost/capy/task.hpp>
23
24			#include <concepts>
25			#include <memory>
26			#include <system_error>
27			#include <tuple>
28
29			namespace boost::corosio {
30
31			/** Encrypts and decrypts a stream using OpenSSL.
32
33			This class wraps an underlying stream satisfying `capy::Stream`
34			and provides TLS encryption using the OpenSSL library.
35
36			Derives from @ref tls_stream to provide a runtime-polymorphic
37			interface. The TLS operations are implemented as coroutines
38			that orchestrate reads and writes on the underlying stream.
39
40			@par Construction Modes
41
42			Two construction modes are supported:
43
44			- Owning: Pass stream by value. The `openssl_stream` takes
45			ownership. The stream is moved into internal storage.
46
47			- Reference: Pass stream by pointer. The `openssl_stream`
48			does not own the stream. The caller must ensure the stream
49			outlives this object.
50
51			@par Thread Safety
52			Distinct objects: Safe.@n
53			Shared objects: Unsafe, with one exception: one read operation and
54			one write operation may be in flight simultaneously. `shutdown()`
55			may overlap a pending read. On a multi-threaded execution context,
56			all operations on one stream must run within the same
57			`capy::strand`, or must otherwise never run concurrently. A
58			single-threaded context needs no strand.
59
60			@par Example
61			@par !example openssl_stream
62
63			@see @ref tls_stream, @ref wolfssl_stream
64			*/
65			class BOOST_COROSIO_DECL openssl_stream final : public tls_stream
66			{
67			struct implementation;
68			implementation* impl_;
69
70			public:
71			/** Construct an OpenSSL stream (owning mode).
72
73			Takes ownership of the underlying stream by moving it into
74			internal storage. The stream is destroyed when this
75			`openssl_stream` is destroyed.
76
77			@param stream The stream to take ownership of. Must satisfy
78			`capy::Stream` and must not be an `openssl_stream`; that
79			case binds to the move constructor instead.
80			@param ctx The TLS context containing configuration.
81			*/
82			template<capy::Stream S>
83			requires(!std::same_as<std::decay_t<S>, openssl_stream>)
84		12x	openssl_stream(S stream, tls_context const& ctx)
85	6/12 ✓ Branch 0 taken 4 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 4 times. ✗ Branch 3 not taken. ✓ Branch 4 taken 1 time. ✗ Branch 5 not taken. ✓ Branch 6 taken 1 time. ✗ Branch 7 not taken. ✓ Branch 8 taken 1 time. ✗ Branch 9 not taken. ✓ Branch 10 taken 1 time. ✗ Branch 11 not taken.	6x	: impl_(adopt(std::make_unique<S>(std::move(stream)), ctx))
86		12x	{
87		12x	}
88
89			/** Construct an OpenSSL stream (reference mode).
90
91			Wraps the underlying stream without taking ownership. The
92			caller must ensure the stream remains valid for the lifetime
93			of this `openssl_stream`.
94
95			@param stream Pointer to the stream to wrap. Must satisfy
96			`capy::Stream`.
97			@param ctx The TLS context containing configuration.
98			*/
99			template<capy::Stream S>
100		5624x	openssl_stream(S* stream, tls_context const& ctx)
101	10/20 ✓ Branch 0 taken 307 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 307 times. ✗ Branch 3 not taken. ✓ Branch 4 taken 2498 times. ✗ Branch 5 not taken. ✓ Branch 6 taken 2498 times. ✗ Branch 7 not taken. ✓ Branch 8 taken 1 time. ✗ Branch 9 not taken. ✓ Branch 10 taken 1 time. ✗ Branch 11 not taken. ✓ Branch 12 taken 1 time. ✗ Branch 13 not taken. ✓ Branch 14 taken 1 time. ✗ Branch 15 not taken. ✓ Branch 16 taken 5 times. ✗ Branch 17 not taken. ✓ Branch 18 taken 5 times. ✗ Branch 19 not taken.	2812x	: impl_(make_implementation(capy::any_stream(stream), {}, ctx))
102		5624x	{
103		2812x	}
104
105			/** Destroy the OpenSSL stream.
106
107			Operations still in flight complete with
108			`capy::error::canceled` without touching this object, and the
109			TLS state they need is released when the last of them
110			finishes. In owning mode the underlying stream is destroyed
111			when the last of those operations finishes. An underlying
112			stream with a `cancel()` member is told to cancel them now. In reference
113			mode, and for an owned stream without `cancel()`, an operation
114			parked on the underlying stream finishes when that stream's
115			operation does.
116			*/
117			~openssl_stream() override;
118
119			/** Move construct from another OpenSSL stream.
120
121			Operations in flight on @p other continue on this stream.
122
123			@param other The source stream. After the move,
124			@p other may only be destroyed or assigned to.
125			*/
126			openssl_stream(openssl_stream&& other) noexcept;
127
128			/** Move assign from another OpenSSL stream.
129
130			Operations in flight on this stream complete as if it were
131			destroyed; those on @p other continue on this stream.
132
133			@param other The source stream. After the move,
134			@p other may only be destroyed or assigned to.
135
136			@return `*this`.
137			*/
138			openssl_stream& operator=(openssl_stream&& other) noexcept;
139
140			/** Asynchronously perform the TLS handshake.
141
142			Suspends the calling coroutine until the handshake
143			completes, an error occurs, or the operation is
144			cancelled via stop token.
145
146			@pre The underlying stream must be connected. No other
147			TLS operation may be in progress on this stream.
148
149			@param role The handshake role, client or server.
150
151			@return An awaitable yielding `(error_code)`.
152			*/
153			[[nodiscard]] capy::task<capy::results<>> handshake(tls_role role) override;
154
155			/** Asynchronously shut down the TLS session.
156
157			Sends a close_notify alert and waits for the peer's
158			close_notify response. Supports cancellation via
159			stop token.
160
161			@pre A handshake must have completed successfully. May overlap
162			a pending read. That read completes with `capy::error::eof`
163			when the peer answers the close_notify. No concurrent write
164			may be in progress.
165
166			@par Postconditions
167			If the transport ends before the peer's close_notify is
168			received, the result is `capy::error::stream_truncated`, not
169			success. A shutdown stopped mid-flight reports canceled. Any
170			other transport error propagates unchanged.
171
172			@return An awaitable yielding `(error_code)`.
173			*/
174			[[nodiscard]] capy::task<capy::results<>> shutdown() override;
175
176			/// Cancel operations pending on the owned underlying stream.
177			void cancel() noexcept override;
178
179			/** Reset TLS session state for reuse.
180
181			Clears internal buffers and session data so the stream
182			can perform a new handshake on the same underlying
183			connection. The previous session is discarded and never
184			resumed, so a handshake after `reset()` is always a full
185			handshake.
186
187			@pre No TLS operation may be in progress on this stream.
188
189			@note If the backend cannot restore a clean session state,
190			subsequent handshakes fail rather than proceed on a
191			partially cleared session.
192			*/
193			void reset() override;
194
195			/** Set the peer hostname for SNI and certificate verification.
196
197			@param hostname The peer name to send as SNI and match against the
198			certificate.
199			*/
200			void set_hostname(std::string_view hostname) override;
201
202			/// Return the underlying stream.
203			capy::any_stream& next_layer() noexcept override;
204
205			/// Return the underlying stream.
206			capy::any_stream const& next_layer() const noexcept override;
207
208			/// Return the TLS backend name ("openssl").
209			std::string_view name() const noexcept override;
210
211			/// Return the ALPN protocol negotiated during the handshake, or empty.
212			std::string_view alpn_protocol() const noexcept override;
213
214			protected:
215			/// @copydoc tls_stream::do_read_some
216			capy::task<capy::results<std::size_t>> do_read_some(
217			capy::detail::mutable_buffer_array<capy::detail::max_iovec_> buffers)
218			override;
219
220			/// @copydoc tls_stream::do_write_some
221			capy::task<capy::results<std::size_t>> do_write_some(
222			capy::detail::const_buffer_array<capy::detail::max_iovec_> buffers)
223			override;
224
225			private:
226			static implementation* make_implementation(
227			capy::any_stream stream,
228			detail::tls_owned_transport owned,
229			tls_context const& ctx);
230
231			// The transport is boxed apart from the any_stream that refers to
232			// it, so it outlives any operation still parked on it after the
233			// stream is destroyed.
234			template<class S>
235			static implementation*
236		6x	adopt(std::unique_ptr<S> owned, tls_context const& ctx)
237			{
238	3/6 ✓ Branch 0 taken 4 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 1 time. ✗ Branch 3 not taken. ✓ Branch 4 taken 1 time. ✗ Branch 5 not taken.	6x	auto* impl = make_implementation(
239		6x	capy::any_stream(owned.get()),
240		6x	detail::make_owned_transport(owned.get()), ctx);
241		6x	std::ignore = owned.release();
242		6x	return impl;
243		✗	}
244			};
245
246			/** Return the error category for raw OpenSSL errors.
247
248			Errors reported by @ref openssl_stream that originate from the OpenSSL
249			error queue (`ERR_get_error`) are assigned this category. Its
250			`message()` decodes the packed OpenSSL error code using OpenSSL's own
251			diagnostic strings. Printing such an `error_code` therefore yields a
252			readable description, for example "certificate verify failed".
253
254			OpenSSL errors whose library is `ERR_LIB_SYS` are reported with
255			`std::system_category()` instead, since their reason code is a genuine
256			`errno` value.
257
258			@return A reference to a static category object with name
259			`"corosio.openssl"`.
260			*/
261			BOOST_COROSIO_DECL std::error_category const& openssl_category() noexcept;
262
263			} // namespace boost::corosio
264
265			#endif
266