SharkTrustX.h File Reference

Detailed Description

Automatic certificates for one native BWS HTTPS port.

Start with the SharkTrustX C Client manual for certificate basics, a C integration example, build requirements, storage, and cleanup. The runnable example is in examples/SharkTrustX/readme.html.

Compile BWS.c with SHARKTRUSTX, BA_JSON=1, and SHARKSSL_ENABLE_CERTINFO_PARSE_API=1. BWS includes the client and its dependencies; do not compile SharkTrustX.c separately. Compile the portal's generated tokengen.c with TOKENGEN_C_API.

One client manages one HTTPS port, using IPv6 first and then IPv4 when USE_IPV6 is enabled. Hold the server dispatcher mutex when calling this API; never call from an interrupt. Keep configuration and borrowed objects alive and unchanged until successful cleanup completes. start() acceptance is separate from certificate readiness. clean() erases state and is not a normal shutdown operation. Saved keys are UNENCRYPTED: the supplied IoIntf must be private and must never be served over HTTP.

#include <HttpServer.h>
#include <BaTimer.h>
#include <IoIntf.h>
#include <SharkSSL.h>
#include <stddef.h>

Include dependency graph for SharkTrustX.h:

Go to the source code of this file.

Classes
struct	SharkTrustX_Config
	Required integration objects and provisioning information. More...
struct	SharkTrustX_Status
	Snapshot of the certificate currently served by the managed listeners. More...

Typedefs
typedef enum SharkTrustX_Code	SharkTrustX_Code
	Numeric lifecycle notifications and errors. More...
typedef int(*	SharkTrustX_Proof) (const unsigned char *message, size_t messageLen, unsigned char proof[32])
	Compute the portal proof using generated tokengen code. More...
typedef void(*	SharkTrustX_Event) (void *context, int code)
	Receive one numeric event. More...
typedef void(*	SharkTrustX_Name) (void *context, const char *name, size_t length)
	Receive the portal-confirmed DNS name, independently of HTTPS readiness. More...
typedef struct SharkTrustX_Config	SharkTrustX_Config
	Required integration objects and provisioning information. More...
typedef struct SharkTrustX_Status	SharkTrustX_Status
	Snapshot of the certificate currently served by the managed listeners. More...

Enumerations
enum	SharkTrustX_Code {   SharkTrustX_Ready = 1 , SharkTrustX_Retry = 2 , SharkTrustX_Busy = -1 , SharkTrustX_Identity = -2 ,   SharkTrustX_Storage = -3 , SharkTrustX_Portal = -4 , SharkTrustX_Acme = -5 , SharkTrustX_Trust = -6 ,   SharkTrustX_Crypto = -7 , SharkTrustX_Terms = -9 }
	Numeric lifecycle notifications and errors. More...

Functions
BA_API int	SharkTrustX_start (const SharkTrustX_Config *config)
	Start registration, certificate installation, and automatic renewal. More...
BA_API BaBool	SharkTrustX_getStatus (SharkTrustX_Status *status)
	Copy current certificate status without network or storage operations. More...
BA_API int	SharkTrustX_setIpAddress (const char *address)
	Ask the active client to publish a changed local IPv4 address. More...
BA_API int	SharkTrustX_clean (IoIntf *io, BaBool all, SharkTrustX_Event onClean, void *context)
	Stop work, close the managed listener, and erase owned certificate state. More...

Typedef Documentation

SharkTrustX_Code

typedef enum SharkTrustX_Code SharkTrustX_Code

Numeric lifecycle notifications and errors.

Zero is an accepted start/cleanup/address request, or successful cleanup completion. getStatus() instead returns a BaBool indicating active management.

SharkTrustX_Config

typedef struct SharkTrustX_Config SharkTrustX_Config

Required integration objects and provisioning information.

Initialize to zero, then set required members. All pointers and strings are borrowed until successful cleanup completes, including the config itself. Do not modify them while management or cleanup is active. See

1. Configure the client

.

SharkTrustX_Event

typedef void(* SharkTrustX_Event) (void *context, int code)

Receive one numeric event.

Parameters

context	Application pointer from configuration or clean().
code	A SharkTrustX_Code; a cleanup callback receives 0 or a negative error. No keys or credentials are passed to callbacks. onEvent runs on the timer worker with the dispatcher mutex held. onClean uses that worker for active cleanup, or runs inline for an inactive store. Keep callbacks short and nonblocking. See Read status and handle callbacks .

SharkTrustX_Name

typedef void(* SharkTrustX_Name) (void *context, const char *name, size_t length)

Receive the portal-confirmed DNS name, independently of HTTPS readiness.

Parameters

context	Application pointer from configuration.
name	Borrowed, NUL-terminated full DNS name, valid during this call; NULL for an IP-only SharkCA enrollment. Copy it if needed after returning.
length	DNS name length in bytes, or zero for IP-only enrollment. Called once after confirmation on each start, then only when the name changes. A SharkCA host must arrange its own .local mDNS advertisement.

SharkTrustX_Proof

typedef int(* SharkTrustX_Proof) (const unsigned char *message, size_t messageLen, unsigned char proof[32])

Compute the portal proof using generated tokengen code.

Parameters

message	Borrowed binary input, possibly containing zero bytes.
messageLen	Number of input bytes, not strlen(message).
proof	Required output buffer for exactly 32 bytes.

Returns

Zero on success, nonzero on failure. Do not retain input pointers.

SharkTrustX_Status

typedef struct SharkTrustX_Status SharkTrustX_Status

Snapshot of the certificate currently served by the managed listeners.

This value contains no pointers or private key material.

Enumeration Type Documentation

SharkTrustX_Code

enum SharkTrustX_Code

Numeric lifecycle notifications and errors.

Zero is an accepted start/cleanup/address request, or successful cleanup completion. getStatus() instead returns a BaBool indicating active management.

Enumerator
SharkTrustX_Ready	Usable certificate installed; renewal scheduled.
SharkTrustX_Retry	A retry follows the preceding negative event.
SharkTrustX_Busy	A client or cleanup already owns the lifecycle.
SharkTrustX_Identity	Saved identity, name, or provider mismatch.
SharkTrustX_Storage	Cannot read, commit, or clean local state.
SharkTrustX_Portal	Invalid configuration or portal/DNS failure.
SharkTrustX_Acme	ACME account, order, or authorization failure.
SharkTrustX_Trust	HTTPS peer did not pass trust/name/date checks.
SharkTrustX_Crypto	Allocation, key, signing, or listener failure.
SharkTrustX_Terms	Public CA terms were not accepted.

Function Documentation

SharkTrustX_clean()

BA_API int SharkTrustX_clean	(	IoIntf *	io,
		BaBool	all,
		SharkTrustX_Event	onClean,
		void *	context
	)

Stop work, close the managed listener, and erase owned certificate state.

Parameters

io	Required store used by the active client, or an inactive store.
all	TRUE also removes portal enrollment; FALSE retains completed or pending enrollment. SharkCA also retains its bound account key/directory; public builds remove account/provider state, permitting a provider change.
onClean	Optional completion callback; may run before return if idle.
context	Optional borrowed pointer for onClean.

Returns

0 when accepted, -1 for a conflicting cleanup/store, -3 for NULL io. Active issuance does not prevent cleanup. Completion code 0 guarantees no old callback, persistence write, or listener install can follow. On failure management stays stopped and start remains blocked until cleanup succeeds. A durable reset marker finishes interrupted cleanup before state can be restored. Acceptance does not report storage success; inspect onClean's code. See

1. Clean state or change configuration

for retained state and a clean-then-start example.

SharkTrustX_getStatus()

BA_API BaBool SharkTrustX_getStatus

(

SharkTrustX_Status *

status

)

Copy current certificate status without network or storage operations.

Parameters

status

Required caller-owned output; all fields are overwritten.

Returns

TRUE while the client manages certificates, including initial enrollment without a certificate. FALSE before start, during cleanup, or after failed cleanup; all output fields are then zero. Hold the server dispatcher mutex, including when called from a web page. Calling from onEvent is allowed. The copied value remains owned by the caller, but may become stale after releasing the mutex.

SharkTrustX_setIpAddress()

BA_API int SharkTrustX_setIpAddress

(

const char *

address

)

Ask the active client to publish a changed local IPv4 address.

Parameters

address

Dotted IPv4 string, copied before returning; NULL discovers the address of the next trusted portal connection. No periodic address discovery is performed. The host calls this after a network change.

Returns

0 when queued, -1 without active management, -4 for invalid IPv4. Changes are serialized with issuance. SharkCA identifier changes trigger reissuance. Failures use the configured numeric event callback. A successful address update alone does not emit a certificate-ready event.

SharkTrustX_start()

BA_API int SharkTrustX_start

(

const SharkTrustX_Config *

config

)

Start registration, certificate installation, and automatic renewal.

Parameters

config

Required configuration retained until cleanup completes.

Returns

0 when accepted; a negative SharkTrustX_Code for immediate rejection. Acceptance does not mean HTTPS is ready. Subsequent errors are delivered via onEvent and retried. Saved identity changes require cleanup, never automatic re-enrollment. Provisioning and directory identity are checked before use. With USE_IPV6, certificate installation tries IPv6 first, then IPv4 on the same port, sharing one TLS context. Otherwise it tries only IPv4. Successful listeners are retained; installation fails if neither opens. The platform determines whether an IPv6 socket also accepts IPv4 connections.