Barracuda Application Server C/C++ Reference
Native APIs, integration guides, and platform interfaces
SharkTrustX.h
Go to the documentation of this file.
1/*
2 * ____ _________ __ _
3 * / __ \___ ____ _/ /_ __(_)___ ___ ___ / / ____ ____ _(_)____
4 * / /_/ / _ \/ __ `/ / / / / / __ `__ \/ _ \/ / / __ \/ __ `/ / ___/
5 * / _, _/ __/ /_/ / / / / / / / / / / / __/ /___/ /_/ / /_/ / / /__
6 * /_/ |_|\___/\__,_/_/ /_/ /_/_/ /_/ /_/\___/_____/\____/\__, /_/\___/
7 * /____/
8 *
9 * Barracuda Embedded Web-Server
10 ****************************************************************************
11 * PROGRAM MODULE
12 *
13 * $Id$
14 *
15 * COPYRIGHT: Real Time Logic LLC, 2026
16 *
17 * This software is copyrighted by and is the sole property of Real
18 * Time Logic LLC. All rights, title, ownership, or other interests in
19 * the software remain the property of Real Time Logic LLC. This
20 * software may only be used in accordance with the terms and
21 * conditions stipulated in the corresponding license agreement under
22 * which the software has been supplied. Any unauthorized use,
23 * duplication, transmission, distribution, or disclosure of this
24 * software is expressly forbidden.
25 *
26 * This Copyright notice may not be removed or modified without prior
27 * written consent of Real Time Logic LLC.
28 *
29 * Real Time Logic LLC. reserves the right to modify this software
30 * without notice.
31 *
32 * https://realtimelogic.com
33 ****************************************************************************
34 */
35
36#ifndef SharkTrustX_h
37#define SharkTrustX_h
38
39#include <HttpServer.h>
40#include <BaTimer.h>
41#include <IoIntf.h>
42#include <SharkSSL.h>
43#include <stddef.h>
44
66#ifdef __cplusplus
67extern "C" {
68#endif
69
74typedef enum SharkTrustX_Code
75{
87
94typedef int (*SharkTrustX_Proof)(const unsigned char* message,
95 size_t messageLen, unsigned char proof[32]);
96
105typedef void (*SharkTrustX_Event)(void* context, int code);
106
115typedef void (*SharkTrustX_Name)(void* context, const char* name, size_t length);
116
122typedef struct SharkTrustX_Config
123{
127 SharkSsl* clientSsl;
128 const char* portalDomain;
129 const unsigned char* zoneKey;
131 const char* name;
134 const char* directoryUrl;
137 const char* email;
139 const char* interfaceName;
147 void* context;
149
161BA_API int SharkTrustX_start(const SharkTrustX_Config* config);
162
166typedef struct SharkTrustX_Status
167{
176
187
197BA_API int SharkTrustX_setIpAddress(const char* address);
198
215BA_API int SharkTrustX_clean(IoIntf* io, BaBool all,
216 SharkTrustX_Event onClean, void* context);
217
218#ifdef __cplusplus
219}
220#endif
221#endif
struct SharkTrustX_Status SharkTrustX_Status
Snapshot of the certificate currently served by the managed listeners.
int(* SharkTrustX_Proof)(const unsigned char *message, size_t messageLen, unsigned char proof[32])
Compute the portal proof using generated tokengen code.
Definition: SharkTrustX.h:94
struct SharkTrustX_Config SharkTrustX_Config
Required integration objects and provisioning information.
void(* SharkTrustX_Event)(void *context, int code)
Receive one numeric event.
Definition: SharkTrustX.h:105
BA_API int SharkTrustX_setIpAddress(const char *address)
Ask the active client to publish a changed local IPv4 address.
BA_API BaBool SharkTrustX_getStatus(SharkTrustX_Status *status)
Copy current certificate status without network or storage operations.
SharkTrustX_Code
Numeric lifecycle notifications and errors.
Definition: SharkTrustX.h:75
@ SharkTrustX_Storage
Cannot read, commit, or clean local state.
Definition: SharkTrustX.h:80
@ SharkTrustX_Retry
A retry follows the preceding negative event.
Definition: SharkTrustX.h:77
@ SharkTrustX_Identity
Saved identity, name, or provider mismatch.
Definition: SharkTrustX.h:79
@ SharkTrustX_Acme
ACME account, order, or authorization failure.
Definition: SharkTrustX.h:82
@ SharkTrustX_Crypto
Allocation, key, signing, or listener failure.
Definition: SharkTrustX.h:84
@ SharkTrustX_Busy
A client or cleanup already owns the lifecycle.
Definition: SharkTrustX.h:78
@ SharkTrustX_Terms
Public CA terms were not accepted.
Definition: SharkTrustX.h:85
@ SharkTrustX_Portal
Invalid configuration or portal/DNS failure.
Definition: SharkTrustX.h:81
@ SharkTrustX_Ready
Usable certificate installed; renewal scheduled.
Definition: SharkTrustX.h:76
@ SharkTrustX_Trust
HTTPS peer did not pass trust/name/date checks.
Definition: SharkTrustX.h:83
BA_API int SharkTrustX_start(const SharkTrustX_Config *config)
Start registration, certificate installation, and automatic renewal.
void(* SharkTrustX_Name)(void *context, const char *name, size_t length)
Receive the portal-confirmed DNS name, independently of HTTPS readiness.
Definition: SharkTrustX.h:115
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.
uint16_t U16
Unsigned 16-bit integer.
Definition: GenPrimT.h:91
S64 BaTime
An arithmetic type representing calendar time with epoch of 1970-01-01 00:00:00 UTC,...
Definition: GenPrimT.h:103
U8 BaBool
Boolean stored in an unsigned byte; FALSE is zero and TRUE is one.
Definition: GenPrimT.h:118
Timer manager used for one-shot and periodic callbacks.
Definition: BaTimer.h:67
The Web Server.
Definition: HttpServer.h:3393
The IoIntf class specifies an abstract file API, implementations include ZipIo, DiskIo,...
Definition: IoIntf.h:482
Required integration objects and provisioning information.
Definition: SharkTrustX.h:123
const char * name
Preferred hostname label, 1..63 ASCII letters/digits/hyphens; no leading/trailing hyphen.
Definition: SharkTrustX.h:131
U16 port
Required unused HTTPS port, 1..65535, normally 443.
Definition: SharkTrustX.h:143
const char * interfaceName
Optional bind address passed to both listener attempts; NULL selects all interfaces.
Definition: SharkTrustX.h:139
BaBool acceptTerms
Must be TRUE publicly; ignored privately.
Definition: SharkTrustX.h:138
SharkTrustX_Name onName
Optional confirmed-name callback, or NULL.
Definition: SharkTrustX.h:146
BaTimer * timer
Required dedicated timer using the server's mutex.
Definition: SharkTrustX.h:125
const char * email
Required contact email in public builds; ignored privately.
Definition: SharkTrustX.h:137
SharkSsl * clientSsl
Required client TLS context with trusted CA list.
Definition: SharkTrustX.h:127
const unsigned char * zoneKey
Required borrowed 32-byte tokengen zone key.
Definition: SharkTrustX.h:129
const char * portalDomain
Required tokengen domain only, without scheme/path.
Definition: SharkTrustX.h:128
SharkTrustX_Proof proof
Required tokengen proof callback.
Definition: SharkTrustX.h:130
HttpServer * server
Required initialized server with running dispatcher.
Definition: SharkTrustX.h:124
void * context
Optional borrowed application pointer for both callbacks.
Definition: SharkTrustX.h:147
SharkTrustX_Event onEvent
Optional status callback, or NULL.
Definition: SharkTrustX.h:145
const char * directoryUrl
Required absolute HTTPS ACME directory in public builds.
Definition: SharkTrustX.h:134
IoIntf * io
Required private writable state store; see Store keys and enrollment safely.
Definition: SharkTrustX.h:126
Snapshot of the certificate currently served by the managed listeners.
Definition: SharkTrustX.h:167
BaBool ready
TRUE when at least one listener has an unexpired certificate.
Definition: SharkTrustX.h:168
BaTime expires
Certificate expiry, UTC Unix seconds; zero if not ready.
Definition: SharkTrustX.h:170
BaTime renew
Renewal due time, UTC Unix seconds; zero if not ready.
Definition: SharkTrustX.h:171