PISOFT::TEAgent
#include <teagent.h>
The TEAgent class represents the Key Service Agent and forms the base class of the TEAgentMatrix and TEAgentFile classes.
© Pi Soft, 2018-2026 · Tricryption Engine 8.1
Inheritance
- Inherited by PISOFT::TEAgentFile
- Inherited by PISOFT::TEAgentMatrix
- Inherited by PISOFT::TEKey
Protected Attributes
| Type | Name | Description |
|---|---|---|
| bool | m_bEncode | |
| bool | m_bDecode | |
| bool | m_bAlloc | |
| void * | m_matrix | |
| void * | m_pConn | |
| void * | m_pCProv | |
| void * | m_pHash | |
| void * | m_pTEConn | |
| void * | m_pCipher |
Public Member Functions
| Member | Description |
|---|---|
TEAgent() | The TEAgent constructor is the default class constructor. |
TEAgent(const TEAgent &)=delete | An agent is a resource, never a value: copy construction and copy assignment are DELETED, here and for every class derived from it (TEKey, TEAgentFile, TEAgentMatrix). |
TEAgent & operator=(const TEAgent &)=delete | |
~TEAgent() | The TEAgent destructor is the class destructor. |
void setEncodeMode(bool encode) | The setEncodeMode method sets the encode mode, which determines whether the output data will be Base64 encoded. |
bool getEncodeMode() | The getEncodeMode method gets the encode mode currently in use. |
void setDecodeMode(bool decode) | The setDecodeMode method sets the decode mode, which indicates whether the input data will be Base64 decoded. |
bool getDecodeMode() | The getDecodeMode method gets the decode mode currently in use. |
void setCipher(TECipher *cipher) | The setCipher method sets the cipher object. All encryption and decryption will be performed inside agent. |
const TECipher * getCipher() const | The getCipher gets the cipher object. |
void attachConnection(uint32_t handle) | The attachConnection method attaches to a connection specified by a connection handle. |
void attachConnection(const TEConnection *conn) | The attachConnection method attaches to a connection specified by a TEConnection pointer. |
uint32_t detachConnection() | The detachConnection method detaches a connection. |
void encrypt() | The encrypt method encrypts data. |
void decrypt() | The decrypt method decrypts data. |
void encryptData(_TESTD string &data, _TESTD string &hl, const _TESTD string &iv) | The encryptData method encrypts data using a specified TTag and IV. |
void decryptData(_TESTD string &data, const _TESTD string &hl, const _TESTD string &iv) | The decryptData method decrypts data using a specified TTag and initialization vector. |
void decryptData(_TESTD string &data, const _TESTD string &hl, uint32_t less) | The decryptData method decrypts data using a specified TTag and initialization vector. |
uint32_t performHash(_TESTD vector< _TESTD pair< _TESTD string, _TESTD string > > &data) const | The performHash method hashes data. |
void performHMacSha384(const _TESTD string &hiddenLink, const _TESTD string &data, _TESTD string &mac) | The performHMacSha384 method computes a keyed hash (MAC) of data under the key a TTag names. |
void clear() | The clear method clears all internal status data. |
void reset() | The reset method clears all internal status data and detaches the connection. |
std::unique_ptr< TEAgent > clone() const | The clone method clones a TEAgent object. |
Static Public Member Functions
| Member | Description |
|---|---|
void enableFipsMode() | The enableFipsMode method switches this process into FIPS mode: every cryptographic operation the agent performs from then on is served by the CMVP-validated OpenSSL FIPS provider 3.1.2 (certificate #4985), and TLS offers NIST curves only. |
Protected Member Functions
| Member | Description |
|---|---|
void processData(long fid, char id, _TESTD string &data, _TESTD string &hl, const _TESTD string &iv, bool bHLDecode=false, bool bHLEncode=false) | The processData method processes data (for internal use only). |
Member Function Documentation
TEAgent()
The TEAgent constructor is the default class constructor.
TEAgent(const TEAgent &)=delete
An agent is a resource, never a value: copy construction and copy assignment are DELETED, here and for every class derived from it (TEKey, TEAgentFile, TEAgentMatrix).
An agent owns its matrix, hash, crypto provider, cipher, file and connection objects, so it is neither copyable nor assignable and no two agents free one of them.
~TEAgent()
The TEAgent destructor is the class destructor.
void setEncodeMode(bool encode)
The setEncodeMode method sets the encode mode, which determines whether the output data will be Base64 encoded.
Parameters
| Parameter | Description |
|---|---|
encode | A boolean value indicating whether the output data will be Base64 encoded; True = output will be Base64 encoded, False = output will not be Base64 encoded. |
bool getEncodeMode()
The getEncodeMode method gets the encode mode currently in use.
Returns: Returns a boolean value representing whether the Base64 encoding is in use; True = Base64 encoding is in use, False = Base64 encoding is not in use.
void setDecodeMode(bool decode)
The setDecodeMode method sets the decode mode, which indicates whether the input data will be Base64 decoded.
Parameters
| Parameter | Description |
|---|---|
decode | A boolean value indicating whether the input data will be Base64 decoded; True = input will be Base64 decoded, False = input will not be Base64 decoded. |
bool getDecodeMode()
The getDecodeMode method gets the decode mode currently in use.
Returns: Returns a boolean value representing whether Base64 decoding is in use; True = Base64 decoding is in use, False = Base64 decoding is not in use.
void setCipher(TECipher *cipher)
The setCipher method sets the cipher object. All encryption and decryption will be performed inside agent.
Parameters
| Parameter | Description |
|---|---|
cipher | Cipher object |
const TECipher * getCipher() const
The getCipher gets the cipher object.
Returns: Returns a pointer to cipher object
void attachConnection(uint32_t handle)
The attachConnection method attaches to a connection specified by a connection handle.
Parameters
| Parameter | Description |
|---|---|
handle | A 32-bit unsigned integer representing a connection handle for an existing connection. |
void attachConnection(const TEConnection *conn)
The attachConnection method attaches to a connection specified by a TEConnection pointer.
Parameters
| Parameter | Description |
|---|---|
conn | A constant pointer to an existing TEConnection object. |
uint32_t detachConnection()
The detachConnection method detaches a connection.
Returns: Returns an unsigned 32-bit integer representing the connection handle of the detached connection.
void encrypt()
The encrypt method encrypts data.
void decrypt()
The decrypt method decrypts data.
void encryptData(_TESTD string &data, _TESTD string &hl, const _TESTD string &iv)
The encryptData method encrypts data using a specified TTag and IV.
Parameters
| Parameter | Description |
|---|---|
data | A string of data; input is to be encrypted, output has been encrypted. |
hl | A constant string representing a TTag to be used for encryption. |
iv | A constant string representing an IV to be used for encryption. |
void decryptData(_TESTD string &data, const _TESTD string &hl, const _TESTD string &iv)
The decryptData method decrypts data using a specified TTag and initialization vector.
Parameters
| Parameter | Description |
|---|---|
data | A string of data; input is to be decrypted, output has been decrypted. |
hl | A constant string representing a TTag to be used for decryption. |
iv | A constant string representing an IV to be used for decryption. |
void decryptData(_TESTD string &data, const _TESTD string &hl, uint32_t less)
The decryptData method decrypts data using a specified TTag and initialization vector.
Parameters
| Parameter | Description |
|---|---|
data | A string of data; input is to be decrypted, output has been decrypted. |
hl | A constant string representing a TTag to be used for decryption. |
less | An integer representing . |
uint32_t performHash(_TESTD vector< _TESTD pair< _TESTD string, _TESTD string > > &data) const
The performHash method hashes data.
The hash method is SHA-256 (performHash v2); v1 outputs do not match v2 outputs and there is no compatibility mode. Note: performHash provides integrity/searchability, not strong pseudonymization of low-entropy data; for that, use a keyed construction (keyed API is a parked roadmap item).
Parameters
| Parameter | Description |
|---|---|
data | A vector of string pairs. Input: First string is data to be hashed, second string is salt to be used; Output: First string is hashed value, second string is unchanged. |
Returns: Return value represents the size of a vector.
void performHMacSha384(const _TESTD string &hiddenLink, const _TESTD string &data, _TESTD string &mac)
The performHMacSha384 method computes a keyed hash (MAC) of data under the key a TTag names.
The MAC is HMAC-SHA384 (RFC 2104 over SHA-384), computed BY THE KEY SERVER under the symmetric key the TTag names, keyed with that key's raw bytes; the key never leaves the key server. The digest is fixed at SHA-384 whatever cipher the deployment configured. The key server authorizes the caller on the key's ACL, as it does before a decrypt, and the caller needs a role granting HMAC Data. A message up to 4 MiB travels in ONE request; a longer one is sent in 4 MiB stages over the same connection (the wire caps one field at 16 MiB). This is a different operation from performHash, which is an UNKEYED salted SHA-256 computed locally. With the decode mode set, hiddenLink and data are base64 and decoded first; with the encode mode set, mac is returned base64.
Parameters
| Parameter | Description |
|---|---|
hiddenLink | The TTag of an existing key. Empty is refused locally with a TEAgentException and nothing is sent. |
data | The message; may be empty. |
mac | Output: the 48-byte MAC (or its base64). |
void clear()
The clear method clears all internal status data.
void reset()
The reset method clears all internal status data and detaches the connection.
std::unique_ptr< TEAgent > clone() const
The clone method clones a TEAgent object.
Returns: Returns a std::unique_ptr that owns a new TEAgent object.
void enableFipsMode()
The enableFipsMode method switches this process into FIPS mode: every cryptographic operation the agent performs from then on is served by the CMVP-validated OpenSSL FIPS provider 3.1.2 (certificate #4985), and TLS offers NIST curves only.
Call it before any connection is opened. The provider module and its configuration are loaded from the ossl-modules directory installed beside te_agent (fips.so and fipsmodule.cnf; fips.dll on Windows); no environment variable is read. Fail-closed: when FIPS mode cannot be honoured – a missing module directory, a missing configuration, a module whose integrity check or self-test fails – it throws, and the process is left refusing algorithms rather than serving them outside the module. In FIPS mode ML-KEM, ML-DSA, X25519 and MD5 are not available. A second call is harmless.
Exceptions
| Exception | Description |
|---|---|
TEAgentException | "FIPS mode unavailable: <cause>" when FIPS mode is not in force. |
void processData(long fid, char id, _TESTD string &data, _TESTD string &hl, const _TESTD string &iv, bool bHLDecode=false, bool bHLEncode=false)
The processData method processes data (for internal use only).
Parameters
| Parameter | Description |
|---|---|
fid | Function ID |
id | operation ID |
data | String of data to be processed |
hl | A string representing the TTag |
iv | String of IV |
bHLDecode | Decoding TTag for input |
bHLEncode | Encoding TTag for output |