HttpSharkSslServCon.h File Reference

Detailed Description

SharkSSL listener and transport adapter.

Asynchronous sending: legacy and current API

The adapter implements the existing SoDispCon asynchronous API for TLS client and server connections. HttpConnection uses the same operations. The newer SharkSSL handshake-output and KeyUpdate APIs are handled inside the adapter; application callers continue using the interfaces below.

Use an established TLS connection with a completed handshake. Serialize access using the connection's dispatcher mutex and allow only one writer. Select nonblocking socket mode for sending from dispatcher callbacks.

Borrowed buffer and return values

SoDispCon_allocAsynchBuf() returns a borrowed void* and writes the available capacity, in bytes, to the required int* size argument. The TLS adapter reports its existing encryption-buffer capacity; it does not allocate a new buffer or resize it to the requested size. A zero input size is also supported for TLS capacity queries. Always check the pointer and use the returned capacity. NULL with size zero can mean the connection is busy, including pending TLS output; it does not necessarily mean out of memory.

Obtaining the pointer does not reserve the connection or start a send. Repeated lookups and capacity-only queries are allowed while idle, including before an ordinary synchronous write. The pointer belongs to the TLS connection and must not be freed or used after that connection is destroyed. TLS processing can change its contents. Fill it immediately before sending, without intervening operations that use the same connection's TLS buffers.

SoDispCon_asyncSend(con, len) starts a new block when no send is pending. The int len is the payload length in bytes, from 1 through the returned capacity. Encryption occurs in place, so the plaintext contents need not survive the call. SoDispCon_asyncReady(con), or asyncSend with len zero, advances pending output without starting another application block. Both operations return an int status, not a byte count:

• 1: Output is complete and the buffer can be refilled. This means transport completion, not acknowledgement by the peer application.
• 0: Output remains pending. Keep the buffer unchanged and arrange a send-ready callback to continue. These calls do not register callbacks.
• A negative value: Transport error. Stop using the connection for sending and perform the owning application's error/close handling.

A block accepted by asyncSend must not be copied or submitted as a new block again when the result is zero. While that send is pending, a legacy call to asyncSend with a positive length also advances the existing output; its length does not describe additional data. Prefer asyncReady for continuation so the intent is explicit. Yield to the dispatcher when the result is zero; do not spin waiting for completion.

Legacy pattern: retain and reuse the buffer

1. Obtain the buffer and capacity once with SoDispCon_allocAsynchBuf().
2. Optionally call SoDispCon_asyncReady() before filling it. A successful readiness check does not invalidate the borrowed pointer.
3. Fill at most the returned capacity and call SoDispCon_asyncSend().
4. If the result is zero, keep the buffer unchanged and advance the send from send-ready callbacks until completion or error.
5. After result 1, refill the same buffer and send the next block. A new buffer lookup or explicit release between blocks is not required.

This supports callers such as the native file reader and tunnel code. Capacity lookup followed by synchronous output is also supported.

Current pattern: obtain the buffer per block

Callers such as the Lua nonblocking writer may obtain the buffer again for each new block. Complete the previous send first, obtain the pointer and capacity, fill it, and call SoDispCon_asyncSend(). Continue pending output exactly as in the legacy pattern. Both patterns use the same public API; reacquisition is optional and does not allocate a new TLS buffer.

During pending asynchronous output, buffer lookup and synchronous writes are rejected and TLS reads are deferred. Do not force the connection idle, release its send buffer, or alter its buffer contents to bypass this state. Completion permits the next operation; obtaining a pointer alone does not impose these restrictions.

The C macros and SoDispCon_asyncReadyF() preserve negative error results. The current C++ SoDispCon::asyncReady() wrapper converts the result to bool, so an error also becomes true. Use the C macro or function from C++ when distinguishing completion from failure.

New SharkSSL control-output API

TLS output can include handshake or KeyUpdate records in addition to application data. When asynchronous application output triggers a key update, result 1 is delayed until that control output has also been sent. A zero result can therefore remain after all application bytes have left the socket. Continue through the same send-ready path without refilling the buffer or resending the application block.

The adapter obtains control bytes with SharkSslCon_getHandshakeData() and SharkSslCon_getHandshakeDataLen(). After each valid transport send result it calls SharkSslCon_setHandshakeDataSent() with the actual U16 byte count, including a partial send, a complete send, or zero bytes. The remaining pointer and length are obtained again before the next send. Applications using the BAS transport must leave this accounting to the adapter.

SharkSslCon_isHandshakeComplete() returns U8: 0 means incomplete, 1 means complete, and 2 means complete with additional buffered input to process. The adapter continues processing buffered input for the latter case during handshake-only reads. These engine-level requirements do not introduce a per-block reservation requirement in the SoDispCon API.

#include <HttpServCon.h>
#include <BaServerLib.h>
#include <SharkSSL.h>
#include <string.h>
#include <DoubleList.h>

Include dependency graph for HttpSharkSslServCon.h:

Go to the source code of this file.

Classes
struct	HttpSharkSslServCon
	Create a SharkSSL server listen object. More...

Macros
#define	HttpSharkSslServCon_isValid(o)   HttpServCon_isValid((HttpServCon*)o)
#define	HttpSharkSslServCon_requestClientCert(o, enable)    (o)->requestClientCert=enable
	Store the listener's client-certificate request flag. More...
#define	HttpSharkSslServCon_favorRSA(o, enable)    (o)->favorRSA=enable
	Select the RSA certificate preference applied to newly accepted connections. More...

Typedefs
typedef struct HttpSharkSslServCon	HttpSharkSslServCon
	Create a SharkSSL server listen object. More...

Functions
SHARKSSL_API void	HttpSharkSslServCon_constructor (HttpSharkSslServCon *o, SharkSsl *sharkSsl, struct HttpServer *server, struct SoDisp *dispatcher, U16 port, BaBool setIP6, const void *interfaceName, HttpServCon_AcceptNewCon userDefinedAccept)
	Create a SharkSSL Server Connection. More...
SHARKSSL_API int	HttpSharkSslServCon_setPort (HttpSharkSslServCon *o, U16 portNumber, BaBool setIp6, const void *interfaceName)
	Open a replacement listener, then close the old listener on success. More...
SHARKSSL_API void	HttpSharkSslServCon_destructor (HttpSharkSslServCon *o)
	Close the listener and every accepted TLS connection still tracked by it. More...

Macro Definition Documentation

HttpSharkSslServCon_favorRSA

#define HttpSharkSslServCon_favorRSA	(		o,
			enable
	)		(o)->favorRSA=enable

Select the RSA certificate preference applied to newly accepted connections.

Parameters

[in,out]	o	Initialized listener.
[in]	enable	TRUE favors RSA, FALSE keeps the default selection. Existing TLS connections are unchanged. Set while holding the dispatcher mutex. Availability and selection details depend on the configured TLS engine.

HttpSharkSslServCon_isValid

#define HttpSharkSslServCon_isValid

(

o

)

HttpServCon_isValid((HttpServCon*)o)

Parameters

[in]

o

Initialized listener.

Returns

TRUE if its listening socket is valid, FALSE otherwise.

HttpSharkSslServCon_requestClientCert

#define HttpSharkSslServCon_requestClientCert	(		o,
			enable
	)		(o)->requestClientCert=enable

Store the listener's client-certificate request flag.

Parameters

[in,out]	o	Initialized listener.
[in]	enable	TRUE sets the flag, FALSE clears it.

Warning

The current accept implementation does not read this field. This macro alone does not request or require a client certificate.

Typedef Documentation

HttpSharkSslServCon

typedef struct HttpSharkSslServCon HttpSharkSslServCon

Create a SharkSSL server listen object.

The object binds itself to the SoDisp object and makes the web-server listen for new connections on the port specified. The default port is 443. You can create several of these objects and bind to the dispatcher if you want the web-server to listen to more than one port.

Function Documentation

HttpSharkSslServCon_constructor()

SHARKSSL_API void HttpSharkSslServCon_constructor	(	HttpSharkSslServCon *	o,
		SharkSsl *	sharkSsl,
		struct HttpServer *	server,
		struct SoDisp *	dispatcher,
		U16	port,
		BaBool	setIP6,
		const void *	interfaceName,
		HttpServCon_AcceptNewCon	userDefinedAccept
	)

Create a SharkSSL Server Connection.

Parameters

	sharkSsl	is the SharkSsl instance required for operating the server connection. You must make sure that this object is valid for the lifetime of the listener and its accepted connections. It must have role SharkSsl_Server and be configured before listening. An incorrect role violates the constructor precondition.
	server	Required borrowed server, valid throughout listener use.
	dispatcher	Required borrowed dispatcher, valid throughout use.
	port	TCP listen port in host byte order, normally 443. Zero initializes an inactive listener without opening a socket.
	setIP6	TRUE selects IPv6, FALSE IPv4. This parameter is ignored unless the underlying TCP/IP stack is a dual IP V4 and IP V6 stack.
	interfaceName	Borrowed platform binding address/interface, used during the call; normally a NUL-terminated address string. NULL binds the wildcard address. Accepted representation is platform-specific.
	userDefinedAccept	Same functionality as for HttpServCon, but this callback is for implementing secure servers. The temporary-connection ownership rules of HttpServCon_AcceptNewCon apply. The callback may run before the TLS handshake completes. It is required in NO_BA_SERVER builds; otherwise NULL selects HTTP handling.
[out]	o	Caller-owned listener storage.

HttpSharkSslServCon_destructor()

SHARKSSL_API void HttpSharkSslServCon_destructor

(

HttpSharkSslServCon *

o

)

Close the listener and every accepted TLS connection still tracked by it.

Parameters

[in,out]

o

Initialized listener; no borrowed dependency is freed.

HttpSharkSslServCon_setPort()

SHARKSSL_API int HttpSharkSslServCon_setPort	(	HttpSharkSslServCon *	o,
		U16	portNumber,
		BaBool	setIp6,
		const void *	interfaceName
	)

Open a replacement listener, then close the old listener on success.

Parameters

[in]	portNumber	New TCP port in host byte order, 1..65535.
[in]	setIp6	True selects IPv6, false IPv4 (default).
[in]	interfaceName	Borrowed platform binding address/interface, or NULL for wildcard; used during this call only.

Returns

Zero on success, -1 on failure. The old listener is retained if replacement setup fails. Uses the associated server's dispatcher. Hold the dispatcher mutex during this operation.

Parameters

[in,out]

o

Initialized listener.