Security

Cryptography, certificates, security policies, and the certificate store (client and server).

ua::EndpointSecurityContext

Sanitized, non-secret security context describing the negotiated endpoint.

This core value is constructed once after endpoint and token-policy selection, then shared unchanged by authentication, Role evaluation, namespace authorization and Session state.

Public attributes

MessageSecurityMode messageSecurityMode

Negotiated message security mode of the channel.

SecurityPolicyId securityPolicyId

Negotiated security policy of the channel.

std::string endpointPolicyId

Mandatory stable endpoint identifier, formatted as "{listenerName}/{endpointName}".

optional< std::string > userTokenPolicyId

UA UserTokenPolicy policyId selected by the stack, or empty if none applied.

String clientApplicationUri

Certificate-verified calling-client application URI, or empty on an unsecured channel.

String endpointUrl

Endpoint URL the client connected to.

String transportProfileUri

Transport profile URI of the negotiated channel.

ua::UserIdentity

Stable, SDK-owned identity bound to a Session after successful activation.

Public attributes

std::string userId

Stable identifier for the authenticated principal.

std::string displayName

Human-readable name for display and audit.

UserTokenKind kind

Token family used to authenticate the principal.

std::unordered_map< std::string, std::string > claims

Application-defined identity claims, keyed by claim name.

ua::CertificateValidationRequest

What one certificate validation is asked to establish (OPC 10000-4 section 6.1.3 Table 106): the certificate, the chain its holder presented, the use and security policy it is validated for and the identity it must carry.

Every path that validates a certificate builds one request and hands it to CertificateStore::validate_certificate_async; the store supplies the trust material (CertificateValidationMaterial) and the validator applies the steps. A member left empty is filled by the store or skipped, as each member states.

Public attributes

shared_ptr< const X509Certificate > certificate

The certificate to validate (the leaf of a presented chain). Must be non-null.

std::vector< shared_ptr< const X509Certificate > > presentedIssuers

The issuer certificates presented with certificate, in the order received (leaf excluded).

optional< CertificateUse > use

The use requested for the certificate (Table 106, Certificate Usage).

optional< SecurityPolicyId > policyId

The security policy the certificate and its chain must comply with (Table 106, Security Policy Check): key type and length, and signature algorithms, for the leaf and every issuer.

optional< std::string > applicationUri

The application URI the certificate's subjectAltName must carry, when set.

optional< std::string > endpointUrl

The endpoint URL whose host name the certificate must carry, when set (the client side of a connection).

optional< TrustListValidationOptions > options

Options for this validation.

std::vector< shared_ptr< const X509Certificate > > trustedForThisConnection

Certificates the application accepted for this connection only (client trust prompt, CL-SECADMIN-003 AcceptForThisSession).

ua::CertificateStore

Asynchronous PKI store of trusted, issuer, rejected and application certificates plus their CRLs.

Holds the four OPC UA trust-list groups (trusted, issuer, rejected) together with the application's own certificate/key pairs, and validates peer certificates against them. All mutating and querying operations are exposed as a *_async / sync / try_sync trio: the *_async overloads are the canonical, never-throwing surface that deliver a Result to a callback; the sync and try_sync wrappers block until the async operation completes.

Implementations serialize access internally, so callers may invoke any method from any thread. Callbacks run on an unspecified worker thread and must not block. Certificates and CRLs are held by shared_ptr<const>; ownership is shared and the stored objects are immutable. Instances are managed by shared_ptr (enable_shared_from_this); construct accordingly.

Member types

std::function< void(VoidResult)> CompleteCallback

Callback receiving the outcome of a mutating operation; carries an ErrorDetail on failure.

std::function< void(CertificateListResult)> GetCertificatesCallback

Callback receiving a CertificateList, or an ErrorDetail on failure.

std::function< void(CrlListResult)> GetCrlsCallback

Callback receiving a CrlList, or an ErrorDetail on failure.

Result< ApplicationCertificate > ApplicationCertificateResult

A single ApplicationCertificate, or an ErrorDetail on failure.

std::vector< ApplicationCertificate > ApplicationCertificateList

A list of the store's ApplicationCertificate entries.

Result< ApplicationCertificateList > ApplicationCertificateListResult

An ApplicationCertificateList, or an ErrorDetail on failure.

std::function< void(ApplicationCertificateResult)> GetApplicationCertificateCallback

Callback receiving a single ApplicationCertificate, or an ErrorDetail on failure.

std::function< void(ApplicationCertificateListResult)> GetApplicationCertificatesCallback

Callback receiving an ApplicationCertificateList, or an ErrorDetail on failure.

Functions

boost::asio::any_io_executor executor() const noexcept

The executor this store's operations complete on, which a *_sync call must not wait on from one of its threads (it refuses with Bad_WouldBlock instead).

Returns: The executor used for this store's asynchronous completions.

~CertificateStore()=default

void shutdown()

Gracefully shuts down the store, cancelling any background work such as refresh timers.

void add_to_application_certificates_async(ApplicationCertificate certificate, CompleteCallback callback) noexcept=0

Adds an application instance certificate and its key pair to the store.

• certificate (ApplicationCertificate) - The certificate, key pair and type to store; consumed by value.
• callback (CompleteCallback) - Receives the outcome; carries an ErrorDetail on failure. Never throws.

void get_application_certificate_async(CertificateType certificateType, GetApplicationCertificateCallback callback) const noexcept=0

Retrieves the application certificate matching the given certificate type.

• certificateType (CertificateType) - Cryptographic profile to look up.
• callback (GetApplicationCertificateCallback) - Receives the matching ApplicationCertificate, or an ErrorDetail if none is found. Never throws.

void get_application_certificates_async(GetApplicationCertificatesCallback callback) const noexcept=0

Retrieves all application certificates held by the store.

• callback (GetApplicationCertificatesCallback) - Receives the ApplicationCertificateList, or an ErrorDetail on failure. Never throws.

void add_to_trusted_certificates_async(shared_ptr< const X509Certificate > certificate, CompleteCallback callback) noexcept=0

Adds a certificate to the trusted list.

• certificate (shared_ptr< const X509Certificate >) - Certificate to trust; must be non-null.
• callback (CompleteCallback) - Receives the outcome; carries an ErrorDetail on failure. Never throws.

void add_to_trusted_certificates_async(std::vector< shared_ptr< const X509Certificate > > certificates, CompleteCallback callback) noexcept=0

Adds several certificates to the trusted list in one operation.

• certificates (std::vector< shared_ptr< const X509Certificate > >) - Certificates to trust; consumed by value.
• callback (CompleteCallback) - Receives the outcome; carries an ErrorDetail on failure. Never throws.

void get_trusted_certificates_async(GetCertificatesCallback callback) const noexcept=0

Retrieves the current trusted certificate list.

• callback (GetCertificatesCallback) - Receives the CertificateList, or an ErrorDetail on failure. Never throws.

void add_to_issuer_certificates_async(shared_ptr< const X509Certificate > certificate, CompleteCallback callback) noexcept=0

Adds a certificate to the issuer (intermediate CA) list.

• certificate (shared_ptr< const X509Certificate >) - Issuer certificate to store; must be non-null.
• callback (CompleteCallback) - Receives the outcome; carries an ErrorDetail on failure. Never throws.

void add_to_issuer_certificates_async(std::vector< shared_ptr< const X509Certificate > > certificates, CompleteCallback callback) noexcept=0

Adds several certificates to the issuer (intermediate CA) list in one operation.

• certificates (std::vector< shared_ptr< const X509Certificate > >) - Issuer certificates to store; consumed by value.
• callback (CompleteCallback) - Receives the outcome; carries an ErrorDetail on failure. Never throws.

void get_issuer_certificates_async(GetCertificatesCallback callback) const noexcept=0

Retrieves the current issuer certificate list.

• callback (GetCertificatesCallback) - Receives the CertificateList, or an ErrorDetail on failure. Never throws.

void add_to_rejected_certificates_async(shared_ptr< const X509Certificate > certificate, CompleteCallback callback) noexcept=0

Records a certificate that failed validation in the rejected list.

• certificate (shared_ptr< const X509Certificate >) - Certificate to record as rejected; must be non-null.
• callback (CompleteCallback) - Receives the outcome; carries an ErrorDetail on failure. Never throws.

void get_rejected_certificates_async(GetCertificatesCallback callback) const noexcept=0

Retrieves the current rejected certificate list.

• callback (GetCertificatesCallback) - Receives the CertificateList, or an ErrorDetail on failure. Never throws.

void add_to_trusted_crls_async(shared_ptr< const X509Crl > crl, CompleteCallback callback) noexcept=0

Adds a CRL to the trusted CRL set.

• crl (shared_ptr< const X509Crl >) - Revocation list to store; must be non-null.
• callback (CompleteCallback) - Receives the outcome; carries an ErrorDetail on failure. Never throws.

void add_to_trusted_crls_async(std::vector< shared_ptr< const X509Crl > > crls, CompleteCallback callback) noexcept=0

Adds several CRLs to the trusted CRL set in one operation.

• crls (std::vector< shared_ptr< const X509Crl > >) - Revocation lists to store; consumed by value.
• callback (CompleteCallback) - Receives the outcome; carries an ErrorDetail on failure. Never throws.

void get_trusted_crls_async(GetCrlsCallback callback) const noexcept=0

Retrieves the current trusted CRL set.

• callback (GetCrlsCallback) - Receives the CrlList, or an ErrorDetail on failure. Never throws.

void add_to_issuer_crls_async(shared_ptr< const X509Crl > crl, CompleteCallback callback) noexcept=0

Adds a CRL to the issuer CRL set.

• crl (shared_ptr< const X509Crl >) - Revocation list to store; must be non-null.
• callback (CompleteCallback) - Receives the outcome; carries an ErrorDetail on failure. Never throws.

void add_to_issuer_crls_async(std::vector< shared_ptr< const X509Crl > > crls, CompleteCallback callback) noexcept=0

Adds several CRLs to the issuer CRL set in one operation.

• crls (std::vector< shared_ptr< const X509Crl > >) - Revocation lists to store; consumed by value.
• callback (CompleteCallback) - Receives the outcome; carries an ErrorDetail on failure. Never throws.

void get_issuer_crls_async(GetCrlsCallback callback) const noexcept=0

Retrieves the current issuer CRL set.

• callback (GetCrlsCallback) - Receives the CrlList, or an ErrorDetail on failure. Never throws.

void replace_trusted_certificates_async(CertificateList certificates, CrlList crls, CompleteCallback callback) noexcept=0

Atomically replaces the entire trusted certificate and CRL set.

• certificates (CertificateList) - Replacement trusted certificate list; consumed by value.
• crls (CrlList) - Replacement trusted CRL set; consumed by value.
• callback (CompleteCallback) - Receives the outcome; carries an ErrorDetail on failure. Never throws.

void replace_issuer_certificates_async(CertificateList certificates, CrlList crls, CompleteCallback callback) noexcept=0

Atomically replaces the entire issuer certificate and CRL set.

• certificates (CertificateList) - Replacement issuer certificate list; consumed by value.
• crls (CrlList) - Replacement issuer CRL set; consumed by value.
• callback (CompleteCallback) - Receives the outcome; carries an ErrorDetail on failure. Never throws.

void remove_from_trusted_certificates_async(const std::string &thumbprint, CompleteCallback callback) noexcept=0

Removes a single certificate from the trusted list by its SHA-1 thumbprint.

• thumbprint (const std::string &) - Hex-encoded SHA-1 thumbprint of the certificate to remove.
• callback (CompleteCallback) - Receives the outcome; carries an ErrorDetail on failure. Never throws.

void remove_from_issuer_certificates_async(const std::string &thumbprint, CompleteCallback callback) noexcept=0

Removes a single certificate from the issuer list by its SHA-1 thumbprint.

• thumbprint (const std::string &) - Hex-encoded SHA-1 thumbprint of the certificate to remove.
• callback (CompleteCallback) - Receives the outcome; carries an ErrorDetail on failure. Never throws.

void set_validation_options(TrustListValidationOptions validationOptions)=0

Sets the default validation options applied by validate_certificate_async.

• validationOptions (TrustListValidationOptions) - Trust-list validation policy to use as the store default.

TrustListValidationOptions validation_options() const =0

Returns the default validation options: the last ones set with set_validation_options, or those the store was created with.

Returns: The store's current default validation options.

void refresh_cache(CompleteCallback callback)=0

Refreshes any cached view of the trust lists from the underlying backing store.

• callback (CompleteCallback) - Receives the outcome; carries an ErrorDetail on failure.

void validate_certificate_async(CertificateValidationRequest request, Crypto::CertificateValidationCompleteCallback callback) noexcept=0

Validates the certificate of request: the store's single validation entry point.

• request (CertificateValidationRequest) - The certificate to validate (must be non-null) and how to validate it.
• callback (Crypto::CertificateValidationCompleteCallback) - Receives the outcome on an unspecified worker thread; carries an ErrorDetail with the rejection reason on failure. Never throws.

VoidResult try_add_to_application_certificates_sync(ApplicationCertificate certificate) noexcept

Adds an application instance certificate, blocking until complete.

• certificate (ApplicationCertificate) - Certificate, key pair and type to store; consumed by value.

Returns: A VoidResult that carries an ErrorDetail on failure. Never throws.

void add_to_application_certificates_sync(ApplicationCertificate certificate)

Adds an application instance certificate, blocking until complete.

• certificate (ApplicationCertificate) - Certificate, key pair and type to store; consumed by value.

ApplicationCertificateResult try_get_application_certificate_sync(CertificateType certificateType) const noexcept

Retrieves the application certificate of the given type, blocking until complete.

• certificateType (CertificateType) - Cryptographic profile to look up.

Returns: The matching ApplicationCertificate, or an ErrorDetail on failure. Never throws.

ApplicationCertificate get_application_certificate_sync(CertificateType certificateType) const

Retrieves the application certificate of the given type, blocking until complete.

• certificateType (CertificateType) - Cryptographic profile to look up.

Returns: The matching ApplicationCertificate.

ApplicationCertificateListResult try_get_application_certificates_sync() const noexcept

Retrieves all application certificates, blocking until complete.

Returns: The ApplicationCertificateList, or an ErrorDetail on failure. Never throws.

ApplicationCertificateList get_application_certificates_sync() const

Retrieves all application certificates, blocking until complete.

Returns: The ApplicationCertificateList.

VoidResult try_add_to_trusted_certificates_sync(shared_ptr< const X509Certificate > certificate) noexcept

Adds a certificate to the trusted list, blocking until complete.

• certificate (shared_ptr< const X509Certificate >) - Certificate to trust; must be non-null.

Returns: A VoidResult that carries an ErrorDetail on failure. Never throws.

void add_to_trusted_certificates_sync(shared_ptr< const X509Certificate > certificate)

Adds a certificate to the trusted list, blocking until complete.

• certificate (shared_ptr< const X509Certificate >) - Certificate to trust; must be non-null.

VoidResult try_add_to_trusted_certificates_sync(std::vector< shared_ptr< const X509Certificate > > certificates) noexcept

Adds several certificates to the trusted list, blocking until complete.

• certificates (std::vector< shared_ptr< const X509Certificate > >) - Certificates to trust; consumed by value.

Returns: A VoidResult that carries an ErrorDetail on failure. Never throws.

void add_to_trusted_certificates_sync(std::vector< shared_ptr< const X509Certificate > > certificates)

Adds several certificates to the trusted list, blocking until complete.

• certificates (std::vector< shared_ptr< const X509Certificate > >) - Certificates to trust; consumed by value.

CertificateListResult try_get_trusted_certificates_sync() const noexcept

Retrieves the trusted certificate list, blocking until complete.

Returns: The CertificateList, or an ErrorDetail on failure. Never throws.

CertificateList get_trusted_certificates_sync() const

Retrieves the trusted certificate list, blocking until complete.

Returns: The CertificateList.

VoidResult try_add_to_issuer_certificates_sync(shared_ptr< const X509Certificate > certificate) noexcept

Adds a certificate to the issuer list, blocking until complete.

• certificate (shared_ptr< const X509Certificate >) - Issuer certificate to store; must be non-null.

Returns: A VoidResult that carries an ErrorDetail on failure. Never throws.

void add_to_issuer_certificates_sync(shared_ptr< const X509Certificate > certificate)

Adds a certificate to the issuer list, blocking until complete.

• certificate (shared_ptr< const X509Certificate >) - Issuer certificate to store; must be non-null.

VoidResult try_add_to_issuer_certificates_sync(std::vector< shared_ptr< const X509Certificate > > certificates) noexcept

Adds several certificates to the issuer list, blocking until complete.

• certificates (std::vector< shared_ptr< const X509Certificate > >) - Issuer certificates to store; consumed by value.

Returns: A VoidResult that carries an ErrorDetail on failure. Never throws.

void add_to_issuer_certificates_sync(std::vector< shared_ptr< const X509Certificate > > certificates)

Adds several certificates to the issuer list, blocking until complete.

• certificates (std::vector< shared_ptr< const X509Certificate > >) - Issuer certificates to store; consumed by value.

CertificateListResult try_get_issuer_certificates_sync() const noexcept

Retrieves the issuer certificate list, blocking until complete.

Returns: The CertificateList, or an ErrorDetail on failure. Never throws.

CertificateList get_issuer_certificates_sync() const

Retrieves the issuer certificate list, blocking until complete.

Returns: The CertificateList.

VoidResult try_add_to_rejected_certificates_sync(shared_ptr< const X509Certificate > certificate) noexcept

Records a rejected certificate, blocking until complete.

• certificate (shared_ptr< const X509Certificate >) - Certificate to record as rejected; must be non-null.

Returns: A VoidResult that carries an ErrorDetail on failure. Never throws.

void add_to_rejected_certificates_sync(shared_ptr< const X509Certificate > certificate)

Records a rejected certificate, blocking until complete.

• certificate (shared_ptr< const X509Certificate >) - Certificate to record as rejected; must be non-null.

CertificateListResult try_get_rejected_certificates_sync() const noexcept

Retrieves the rejected certificate list, blocking until complete.

Returns: The CertificateList, or an ErrorDetail on failure. Never throws.

CertificateList get_rejected_certificates_sync() const

Retrieves the rejected certificate list, blocking until complete.

Returns: The CertificateList.

VoidResult try_add_to_trusted_crls_sync(shared_ptr< const X509Crl > crl) noexcept

Adds a CRL to the trusted CRL set, blocking until complete.

• crl (shared_ptr< const X509Crl >) - Revocation list to store; must be non-null.

Returns: A VoidResult that carries an ErrorDetail on failure. Never throws.

void add_to_trusted_crls_sync(shared_ptr< const X509Crl > crl)

Adds a CRL to the trusted CRL set, blocking until complete.

• crl (shared_ptr< const X509Crl >) - Revocation list to store; must be non-null.

VoidResult try_add_to_trusted_crls_sync(std::vector< shared_ptr< const X509Crl > > crls) noexcept

Adds several CRLs to the trusted CRL set, blocking until complete.

• crls (std::vector< shared_ptr< const X509Crl > >) - Revocation lists to store; consumed by value.

Returns: A VoidResult that carries an ErrorDetail on failure. Never throws.

void add_to_trusted_crls_sync(std::vector< shared_ptr< const X509Crl > > crls)

Adds several CRLs to the trusted CRL set, blocking until complete.

• crls (std::vector< shared_ptr< const X509Crl > >) - Revocation lists to store; consumed by value.

CrlListResult try_get_trusted_crls_sync() const noexcept

Retrieves the trusted CRL set, blocking until complete.

Returns: The CrlList, or an ErrorDetail on failure. Never throws.

CrlList get_trusted_crls_sync() const

Retrieves the trusted CRL set, blocking until complete.

Returns: The CrlList.

VoidResult try_add_to_issuer_crls_sync(shared_ptr< const X509Crl > crl) noexcept

Adds a CRL to the issuer CRL set, blocking until complete.

• crl (shared_ptr< const X509Crl >) - Revocation list to store; must be non-null.

Returns: A VoidResult that carries an ErrorDetail on failure. Never throws.

void add_to_issuer_crls_sync(shared_ptr< const X509Crl > crl)

Adds a CRL to the issuer CRL set, blocking until complete.

• crl (shared_ptr< const X509Crl >) - Revocation list to store; must be non-null.

VoidResult try_add_to_issuer_crls_sync(std::vector< shared_ptr< const X509Crl > > crls) noexcept

Adds several CRLs to the issuer CRL set, blocking until complete.

• crls (std::vector< shared_ptr< const X509Crl > >) - Revocation lists to store; consumed by value.

Returns: A VoidResult that carries an ErrorDetail on failure. Never throws.

void add_to_issuer_crls_sync(std::vector< shared_ptr< const X509Crl > > crls)

Adds several CRLs to the issuer CRL set, blocking until complete.

• crls (std::vector< shared_ptr< const X509Crl > >) - Revocation lists to store; consumed by value.

CrlListResult try_get_issuer_crls_sync() const noexcept

Retrieves the issuer CRL set, blocking until complete.

Returns: The CrlList, or an ErrorDetail on failure. Never throws.

CrlList get_issuer_crls_sync() const

Retrieves the issuer CRL set, blocking until complete.

Returns: The CrlList.

VoidResult try_replace_trusted_certificates_sync(CertificateList certificates, CrlList crls) noexcept

Atomically replaces the trusted certificate and CRL set, blocking until complete.

• certificates (CertificateList) - Replacement trusted certificate list; consumed by value.
• crls (CrlList) - Replacement trusted CRL set; consumed by value.

Returns: A VoidResult that carries an ErrorDetail on failure. Never throws.

void replace_trusted_certificates_sync(CertificateList certificates, CrlList crls)

Atomically replaces the trusted certificate and CRL set, blocking until complete.

• certificates (CertificateList) - Replacement trusted certificate list; consumed by value.
• crls (CrlList) - Replacement trusted CRL set; consumed by value.

VoidResult try_replace_issuer_certificates_sync(CertificateList certificates, CrlList crls) noexcept

Atomically replaces the issuer certificate and CRL set, blocking until complete.

• certificates (CertificateList) - Replacement issuer certificate list; consumed by value.
• crls (CrlList) - Replacement issuer CRL set; consumed by value.

Returns: A VoidResult that carries an ErrorDetail on failure. Never throws.

void replace_issuer_certificates_sync(CertificateList certificates, CrlList crls)

Atomically replaces the issuer certificate and CRL set, blocking until complete.

• certificates (CertificateList) - Replacement issuer certificate list; consumed by value.
• crls (CrlList) - Replacement issuer CRL set; consumed by value.

VoidResult try_remove_from_trusted_certificates_sync(const std::string &thumbprint) noexcept

Removes a trusted certificate by SHA-1 thumbprint, blocking until complete.

• thumbprint (const std::string &) - Hex-encoded SHA-1 thumbprint of the certificate to remove.

Returns: A VoidResult that carries an ErrorDetail on failure. Never throws.

void remove_from_trusted_certificates_sync(const std::string &thumbprint)

Removes a trusted certificate by SHA-1 thumbprint, blocking until complete.

• thumbprint (const std::string &) - Hex-encoded SHA-1 thumbprint of the certificate to remove.

VoidResult try_remove_from_issuer_certificates_sync(const std::string &thumbprint) noexcept

Removes an issuer certificate by SHA-1 thumbprint, blocking until complete.

• thumbprint (const std::string &) - Hex-encoded SHA-1 thumbprint of the certificate to remove.

Returns: A VoidResult that carries an ErrorDetail on failure. Never throws.

void remove_from_issuer_certificates_sync(const std::string &thumbprint)

Removes an issuer certificate by SHA-1 thumbprint, blocking until complete.

• thumbprint (const std::string &) - Hex-encoded SHA-1 thumbprint of the certificate to remove.

VoidResult try_validate_certificate_sync(CertificateValidationRequest request) noexcept

Validates the certificate of request as validate_certificate_async does, blocking until complete.

• request (CertificateValidationRequest) - The certificate to validate (must be non-null) and how to validate it.

Returns: A VoidResult that carries the rejection reason as an ErrorDetail on failure. Never throws.

void validate_certificate_sync(CertificateValidationRequest request)

Validates the certificate of request as validate_certificate_async does, blocking until complete.

• request (CertificateValidationRequest) - The certificate to validate (must be non-null) and how to validate it.

ua::CertificateStoreFilesConfig

The settings of a file-system-backed certificate store (CertificateStoreFiles::create).

Public attributes

std::filesystem::path trustListPath

Root directory holding the store's subdirectories; created if missing.

TrustListValidationOptions validationOptions

Initial trust-list validation options.

std::optional< std::chrono::seconds > refreshPeriod

Interval between automatic file system re-scans; unset or a non-positive value disables automatic refresh.

bool storeRejectedCertificates

When true, certificates that fail validation are persisted to the rejected store; otherwise they are tracked only in memory.

size_t maxRejectedCertificates

Upper bound on the rejected-certificate store.

CertificateUse use

The use this store's certificates are validated for when a request does not name one (OPC 10000-4 Table 106, Certificate Usage).

Logger logger

Logger for diagnostics; a no-op logger by default.

ua::CertificateStoreFiles

A CertificateStore that persists each store as a directory tree on the file system.

Application certificates and keys, trusted certificates, issuer certificates, rejected certificates, and their CRLs are each kept in a dedicated subdirectory beneath a single trust list root path. The store reads those directories into an in-memory cache and, when a non-zero refresh period is configured, periodically re-scans the file system so that out-of-band changes (certificates dropped in or removed by an operator or by the OPC UA TrustList file type) are picked up automatically.

This is a strand-serialized component: every public method posts its work to a private strand, so callers may invoke it from any thread and the store serializes all access to its caches and to the file system internally. The *_async overloads deliver their outcome on an unspecified worker thread; do not block that thread.

Created through create and owned as a shared_ptr<CertificateStore>; the concrete type is private to the SDK. The store keeps the injected executor and Crypto alive for as long as it lives.

CertificateStore

Static functions

shared_ptr< CertificateStore > create(boost::asio::any_io_executor executor, shared_ptr< const Crypto > crypto, CertificateStoreFilesConfig config)

Creates a file-system-backed certificate store rooted at config.trustListPath.

• executor (boost::asio::any_io_executor) - Executor on which the store's strand and background refresh run; kept alive for the store's lifetime.
• crypto (shared_ptr< const Crypto >) - Cryptographic provider used for parsing and validation; kept alive for the store's lifetime; must not be null.
• config (CertificateStoreFilesConfig) - The store's settings; see CertificateStoreFilesConfig.

Returns: A shared, ready-to-use CertificateStore.

ua::CertificateValidationMaterial

The trust material one certificate validation runs against: what the holder of the trust list supplies to Crypto::validate_certificate_async, as distinct from what the peer presented (CertificateValidationRequest).

A CertificateStore fills it from its own lists, CRLs and options; the TrustList methods fill it from the list being installed. The validator treats the two certificate lists differently: a certificate in trusted confers trust (OPC 10000-4 section 6.1.3 Table 106, Trust List Check), a certificate in issuers only completes a chain.

Public attributes

std::vector< shared_ptr< const X509Certificate > > trusted

Trusted certificates (roots, intermediates and trusted peers), matched by thumbprint and DER encoding.

std::vector< shared_ptr< const X509Certificate > > issuers

Issuer certificates used only to complete a chain; never trusted.

std::vector< shared_ptr< const X509Crl > > trustedCrls

CRLs issued by the certificates of trusted.

std::vector< shared_ptr< const X509Crl > > issuerCrls

CRLs issued by the certificates of issuers.

TrustListValidationOptions options

The resolved options: the request's options when it carries them, otherwise the trust list's.

ua::AsymmetricKeyPair

An asymmetric public/private key pair, owned by a Crypto provider.

Instances are produced by a Crypto and shared as shared_ptr<const AsymmetricKeyPair>; they are immutable and safe to share across threads. A key pair may be public-key-only (see Crypto::get_public_key_from_der), in which case the private-key accessors fail.

Functions

~AsymmetricKeyPair()=default

CertificateKeyAlgorithm algorithm() const =0

Returns the key algorithm (e.g.

Returns: The key algorithm (RSA or an elliptic-curve variant) of this pair.

ByteString public_key_der() const =0

Returns the DER-encoded SubjectPublicKeyInfo for the public key.

Returns: The DER-encoded SubjectPublicKeyInfo of the public key.

ByteString private_key_pem() const =0

Returns the PEM-encoded private key.

Returns: The private key in PEM encoding.

ua::Crypto

Cryptographic provider for OPC UA security operations.

Crypto is the abstraction over a concrete crypto backend (e.g. OpenSSL, or a hardware secure element). It supplies entropy, hashing, symmetric and asymmetric cipher/signature primitives, key derivation and agreement, and X.509 certificate/CRL creation, parsing, and validation.

Most operations expose an async variant (callback receives a Result) plus a blocking _sync convenience. The async callback runs on an unspecified worker thread and must not block. Implementations are immutable after construction and safe to call concurrently from any thread; instances are shared as shared_ptr<const Crypto>.

Buffer parameters passed as span are borrowed for the duration of the call only: for async operations the caller must keep the referenced storage alive until the callback fires. Several async overloads additionally take an owning resource handle whose sole purpose is to pin such caller-owned storage for the lifetime of the operation.

Member types

Result< EphemeralKeyPair > EphemeralKeyPairResult

Result of generating an EphemeralKeyPair; carries an ErrorDetail on failure.

std::function< SecureString()> PrivateKeyCredentialCallback

Callback supplying the passphrase that protects private key material.

Returns: The passphrase. When a credential is required, this must be non-empty.

std::function< void(VoidResult)> GenericCompleteCallback

Completion callback for operations whose only outcome is success or an ErrorDetail.

std::function< void(ByteStringResult)> GetEntropyCompleteCallback

Completion callback for get_entropy_async; receives the random bytes or an ErrorDetail.

Result< CalculateDigestOutput > CalculateDigestOutputResult

Result of calculate_digest_async; carries an ErrorDetail on failure.

std::function< void(CalculateDigestOutputResult)> CalculateDigestCompleteCallback

Completion callback for calculate_digest_async.

GenericCompleteCallback SymmetricEncryptCompleteCallback

Completion callback for symmetric_encrypt_async; the ciphertext is written in place.

GenericCompleteCallback SymmetricDecryptCompleteCallback

Completion callback for symmetric_decrypt_async; the plaintext is written in place.

Result< SymmetricEncryptAndSignOutput > SymmetricEncryptAndSignOutputResult

Result of symmetric_encrypt_and_sign_async; carries an ErrorDetail on failure.

std::function< void(SymmetricEncryptAndSignOutputResult)> SymmetricEncryptAndSignCompleteCallback

Completion callback for symmetric_encrypt_and_sign_async.

Result< SymmetricVerifyAndDecryptOutput > SymmetricVerifyAndDecryptOutputResult

Result of symmetric_verify_and_decrypt_async; carries an ErrorDetail on failure.

std::function< void(SymmetricVerifyAndDecryptOutputResult)> SymmetricVerifyAndDecryptCompleteCallback

Completion callback for symmetric_verify_and_decrypt_async.

std::function< void(ByteStringResult)> SymmetricSignCompleteCallback

Completion callback for symmetric_sign_async; receives the signature or an ErrorDetail.

GenericCompleteCallback SymmetricVerifyCompleteCallback

Completion callback for symmetric_verify_async; success means the signature is valid.

GenericCompleteCallback AsymmetricEncryptCompleteCallback

Completion callback for asymmetric_encrypt_async; the ciphertext is written in place.

Result< span< const byte > > ByteSpanResult

Result holding a borrowed view of bytes (a sub-span of a caller-supplied buffer).

std::function< void(ByteSpanResult)> AsymmetricDecryptCompleteCallback

Completion callback for asymmetric_decrypt_async; receives the recovered plaintext view.

std::function< void(ByteStringResult)> AsymmetricSignCompleteCallback

Completion callback for asymmetric_sign_async; receives the signature or an ErrorDetail.

GenericCompleteCallback AsymmetricVerifyCompleteCallback

Completion callback for asymmetric_verify_async; success means the signature is valid.

std::function< void(KeyPairResult)> CreateAsymmetricKeyPairCompleteCallback

Completion callback for create_asymmetric_key_pair_async.

std::function< void(ByteStringResult)> DeriveSymmetricKeysCompleteCallback

Completion callback for the derive_symmetric_keys_async overloads.

std::function< void(EphemeralKeyPairResult)> CreateEphemeralKeysCompleteCallback

Completion callback for create_ephemeral_keys_async.

std::function< void(ByteStringResult)> CalculateSharedSecretCompleteCallback

Completion callback for calculate_shared_secret_async.

std::function< void(CertificateResult)> CreateCertificateCompleteCallback

Completion callback for create_certificate_async.

std::function< void(SelfSignedCertResult)> CreateSelfSignedApplicationInstanceCertificateCompleteCallback

Completion callback for create_self_signed_application_instance_certificate_async.

std::function< void(ByteStringResult)> CreateCertificateSigningRequestCompleteCallback

Completion callback for create_certificate_signing_request_async; receives the DER CSR.

std::function< void(CrlResult)> CreateCrlCompleteCallback

Completion callback for create_crl_async.

std::function< void(VoidResult)> CertificateValidationCompleteCallback

Completion callback for validate_certificate_async; success means the certificate is trusted.

std::function< void(VoidResult)> CrlValidationCompleteCallback

Completion callback for validate_crl_async; success means the CRL is valid.

std::function< void(CertificateResult)> SignCsrCompleteCallback

Completion callback for sign_certificate_request_async.

Functions

bool has_secure_element() const =0

Returns true if the provider uses a secure element (HSM/TPM) for private key storage.

Returns: true if a secure element (HSM/TPM) backs private-key storage; false for software-only providers.

~Crypto()=default

void get_entropy_async(size_t numberOfBytes, GetEntropyCompleteCallback callback) const noexcept=0

Generates cryptographically secure random bytes.

• numberOfBytes (size_t) - Number of random bytes to produce.
• callback (GetEntropyCompleteCallback) - Receives the random bytes, or an ErrorDetail on failure. Never throws.

ByteString get_entropy_sync(size_t numberOfBytes) const =0

Generates cryptographically secure random bytes, blocking until complete.

• numberOfBytes (size_t) - Number of random bytes to produce.

Returns: The random bytes.

void calculate_digest_async(HashAlgorithm algorithm, ByteString inputBuffer, span< const byte > input, CalculateDigestCompleteCallback callback) const noexcept=0

Computes a message digest over input using algorithm.

• algorithm (HashAlgorithm) - Hash algorithm to apply.
• inputBuffer (ByteString) - Owning copy of the input that is returned alongside the digest, keeping the hashed bytes valid for the duration of the async call.
• input (span< const byte >) - View of the bytes to hash (typically a view into inputBuffer).
• callback (CalculateDigestCompleteCallback) - Receives the input buffer and digest, or an ErrorDetail on failure. Never throws.

ByteString calculate_digest_sync(HashAlgorithm algorithm, span< const byte > input) const =0

Computes a message digest over input, blocking until complete.

• algorithm (HashAlgorithm) - Hash algorithm to apply.
• input (span< const byte >) - Bytes to hash.

Returns: The computed digest.

void derive_symmetric_keys_async(SymmetricKeyDerivationAlgorithm algorithm, size_t numberOfBytes, ByteString secret, ByteString seed, DeriveSymmetricKeysCompleteCallback callback) const noexcept=0

Derives numberOfBytes of key material from a secret and seed (P-SHA pseudo-random function).

• algorithm (SymmetricKeyDerivationAlgorithm) - Key-derivation algorithm to use.
• numberOfBytes (size_t) - Length of the derived key material, in bytes.
• secret (ByteString) - Shared secret input (kept alive for the async call).
• seed (ByteString) - Seed input (kept alive for the async call).
• callback (DeriveSymmetricKeysCompleteCallback) - Receives the derived key material, or an ErrorDetail on failure. Never throws.

ByteString derive_symmetric_keys_sync(SymmetricKeyDerivationAlgorithm algorithm, size_t numberOfBytes, span< const byte > secret, span< const byte > seed) const =0

Derives key material from a secret and seed, blocking until complete.

• algorithm (SymmetricKeyDerivationAlgorithm) - Key-derivation algorithm to use.
• numberOfBytes (size_t) - Length of the derived key material, in bytes.
• secret (span< const byte >) - Shared secret input.
• seed (span< const byte >) - Seed input.

Returns: The derived key material, of length numberOfBytes.

void derive_symmetric_keys_async(SymmetricKeyDerivationAlgorithm algorithm, size_t numberOfBytes, ByteString secret, ByteString salt, ByteString info, DeriveSymmetricKeysCompleteCallback callback) const noexcept=0

Derives numberOfBytes of key material from a secret using an HKDF-style salt and info.

• algorithm (SymmetricKeyDerivationAlgorithm) - Key-derivation algorithm to use.
• numberOfBytes (size_t) - Length of the derived key material, in bytes.
• secret (ByteString) - Shared secret input (kept alive for the async call).
• salt (ByteString) - Salt input (kept alive for the async call).
• info (ByteString) - Context/info input binding the key to its use (kept alive for the call).
• callback (DeriveSymmetricKeysCompleteCallback) - Receives the derived key material, or an ErrorDetail on failure. Never throws.

ByteString derive_symmetric_keys_sync(SymmetricKeyDerivationAlgorithm algorithm, size_t numberOfBytes, span< const byte > secret, span< const byte > salt, span< const byte > info) const =0

Derives key material from a secret, salt, and info, blocking until complete.

• algorithm (SymmetricKeyDerivationAlgorithm) - Key-derivation algorithm to use.
• numberOfBytes (size_t) - Length of the derived key material, in bytes.
• secret (span< const byte >) - Shared secret input.
• salt (span< const byte >) - Salt input.
• info (span< const byte >) - Context/info input binding the key to its use.

Returns: The derived key material, of length numberOfBytes.

void symmetric_encrypt_async(shared_ptr< const void > resource, SymmetricEncryptionAlgorithm algorithm, span< const byte > iv, span< const byte > key, span< const byte > plainText, span< byte > cipherText, SymmetricEncryptCompleteCallback callback) const noexcept=0

Encrypts plainText into cipherText using a symmetric cipher.

• resource (shared_ptr< const void >) - Owning handle that pins the caller-supplied buffers for the operation's lifetime; may be empty if the caller guarantees the spans outlive the call.
• algorithm (SymmetricEncryptionAlgorithm) - Symmetric encryption algorithm.
• iv (span< const byte >) - Initialization vector.
• key (span< const byte >) - Symmetric key.
• plainText (span< const byte >) - Plaintext input.
• cipherText (span< byte >) - Output buffer; the ciphertext is written here in place and must be large enough to hold it.
• callback (SymmetricEncryptCompleteCallback) - Receives success or an ErrorDetail on failure. Never throws.

void symmetric_encrypt_sync(SymmetricEncryptionAlgorithm algorithm, span< const byte > iv, span< const byte > key, span< const byte > plainText, span< byte > cipherText) const =0

Encrypts plainText into cipherText, blocking until complete.

• algorithm (SymmetricEncryptionAlgorithm) - Symmetric encryption algorithm.
• iv (span< const byte >) - Initialization vector.
• key (span< const byte >) - Symmetric key.
• plainText (span< const byte >) - Plaintext input.
• cipherText (span< byte >) - Output buffer written in place; must be large enough for the ciphertext.

void symmetric_decrypt_async(shared_ptr< const void > resource, SymmetricEncryptionAlgorithm algorithm, span< const byte > iv, span< const byte > key, span< const byte > cipherText, span< byte > plainText, SymmetricDecryptCompleteCallback callback) const noexcept=0

Decrypts cipherText into plainText using a symmetric cipher.

• resource (shared_ptr< const void >) - Owning handle that pins the caller-supplied buffers for the operation's lifetime; may be empty if the caller guarantees the spans outlive the call.
• algorithm (SymmetricEncryptionAlgorithm) - Symmetric encryption algorithm.
• iv (span< const byte >) - Initialization vector.
• key (span< const byte >) - Symmetric key.
• cipherText (span< const byte >) - Ciphertext input.
• plainText (span< byte >) - Output buffer; the plaintext is written here in place.
• callback (SymmetricDecryptCompleteCallback) - Receives success or an ErrorDetail on failure. Never throws.

void symmetric_decrypt_sync(SymmetricEncryptionAlgorithm algorithm, span< const byte > iv, span< const byte > key, span< const byte > cipherText, span< byte > plainText) const =0

Decrypts cipherText into plainText, blocking until complete.

• algorithm (SymmetricEncryptionAlgorithm) - Symmetric encryption algorithm.
• iv (span< const byte >) - Initialization vector.
• key (span< const byte >) - Symmetric key.
• cipherText (span< const byte >) - Ciphertext input.
• plainText (span< byte >) - Output buffer written in place.

void symmetric_encrypt_and_sign_async(SymmetricEncryptionAlgorithm algorithm, ByteString iv, ByteString key, ByteString plainTextBuffer, span< const byte > plainText, span< const byte > additionalData, optional< ByteString > cipherTextBuffer, span< byte > cipherText, SymmetricEncryptAndSignCompleteCallback callback) const =0

Encrypts and authenticates plainText, producing ciphertext and a signature (MAC).

• algorithm (SymmetricEncryptionAlgorithm) - Symmetric encryption algorithm.
• iv (ByteString) - Initialization vector (owning, kept alive for the async call).
• key (ByteString) - Symmetric key (owning, kept alive for the async call).
• plainTextBuffer (ByteString) - Owning copy of the plaintext, returned in the result.
• plainText (span< const byte >) - View of the plaintext to encrypt (typically into plainTextBuffer).
• additionalData (span< const byte >) - Additional authenticated data covered by the signature but not encrypted.
• cipherTextBuffer (optional< ByteString >) - Optional owning output buffer for out-of-place ciphertext; pass empty for in-place encryption into cipherText.
• cipherText (span< byte >) - Output view for the ciphertext when produced in place.
• callback (SymmetricEncryptAndSignCompleteCallback) - Receives the buffers and signature, or an ErrorDetail on failure. Never throws.

ByteString symmetric_encrypt_and_sign_sync(SymmetricEncryptionAlgorithm algorithm, span< const byte > iv, span< const byte > key, span< const byte > plainText, span< const byte > additionalData, span< byte > cipherText) const =0

Encrypts and authenticates plainText, blocking until complete.

• algorithm (SymmetricEncryptionAlgorithm) - Symmetric encryption algorithm.
• iv (span< const byte >) - Initialization vector.
• key (span< const byte >) - Symmetric key.
• plainText (span< const byte >) - Plaintext input to encrypt.
• additionalData (span< const byte >) - Additional authenticated data covered by the signature but not encrypted.
• cipherText (span< byte >) - Output buffer written in place; must be large enough for the ciphertext.

Returns: The authentication signature (MAC) over the ciphertext and additional data.

void symmetric_verify_and_decrypt_async(SymmetricEncryptionAlgorithm algorithm, ByteString iv, ByteString key, ByteString cipherTextBuffer, span< const byte > cipherText, span< const byte > additionalData, span< const byte > signature, optional< ByteString > plainTextBuffer, span< byte > plainText, SymmetricVerifyAndDecryptCompleteCallback callback) const =0

Verifies signature and, on success, decrypts cipherText into plaintext.

• algorithm (SymmetricEncryptionAlgorithm) - Symmetric encryption algorithm.
• iv (ByteString) - Initialization vector (owning, kept alive for the async call).
• key (ByteString) - Symmetric key (owning, kept alive for the async call).
• cipherTextBuffer (ByteString) - Owning copy of the ciphertext, returned in the result.
• cipherText (span< const byte >) - View of the ciphertext to verify and decrypt.
• additionalData (span< const byte >) - Additional authenticated data covered by the signature.
• signature (span< const byte >) - Signature (MAC) to verify before decrypting.
• plainTextBuffer (optional< ByteString >) - Optional owning output buffer for out-of-place plaintext; pass empty for in-place decryption into plainText.
• plainText (span< byte >) - Output view for the plaintext when produced in place.
• callback (SymmetricVerifyAndDecryptCompleteCallback) - Receives the buffers, or an ErrorDetail if verification or decryption fails. Never throws.

void symmetric_verify_and_decrypt_sync(SymmetricEncryptionAlgorithm algorithm, span< const byte > iv, span< const byte > key, span< const byte > cipherText, span< const byte > additionalData, span< const byte > signature, span< byte > plainText) const =0

Verifies signature and decrypts cipherText, blocking until complete.

• algorithm (SymmetricEncryptionAlgorithm) - Symmetric encryption algorithm.
• iv (span< const byte >) - Initialization vector.
• key (span< const byte >) - Symmetric key.
• cipherText (span< const byte >) - Ciphertext input to verify and decrypt.
• additionalData (span< const byte >) - Additional authenticated data covered by the signature.
• signature (span< const byte >) - Authentication tag (MAC) checked against the ciphertext and additionalData.
• plainText (span< byte >) - Output buffer written in place; valid only if the call returns normally.

void symmetric_sign_async(shared_ptr< const void > resource, SymmetricSignatureAlgorithm algorithm, span< const byte > key, span< const byte > input, SymmetricSignCompleteCallback callback) const =0

Computes a symmetric signature (MAC) over input.

• resource (shared_ptr< const void >) - Owning handle that pins the caller-supplied buffers for the operation's lifetime; may be empty if the caller guarantees the spans outlive the call.
• algorithm (SymmetricSignatureAlgorithm) - Symmetric signature algorithm.
• key (span< const byte >) - Symmetric key.
• input (span< const byte >) - Data to sign.
• callback (SymmetricSignCompleteCallback) - Receives the signature, or an ErrorDetail on failure. Never throws.

ByteString symmetric_sign_sync(SymmetricSignatureAlgorithm algorithm, span< const byte > key, span< const byte > input) const =0

Computes a symmetric signature (MAC) over input, blocking until complete.

• algorithm (SymmetricSignatureAlgorithm) - Symmetric signature algorithm.
• key (span< const byte >) - Symmetric key.
• input (span< const byte >) - Data to sign.

Returns: The signature.

void symmetric_verify_async(shared_ptr< const void > resource, SymmetricSignatureAlgorithm algorithm, span< const byte > key, span< const byte > input, span< const byte > signature, SymmetricVerifyCompleteCallback callback) const =0

Verifies a symmetric signature (MAC) over input.

• resource (shared_ptr< const void >) - Owning handle that pins the caller-supplied buffers for the operation's lifetime; may be empty if the caller guarantees the spans outlive the call.
• algorithm (SymmetricSignatureAlgorithm) - Symmetric signature algorithm.
• key (span< const byte >) - Symmetric key.
• input (span< const byte >) - Data the signature covers.
• signature (span< const byte >) - Signature to verify.
• callback (SymmetricVerifyCompleteCallback) - Receives success if the signature is valid, or an ErrorDetail otherwise. Never throws.

void symmetric_verify_sync(SymmetricSignatureAlgorithm algorithm, span< const byte > key, span< const byte > input, span< const byte > signature) const =0

Verifies a symmetric signature (MAC) over input, blocking until complete.

• algorithm (SymmetricSignatureAlgorithm) - Symmetric signature algorithm.
• key (span< const byte >) - Symmetric key.
• input (span< const byte >) - Data the signature covers.
• signature (span< const byte >) - Signature to verify.

void asymmetric_encrypt_async(shared_ptr< const void > resource, AsymmetricEncryptionAlgorithm algorithm, span< const byte > publicKey, span< const byte > plainText, span< byte > cipherText, AsymmetricEncryptCompleteCallback callback) const =0

Encrypts plainText into cipherText with a public key.

• resource (shared_ptr< const void >) - Owning handle that pins the caller-supplied buffers for the operation's lifetime; may be empty if the caller guarantees the spans outlive the call.
• algorithm (AsymmetricEncryptionAlgorithm) - Asymmetric encryption algorithm (and padding).
• publicKey (span< const byte >) - Recipient's public key.
• plainText (span< const byte >) - Plaintext input.
• cipherText (span< byte >) - Output buffer written in place; must be large enough for the ciphertext.
• callback (AsymmetricEncryptCompleteCallback) - Receives success or an ErrorDetail on failure. Never throws.

void asymmetric_encrypt_sync(AsymmetricEncryptionAlgorithm algorithm, span< const byte > publicKey, span< const byte > plainText, span< byte > cipherText) const =0

Encrypts plainText into cipherText with a public key, blocking until complete.

• algorithm (AsymmetricEncryptionAlgorithm) - Asymmetric encryption algorithm (and padding).
• publicKey (span< const byte >) - Recipient's public key.
• plainText (span< const byte >) - Plaintext input.
• cipherText (span< byte >) - Output buffer written in place; must be large enough for the ciphertext.

void asymmetric_decrypt_async(shared_ptr< const void > resource, AsymmetricEncryptionAlgorithm algorithm, shared_ptr< const AsymmetricKeyPair > privateKey, span< const byte > cipherText, span< byte > plainText, AsymmetricDecryptCompleteCallback callback) const =0

Decrypts cipherText with a private key, writing the plaintext into plainText.

• resource (shared_ptr< const void >) - Owning handle that pins the caller-supplied buffers for the operation's lifetime; may be empty if the caller guarantees the spans outlive the call.
• algorithm (AsymmetricEncryptionAlgorithm) - Asymmetric encryption algorithm (and padding).
• privateKey (shared_ptr< const AsymmetricKeyPair >) - Key pair holding the private key to decrypt with.
• cipherText (span< const byte >) - Ciphertext input.
• plainText (span< byte >) - Output buffer the plaintext is written into.
• callback (AsymmetricDecryptCompleteCallback) - Receives a view of the recovered plaintext within plainText, or an ErrorDetail on failure. Never throws.

span< const byte > asymmetric_decrypt_sync(AsymmetricEncryptionAlgorithm algorithm, shared_ptr< const AsymmetricKeyPair > privateKey, span< const byte > cipherText, span< byte > plainText) const =0

Decrypts cipherText with a private key, blocking until complete.

• algorithm (AsymmetricEncryptionAlgorithm) - Asymmetric encryption algorithm (and padding).
• privateKey (shared_ptr< const AsymmetricKeyPair >) - Key pair holding the private key to decrypt with.
• cipherText (span< const byte >) - Ciphertext input.
• plainText (span< byte >) - Output buffer the plaintext is written into.

Returns: A view of the recovered plaintext within plainText.

void asymmetric_sign_async(shared_ptr< const void > resource, AsymmetricSignatureAlgorithm algorithm, shared_ptr< const AsymmetricKeyPair > privateKey, span< const byte > input, AsymmetricSignCompleteCallback callback) const =0

Signs input with a private key.

• resource (shared_ptr< const void >) - Owning handle that pins the caller-supplied buffers for the operation's lifetime; may be empty if the caller guarantees the spans outlive the call.
• algorithm (AsymmetricSignatureAlgorithm) - Asymmetric signature algorithm.
• privateKey (shared_ptr< const AsymmetricKeyPair >) - Key pair holding the private key to sign with.
• input (span< const byte >) - Data to sign.
• callback (AsymmetricSignCompleteCallback) - Receives the signature, or an ErrorDetail on failure. Never throws.

ByteString asymmetric_sign_sync(AsymmetricSignatureAlgorithm algorithm, shared_ptr< const AsymmetricKeyPair > privateKey, span< const byte > input) const =0

Signs input with a private key, blocking until complete.

• algorithm (AsymmetricSignatureAlgorithm) - Asymmetric signature algorithm.
• privateKey (shared_ptr< const AsymmetricKeyPair >) - Key pair holding the private key to sign with.
• input (span< const byte >) - Data to sign.

Returns: The signature.

void asymmetric_verify_async(shared_ptr< const void > resource, AsymmetricSignatureAlgorithm algorithm, span< const byte > publicKey, span< const byte > input, span< const byte > signature, AsymmetricVerifyCompleteCallback callback) const =0

Verifies signature over input against a public key.

• resource (shared_ptr< const void >) - Owning handle that pins the caller-supplied buffers for the operation's lifetime; may be empty if the caller guarantees the spans outlive the call.
• algorithm (AsymmetricSignatureAlgorithm) - Asymmetric signature algorithm.
• publicKey (span< const byte >) - Signer's public key.
• input (span< const byte >) - Data the signature covers.
• signature (span< const byte >) - Signature to verify.
• callback (AsymmetricVerifyCompleteCallback) - Receives success if the signature is valid, or an ErrorDetail otherwise. Never throws.

void asymmetric_verify_sync(AsymmetricSignatureAlgorithm algorithm, span< const byte > publicKey, span< const byte > input, span< const byte > signature) const =0

Verifies signature over input against a public key, blocking until complete.

• algorithm (AsymmetricSignatureAlgorithm) - Asymmetric signature algorithm.
• publicKey (span< const byte >) - Signer's public key.
• input (span< const byte >) - Data the signature covers.
• signature (span< const byte >) - Signature to verify.

void create_asymmetric_key_pair_async(CertificateKeyAlgorithm algorithm, optional< size_t > keyLengthInBits, CreateAsymmetricKeyPairCompleteCallback callback) const =0

Generates a new long-term asymmetric key pair.

• algorithm (CertificateKeyAlgorithm) - Key algorithm to generate.
• keyLengthInBits (optional< size_t >) - Key length in bits; unset selects the algorithm's default (and is ignored for fixed-size elliptic curves).
• callback (CreateAsymmetricKeyPairCompleteCallback) - Receives the new key pair, or an ErrorDetail on failure. Never throws.

shared_ptr< const AsymmetricKeyPair > create_asymmetric_key_pair_sync(CertificateKeyAlgorithm algorithm, optional< size_t > keyLengthInBits) const =0

Generates a new long-term asymmetric key pair, blocking until complete.

• algorithm (CertificateKeyAlgorithm) - Key algorithm to generate.
• keyLengthInBits (optional< size_t >) - Key length in bits; unset selects the algorithm's default (and is ignored for fixed-size elliptic curves).

Returns: The generated key pair.

void create_ephemeral_keys_async(EphemeralKeyAlgorithm algorithm, CreateEphemeralKeysCompleteCallback callback) const =0

Generates an ephemeral key-agreement key pair for a single handshake.

• algorithm (EphemeralKeyAlgorithm) - Ephemeral key-agreement algorithm.
• callback (CreateEphemeralKeysCompleteCallback) - Receives the ephemeral key pair, or an ErrorDetail on failure. Never throws.

EphemeralKeyPair create_ephemeral_keys_sync(EphemeralKeyAlgorithm algorithm) const =0

Generates an ephemeral key-agreement key pair, blocking until complete.

• algorithm (EphemeralKeyAlgorithm) - Ephemeral key-agreement algorithm.

Returns: The ephemeral key pair.

void calculate_shared_secret_async(EphemeralKeyAlgorithm algorithm, ByteString localPrivateKey, ByteString remotePublicKey, CalculateSharedSecretCompleteCallback callback) const =0

Computes the shared secret from a local private key and the peer's public key.

• algorithm (EphemeralKeyAlgorithm) - Key-agreement algorithm.
• localPrivateKey (ByteString) - Local ephemeral private key (kept alive for the async call).
• remotePublicKey (ByteString) - Peer's ephemeral public key (kept alive for the async call).
• callback (CalculateSharedSecretCompleteCallback) - Receives the shared secret, or an ErrorDetail on failure. Never throws.

ByteString calculate_shared_secret_sync(EphemeralKeyAlgorithm algorithm, span< const byte > localPrivateKey, span< const byte > remotePublicKey) const =0

Computes the key-agreement shared secret, blocking until complete.

• algorithm (EphemeralKeyAlgorithm) - Key-agreement algorithm.
• localPrivateKey (span< const byte >) - Local ephemeral private key.
• remotePublicKey (span< const byte >) - Peer's ephemeral public key.

Returns: The shared secret.

shared_ptr< const X509Certificate > read_certificate_from_der(span< const byte > der) const =0

Parses a single DER-encoded X.509 certificate.

• der (span< const byte >) - DER bytes of exactly one certificate.

Returns: The parsed certificate.

std::vector< shared_ptr< const X509Certificate > > read_certificates_from_der(span< const byte > der) const =0

Parses a concatenation of DER-encoded X.509 certificates (e.g.

• der (span< const byte >) - DER bytes of one or more concatenated certificates; every byte must belong to a complete certificate.

Returns: The parsed certificates, in encounter order (empty for empty input). Never a partial result.

shared_ptr< const X509Crl > read_crl_from_der(span< const byte > der) const =0

Parses a single DER-encoded X.509 CRL.

• der (span< const byte >) - DER bytes of exactly one CRL.

Returns: The parsed CRL.

std::vector< shared_ptr< const X509Crl > > read_crls_from_der(span< const byte > der) const =0

Parses a concatenation of DER-encoded X.509 CRLs.

• der (span< const byte >) - DER bytes of one or more concatenated CRLs; every byte must belong to a complete CRL.

Returns: The parsed CRLs, in encounter order (empty for empty input). Never a partial result.

shared_ptr< const AsymmetricKeyPair > get_private_key_from_pem(CertificateKeyAlgorithm keyAlgorithm, span< byte > pem) const =0

Loads a key pair (including its private key) from PEM-encoded bytes.

• keyAlgorithm (CertificateKeyAlgorithm) - Expected key algorithm of the PEM key.
• pem (span< byte >) - Mutable PEM bytes; the buffer may be scrubbed in place after parsing so private-key material does not linger in caller memory.

Returns: The loaded key pair.

void create_certificate_async(const CreateCertificateConfig &parameters, CreateCertificateCompleteCallback callback) const =0

Issues an X.509 certificate signed by the issuer described in parameters.

• parameters (const CreateCertificateConfig &) - Subject, issuer, validity, and extension parameters for the certificate.
• callback (CreateCertificateCompleteCallback) - Receives the issued certificate, or an ErrorDetail on failure. Never throws.

void create_self_signed_application_instance_certificate_async(Name subject, UtcTime expiry, SubjectAlternateName subjectAlternateName, CertificateType certificateType, optional< size_t > keyLengthInBits, CreateSelfSignedApplicationInstanceCertificateCompleteCallback callback) const

Generates a key pair and a matching self-signed application instance certificate.

• subject (Name) - Subject distinguished name for the certificate.
• expiry (UtcTime) - notAfter validity end (validity starts at issuance).
• subjectAlternateName (SubjectAlternateName) - SubjectAlternativeName entries, including the application URI.
• certificateType (CertificateType) - Certificate/key type to generate (e.g. RSA or an ECC variant).
• keyLengthInBits (optional< size_t >) - Key length in bits; unset uses the type's default.
• callback (CreateSelfSignedApplicationInstanceCertificateCompleteCallback) - Receives the generated key pair and certificate with the code create_certificate_async() answered (a Good subcode or an Uncertain code is kept), or an ErrorDetail on failure. A key pair answered Uncertain is not used: the call fails with Bad_InternalError, that code as the cause. Never throws.

SelfSignedCertResult try_create_self_signed_application_instance_certificate_sync(Name subject, UtcTime expiry, SubjectAlternateName subjectAlternateName, CertificateType certificateType, optional< size_t > keyLengthInBits) const noexcept

Generates a self-signed application instance certificate, blocking until complete.

• subject (Name) - Subject distinguished name for the certificate.
• expiry (UtcTime) - notAfter validity end (validity starts at issuance).
• subjectAlternateName (SubjectAlternateName) - SubjectAlternativeName entries, including the application URI.
• certificateType (CertificateType) - Certificate/key type to generate (e.g. RSA or an ECC variant).
• keyLengthInBits (optional< size_t >) - Key length in bits; unset uses the type's default.

Returns: The generated key pair and certificate, or an ErrorDetail on failure. Never throws.

std::pair< shared_ptr< const AsymmetricKeyPair >, shared_ptr< const X509Certificate > > create_self_signed_application_instance_certificate_sync(Name subject, UtcTime expiry, SubjectAlternateName subjectAlternateName, CertificateType certificateType, optional< size_t > keyLengthInBits) const

Generates a self-signed application instance certificate, blocking until complete.

• subject (Name) - Subject distinguished name for the certificate.
• expiry (UtcTime) - notAfter validity end (validity starts at issuance).
• subjectAlternateName (SubjectAlternateName) - SubjectAlternativeName entries, including the application URI.
• certificateType (CertificateType) - Certificate/key type to generate (e.g. RSA or an ECC variant).
• keyLengthInBits (optional< size_t >) - Key length in bits; unset uses the type's default.

Returns: The generated key pair and certificate.

void create_certificate_signing_request_async(const CreateCsrConfig &parameters, CreateCertificateSigningRequestCompleteCallback callback) const =0

Builds a PKCS#10 certificate signing request (CSR) from parameters.

• parameters (const CreateCsrConfig &) - Subject, key, and extension parameters for the CSR.
• callback (CreateCertificateSigningRequestCompleteCallback) - Receives the DER-encoded CSR, or an ErrorDetail on failure. Never throws.

shared_ptr< const AsymmetricKeyPair > get_public_key_from_der(CertificateKeyAlgorithm keyAlgorithm, span< const byte > der) const =0

Loads a public-key-only AsymmetricKeyPair from DER-encoded public key bytes.

• keyAlgorithm (CertificateKeyAlgorithm) - Expected key algorithm of the encoded public key.
• der (span< const byte >) - DER-encoded public key (SubjectPublicKeyInfo).

Returns: A public-key-only key pair.

void sign_certificate_request_async(const SignCsrConfig &parameters, SignCsrCompleteCallback callback) const =0

Signs a PKCS#10 CSR, issuing the requested certificate.

• parameters (const SignCsrConfig &) - CSR, issuer, validity, and extension parameters.
• callback (SignCsrCompleteCallback) - Receives the issued certificate, or an ErrorDetail on failure. Never throws.

CertificateResult try_sign_certificate_request_sync(const SignCsrConfig &parameters) const noexcept

Signs a PKCS#10 CSR, blocking until complete.

• parameters (const SignCsrConfig &) - CSR, issuer, validity, and extension parameters.

Returns: The issued certificate, or an ErrorDetail on failure. Never throws.

shared_ptr< const X509Certificate > sign_certificate_request_sync(const SignCsrConfig &parameters) const

Signs a PKCS#10 CSR, blocking until complete.

• parameters (const SignCsrConfig &) - CSR, issuer, validity, and extension parameters.

Returns: The issued certificate.

void create_crl_async(shared_ptr< const X509Certificate > issuer, shared_ptr< const AsymmetricKeyPair > issuerKeys, std::vector< std::string > revokedSerialNumbers, CreateCrlCompleteCallback callback) const =0

Creates an X.509 CRL revoking the given serial numbers, signed by the issuer.

• issuer (shared_ptr< const X509Certificate >) - Issuing CA certificate.
• issuerKeys (shared_ptr< const AsymmetricKeyPair >) - Issuer key pair used to sign the CRL.
• revokedSerialNumbers (std::vector< std::string >) - Serial numbers (as strings) to mark revoked.
• callback (CreateCrlCompleteCallback) - Receives the new CRL, or an ErrorDetail on failure. Never throws.

shared_ptr< const X509Crl > create_crl_sync(shared_ptr< const X509Certificate > issuer, shared_ptr< const AsymmetricKeyPair > issuerKeys, const std::vector< std::string > &revokedSerialNumbers) const

Creates an X.509 CRL, blocking until complete.

• issuer (shared_ptr< const X509Certificate >) - Issuing CA certificate.
• issuerKeys (shared_ptr< const AsymmetricKeyPair >) - Issuer key pair used to sign the CRL.
• revokedSerialNumbers (const std::vector< std::string > &) - Serial numbers (as strings) to mark revoked.

Returns: The new CRL.

CrlResult try_create_crl_sync(shared_ptr< const X509Certificate > issuer, shared_ptr< const AsymmetricKeyPair > issuerKeys, const std::vector< std::string > &revokedSerialNumbers) const noexcept

Creates an X.509 CRL, blocking until complete.

• issuer (shared_ptr< const X509Certificate >) - Issuing CA certificate.
• issuerKeys (shared_ptr< const AsymmetricKeyPair >) - Issuer key pair used to sign the CRL.
• revokedSerialNumbers (const std::vector< std::string > &) - Serial numbers (as strings) to mark revoked.

Returns: The new CRL, or an ErrorDetail on failure. Never throws.

void validate_certificate_async(const CertificateValidationRequest &request, CertificateValidationMaterial material, CertificateValidationCompleteCallback callback) const =0

Validates a certificate against a trust list and the configured validation options.

• request (const CertificateValidationRequest &) - What is validated and how: the certificate, the issuers the peer presented (chain material only), the requested use (OPC 10000-4 Table 106, Certificate Usage; CertificateUse::ApplicationInstance when empty), the security policy the certificate must comply with (none when null), and the expected application URI and endpoint URL, when set. The request's own options and CertificateValidationRequest::trustedForThisConnection are not read here: the caller resolves them into material.
• material (CertificateValidationMaterial) - The trust material: trusted and issuer certificates, their CRLs and the resolved options.
• callback (CertificateValidationCompleteCallback) - Receives success if the certificate is trusted, or an ErrorDetail describing the rejection. A certificate whose issuer is in neither list reports Bad_CertificateChainIncomplete, with the missing issuer named in the ErrorDetail. A certificate requested as a CA without basicConstraints cA TRUE reports Bad_CertificateUseNotAllowed; a fault of an issuer reports the issuer variant of its step's code. Never throws.

void validate_crl_async(TrustListValidationOptions validationOptions, shared_ptr< const X509Crl > crl, std::vector< shared_ptr< const X509Certificate > > issuerCandidates, CrlValidationCompleteCallback callback) const =0

Validates a CRL before it is installed in a trust list (OPC 10000-12 section 7.8.2.1: the Server "will validate all new Certificates and CRLs").

• validationOptions (TrustListValidationOptions) - Options of the certificate group the CRL is installed in.
• crl (shared_ptr< const X509Crl >) - CRL to validate.
• issuerCandidates (std::vector< shared_ptr< const X509Certificate > >) - The certificates that may have issued the CRL (the trust list's trusted and issuer certificates).
• callback (CrlValidationCompleteCallback) - Receives success, or the cause with an ErrorDetail whose context names the CRL's issuer: Bad_CertificateChainIncomplete when no candidate is the issuer, Bad_SecurityChecksFailed when the signature does not verify, Bad_CertificateRevocationUnknown when the CRL is outside its validity window. Never throws.

ua::SecureString

A string that holds secret material in a buffer it owns and zeroes when it is done with it.

Intended for short-lived secrets such as decrypted passwords. The buffer is overwritten with a non-elidable scrub before it is released, so a compiler cannot optimise the wipe away. A move transfers the buffer: the moved-from instance owns no bytes and nothing is copied or left behind. A copy duplicates the secret into independent storage; copy-assignment scrubs the storage it replaces. The value may contain embedded NUL bytes: size and view report the full length, and c_str is NUL-terminated for callers that need a C string.

This bounds the time secret bytes remain resident in memory; it is not a guarantee against all disclosure (the value is plain in memory while live and may be paged or duplicated by lower layers). Move-assignment is deleted: a value may be constructed, copied or moved from, but not reassigned in place. The type is not thread-safe.

Functions

SecureString(const char *value)

Constructs from a null-terminated C string, copying its bytes.

• value (const char *) - Null-terminated source string. Must not be null. The pointed-to bytes are copied; no ownership of value is taken.

SecureString(const char *data, size_t size)

Constructs from size bytes at data, copying them.

• data (const char *) - Source bytes; may be null only when size is zero.
• size (size_t) - Number of bytes to copy.

SecureString(const SecureString &other)

Copy-constructs, duplicating the secret into independent storage.

• other (const SecureString &) - Secret whose bytes are copied into this object.

SecureString(SecureString &&other) noexcept

Move-constructs, taking other's buffer.

• other (SecureString &&) - Secret whose buffer is transferred; left empty.

SecureString & operator=(const SecureString &other)

Copy-assigns, duplicating the secret into independent storage; the storage it replaces is scrubbed.

• other (const SecureString &) - Secret whose bytes replace this object's bytes.

Returns: This object after assignment.

~SecureString()

Destroys the string, zeroing its buffer so the secret does not linger.

const char * c_str() const noexcept

Returns a pointer to the NUL-terminated value.

Returns: NUL-terminated buffer owned by this object. Valid until the string is destroyed, moved from or assigned; never null (empty yields "").

std::string_view view() const noexcept

The value with its full length, embedded NUL bytes included.

Returns: A view borrowed until destruction, move or assignment.

size_t size() const noexcept

Number of bytes in the value (embedded NUL bytes included, the terminator excluded).

Returns: The byte count excluding the terminator.

bool empty() const noexcept

Reports whether the value is empty.

Returns: True when no value bytes are stored.

ua::X509Certificate

A parsed, read-only X.509 v3 certificate.

Exposes the fields and extensions of a DER-encoded certificate (per RFC 5280) as already-decoded accessors: subject and issuer distinguished-name components, validity window, public key, key-usage / extended-key-usage flags, subject alternative names, and basic constraints. Instances are immutable once parsed and the accessors are pure (side-effect-free) - they are safe to call concurrently from any thread.

This is an abstract interface; a concrete certificate is produced by the security backend (for example from a ByteString DER blob). Implementations own the underlying parsed certificate for their lifetime.

Functions

~X509Certificate()=default

bool operator==(const X509Certificate &obj) const =0

Compares two certificates for equality.

• obj (const X509Certificate &) - Certificate to compare against.

Returns: true if the certificates are equal.

int version() const =0

Returns the zero-indexed X.509 format version: 0 for v1, 1 for v2, 2 for v3.

Returns: The zero-indexed X.509 version (0=v1, 1=v2, 2=v3).

std::string serial_number() const =0

Returns the certificate serial number as a base-10 decimal string.

Returns: The serial number as a base-10 decimal string.

ByteString signature() const =0

Returns the raw signature value over the certificate's TBS data.

Returns: The raw signature value over the certificate's TBS data.

std::string issuer() const =0

Returns the issuer name as the raw DER encoding of the X.509 Name (bytes in a string).

Returns: The issuer Name as its raw DER encoding.

std::string issuer_country() const =0

Returns the issuer country (C) attribute, or an empty string if absent.

Returns: The issuer country (C) attribute, or empty if absent.

std::string issuer_organization() const =0