C++ API Programming Guide

© Pi Soft, 2018-2026 · Tricryption Engine 8.1

The Tricryption Engine C++ API comprises two groups of components: TEAgent (cryptographic operations) and TEAdmin (administration). All classes live in the PISOFT namespace, so either bring it into scope with using namespace PISOFT; or prefix class names with PISOFT::.

TEAgent components

The TEAgent group provides functionality such as encrypting, decrypting and hashing data. The general procedure is:

Create a PISOFT::TEConnection object and open a connection to a Key Server.
Create a working object of a class such as PISOFT::TEAgentMatrix and attach it to the connection object.
Use the working object to encrypt, decrypt or hash.
Detach the working object and close the connection.

Environment settings

Include the public headers (teagent.h, teexception.h, and so on) and build against the agent library.

Windows (Microsoft Visual C++): link against the import library and ship the agent DLL with your application.
Linux: link against the shared object.

FIPS mode

Call the static PISOFT::TEAgent::enableFipsMode() once, before any connection is opened, to run every cryptographic operation of the agent through the CMVP-validated OpenSSL FIPS provider 3.1.2 (certificate #4985). The provider module and its configuration are loaded from the ossl-modules directory installed beside the agent library (fips.so and fipsmodule.cnf; fips.dll on Windows); ship that directory unmodified with your application. No environment variable is read.

The call is fail-closed: when FIPS mode cannot be honoured it throws PISOFT::TEAgentException with the message FIPS mode unavailable: followed by the cause, and the agent then serves no algorithm outside the module. In FIPS mode TLS offers the NIST curves P-384 and P-256 only; ML-KEM, ML-DSA, X25519 and MD5 are unavailable, and RSA keys are 2048 bits or more.

try {
    PISOFT::TEAgent::enableFipsMode();
} catch (PISOFT::TEAgentException& e) {
    // refuse to continue: FIPS mode was required and is not in force
}

Creating a connection

Use PISOFT::TEConnection. Create a connection object of the desired type — normal or secure (TLS) — then call its open() method with the server name, port and authentication context (or, for a native user, the server name, port, username and password). The TEConnection object is destroyed automatically when its smart pointer goes out of scope, so there is no need to delete it explicitly.

Examples: cpp_connect.cpp (agent), cpp_admin_connect.cpp (secure/admin), and the per-method cpp_connect_*.cpp samples for each authentication type.

Kerberos login

PISOFT::TEGssapiAuthenticationContext (teauthgssapictx.h) logs in with a Kerberos ticket the caller already holds, through the Key Server's GSSAPIAuthentication module (AM10). The Key Server must have the module enabled; the operator steps are in the repository's docs/KERBEROS_AM10.md.

Name three things on the context, then open a secure connection with it:

setServicePrincipal() — the Key Server's acceptor principal, the name its keytab holds, e.g. te/ks.example.com@EXAMPLE.COM. A ticket for any other service is refused.
setCredentialCache() — the credential cache to initiate from, e.g. FILE:/run/user/1000/krb5cc; leave it unset (empty) for the Kerberos library's default cache.
setServerAnchorFile() — required: a file holding the certificate the connection trusts the Key Server by (one or more PEM certificates, or one DER certificate — normally the Key Server's CA). Before any Kerberos token is sent, the Key Server's presented chain is verified against it with no error forgiven; an anchor that is not self-signed pins that certificate.

#include <iostream>
#include "teconnection.h"
#include "teauthgssapictx.h"
#include "teexception.h"

using namespace PISOFT;

int main()
{
    try
    {
        std::unique_ptr<TEConnection> conn =
            TEConnection::createInstance(TEConnection::SecureConnection);
        std::unique_ptr<TEGssapiAuthenticationContext> ctx =
            TEGssapiAuthenticationContext::getInstance();
        ctx->setServicePrincipal("te/ks.example.com@EXAMPLE.COM");
        ctx->setCredentialCache("");                    // the default cache
        ctx->setServerAnchorFile("/etc/te/ks-ca.pem");  // required
        conn->open("ks.example.com", 8888, *ctx);
        std::cout << "logged in as " << ctx->getInitiatorName().c_str() << std::endl;
        conn->close();
    }
    catch (TEException& e)
    {
        std::cout << e.getAllMessages().c_str() << std::endl;
        return 1;
    }
    return 0;
}

The binding is carried for you. The context reads the connection's RFC 9266 channel binding (tls-exporter, the value PISOFT::TEConnection::getChannelBinding returns) and passes it into the GSS-API exchange, with mutual authentication requested. Nothing in the API asks you for it; the Key Server accepts the login only when the exchange is bound to the connection it arrived on, so a relay that terminates TLS cannot forward it. The caller's Kerberos profile (krb5.conf, or KRB5_CONFIG) must declare client_aware_channel_bindings = true under [libdefaults], or the Key Server refuses the login as unbound.

After open() returns, getInitiatorName() is the Kerberos name the credentials authenticated as (alice@EXAMPLE.COM); the session itself is the LDAP principal the Key Server resolved that name to through its directory.

Refusals arrive as an PISOFT::TEAgentException whose message names the check:

before any token — GSSAPI initiator: no key server anchor set (setServerAnchorFile) -- a Kerberos login names the key server it trusts, or the key server's certificate did not verify: <reason>;
from the Key Server — GSSAPI: the exchange is not bound to this connection (GSS_C_CHANNEL_BOUND_FLAG not set) (the profile setting above), GSSAPI: channel binding mismatch (GSS_S_BAD_BINDINGS) -- the exchange was not bound to this connection (a relay in the path), GSSAPI: the security context was not established (a ticket for another service, or none), GSSAPI: no directory entry carries <attribute>=<name> and GSSAPI: the directory entry <dn> is not an enrolled LDAP principal (<reason>) (the directory mapping), and Authentication Protocol Mismatch (the module is not enabled on that Key Server).

Windows. The client library imports gssapi64.dll from the product's MIT Kerberos package; ship it, with krb5_64.dll, comerr64.dll and k5sprt64.dll (which it imports), on the application's PATH beside the agent DLL. No Kerberos KDC is bundled on either platform.

Working with a data matrix

PISOFT::TEAgentMatrix represents a 2-D data matrix whose indices start at 1. Data in the matrix can be encrypted, decrypted or hashed. To encrypt or decrypt, populate the matrix and set Hidden Links as needed, attach it to a connection, and call the matrix operation. Hashing with a matrix does not require a connection to a Tricryption Engine. Examples: cpp_matrix_encrypt.cpp, cpp_matrix_hash.cpp.

Working with a file

PISOFT::TEAgentFile encrypts and decrypts a file given its path. Set the input and output paths and call the encrypt/decrypt operation. Example: cpp_file.cpp.

Administration (TEAdmin)

The TEAdmin group manages a Tricryption Engine — adding principals, changing passwords, assigning roles, and so on. The general procedure is:

Create a PISOFT::TEConnection object in secure mode and open a connection to the Tricryption Engine.
Create an PISOFT::TEAdmin working object and attach the connection to it.
Use the TEAdmin methods (and the related PISOFT::TEAdminACL, PISOFT::TEAdminLocal, PISOFT::TEAdminLicense, PISOFT::TEAdminLog classes) to perform administrative tasks.

Common tasks — managing principals, roles and groups; working with access-control lists; taking a Remote Engine online/offline; and querying license, version and system information — are shown in the cpp_admin_*.cpp examples.

Note: Principal, role and group identifiers use the 64-bit PISOFT::te_oid type (uint64_t). Code written against earlier 32-bit identifiers must be updated accordingly.

TEAgent components​

Environment settings​

FIPS mode​

Creating a connection​

Kerberos login​

Working with a data matrix​

Working with a file​

Administration (TEAdmin)​