C API
#include "teagent_c.h"
The teagent_c.h header file contains the Pi-Soft Agent C API function definitions.
The teagent_c.h header file requires libte_agent_c.so (Linux) or te_agent_c.dll and te_agent_c.lib (Windows) in order to compile and run C code.
© Pi Soft, 2018-2026 · Tricryption Engine 8.1
Return codes and types
| Member | Description |
|---|---|
TE_SUCCESS | The operation completed successfully. Zero; test for it with TE_IS_SUCCESS. |
TE_BUFFER_ERROR_MASK | Masks a return code as a buffer error. |
TE_OPENSSL_ERROR_MASK | Masks a return code as an error raised inside OpenSSL rather than by the agent itself. |
TE_FAILURE_MASK | Masks a return code as a failure. Every failure code carries this bit or a more specific mask that includes it; TE_IS_FAILED tests for it. |
TE_CRYPT_ERROR_MASK | Masks a return code as a failure of a cryptographic operation. |
TE_SERVER_ERROR_MASK | Masks a return code as a failure reported by the Key Service rather than detected locally. GetLastTEError renders these as "... in server operation". |
TE_FAILURE | The operation failed and no more specific code applies. |
TE_NULL_POINTER | A required pointer argument was NULL, or the connection handle was NULL. |
TE_TYPE_NOT_SUPPORTED | The network layer was asked to handle a packet or connection type it does not implement. |
TE_INSUFFICIENT_RESOURCES | A required allocation failed, or a size argument was zero where a non-empty buffer was required. |
TE_COMMUNICATION_ERROR | The exchange with the server ended in an unexpected state - the peer closed the connection, or answered with a packet other than the one the protocol expects. |
TE_ZERO_DATA_ERROR | The server returned an empty result, or a length argument was zero where the call requires data. |
TE_NOT_SUPPORTED | Reserved. Defined for completeness of the code space; no C API function currently returns it. |
TE_SSL_ERROR | A TLS operation on the connection failed. The underlying OpenSSL diagnosis is available through GetLastTEError. |
TE_INVALID_FORMAT | Data supplied to the call is malformed - for example a base64 argument whose length is not a multiple of four, or which contains characters outside the alphabet. |
TE_OVERFLOW | Reserved. Defined for completeness of the code space; no C API function currently returns it. |
TE_GENERATE_KEY_FAILED | The Key Service could not generate the requested key. |
TE_AUTHENTICATION_ERROR | The credentials were rejected, so no session was established. |
TE_INVALID_CONNECTION_TYPE | The call requires a TLS connection (TE_SSL_CONNECTION) but the handle refers to a plain one. |
TE_INVALID_DATA | An argument is present but not usable for this call - a zero length, or a declared length larger than the buffer that carries it. |
TE_NOT_AVAILABLE | The addressed item does not exist - for example a matrix row or cell that was never set. |
TE_AUTHORIZATION_FAIL | The principal authenticated successfully but is not permitted to perform the requested operation. |
TE_ENCRYPTION_FAIL | The data could not be encrypted. |
TE_DECRYPTION_FAIL | The data could not be decrypted - commonly a T-tag that does not match the ciphertext, or a key the caller may not use. |
TE_INSUFFICIENT_BUFFER_SIZE | The buffer supplied by the caller is too small for the result. Where the call also returns a required-size argument, that argument is set before returning. |
TE_FIPS_MODE_UNAVAILABLE | FIPS mode was requested and cannot be honoured - the validated FIPS provider module or its configuration is missing, does not load, or fails its self-test. The process is left refusing every algorithm rather than serving it from the default provider. |
TE_IS_SUCCESS | Evaluates to true when a TE_RETCODE reports success. |
TE_IS_FAILED | Evaluates to true when a TE_RETCODE reports any failure, of any category. |
uint32_t * TE_HANDLE | A pointer to an unsigned 32-bit integer representing the handle. |
uint32_t TE_RETCODE | An unsigned 32-bit integer representing the return code. |
Connections and sessions
| Member | Description |
|---|---|
TE_NORMAL_CONNECTION | A normal, unencrypted connection to the Pi-Soft services. |
TE_SSL_CONNECTION | A secure (TLS) connection to the Pi-Soft services. |
TE_RETCODE TEEnvInit() | The TEEnvInit function initializes the Pi-Soft client environment. |
TE_RETCODE TEEnvClose() | The TEEnvClose function closes the Pi-Soft client environment. |
TE_RETCODE TEEnableFipsMode() | The TEEnableFipsMode function 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. |
TE_HANDLE OpenConnectionWithToken(const int32_t type, const char *svrName, int32_t svrPort, const char *token, const int32_t tokenl) | The OpenConnectionWithToken function connects an existing session to the Key Services. |
TE_HANDLE OpenConnectionWithLDAPUser(const int32_t type, const char *svrName, int32_t svrPort, const char *userName, const char *password) | The OpenConnectionWithLDAPUser function connects a LDAP User to the Key Services. |
TE_HANDLE OpenConnectionWithNativeUser(const int32_t type, const char *svrName, int32_t svrPort, const char *userName, int32_t nlength, const char *password, int32_t plength) | The OpenConnectionWithNativeUser function connects a Native User to the Key Services. |
TE_HANDLE OpenConnectionWithPrivateKeyAndCertificateChainFiles(const char *svrName, int32_t svrPort, const char *pkfile, const char *certfile, const char *password, int32_t plength) | The OpenConnectionWithPrivateKeyAndCertificateChainFiles function connects a certificate User to the Key Services. |
TE_HANDLE OpenConnectionWithPKCS12File(const char *svrName, int32_t svrPort, const char *pkcs12file, const char *password, int32_t plength) | The OpenConnectionWithPKCS12File function connects a certificate User to the Key Services. |
TE_HANDLE OpenConnectionWithPrivateKeyAndCertificateChainFilesAnchored(const char *svrName, int32_t svrPort, const char *pkfile, const char *certfile, const char *password, int32_t plength, const char *anchorfile) | The OpenConnectionWithPrivateKeyAndCertificateChainFilesAnchored function is OpenConnectionWithPrivateKeyAndCertificateChainFiles naming the certificate the connection trusts the Key Services by. |
TE_HANDLE OpenConnectionWithPKCS12FileAnchored(const char *svrName, int32_t svrPort, const char *pkcs12file, const char *password, int32_t plength, const char *anchorfile) | The OpenConnectionWithPKCS12FileAnchored function is OpenConnectionWithPKCS12File naming the certificate the connection trusts the Key Services by. |
TE_HANDLE OpenConnectionWithKerberos(const char *svrName, int32_t svrPort, const char *servicePrincipal, const char *ccache, const char *anchorfile) | The OpenConnectionWithKerberos function opens a TLS connection to the Key Services and authenticates the caller's Kerberos credentials through GSS-API, bound to that connection, by the Key Services' AM10 module. |
TE_RETCODE CloseConnection(TE_HANDLE h) | The CloseConnection function closes the TLS connection to the Key Services. |
TE_RETCODE GetToken(TE_HANDLE h, char *tokenbuf, int32_t *tokenbufl) | The GetToken function retrieves a token from an existing open connection to the Key Services. |
uint32_t GetLastTEError(char *szErr, uint32_t *nLength) | The GetLastTEError retrieves the last Error String and Error Code. |
TE_RETCODE CurrentLogonPrincipalId(TE_HANDLE h, uint64_t *PrincID) | The CurrentLogonPrincipalId function retrieves a Principal ID of an existing open connection to the Key Services. |
Keys
| Member | Description |
|---|---|
TE_KEY_BLOB_SIZE | The size of the Key blob. |
TE_DEFAULT_HIDDEN_LINK_LEN | The size of the TTag. |
TE_HMAC_SHA384_LEN | The length of an HMAC-SHA384 MAC, in bytes. |
struct TE_STRU_BUFFER * TE_STRU_BUFFER_PTR | The *TE_STRU_BUFFER_PTR is a pointer to TE_STRU_BUFFER. |
struct TE_KEY_BUFFER * TE_KEY_BUFFER_PTR | Structure of TE_KEY_BUFFER. |
TE_RETCODE TESetCipherAlgorithm(TE_HANDLE h, char *algorithm) | The TESetCipherAlgorithm function sets the cryptographic cipher for encryption. |
TE_RETCODE TECreateKey(TE_HANDLE h, char *algorithm, char *acl, unsigned char *Ttagbuff, int32_t Ttagbuffsiz, int32_t *TtagL) | The TECreateKey function allows the developer to create a key. |
TE_RETCODE TEExportKey(TE_HANDLE h, uint32_t SysID, uint64_t PrincID, TE_KEY_BUFFER_PTR) | The TEExportKey function retrieves a key for export. |
TE_RETCODE TEExportMultiKeys(TE_HANDLE h, uint32_t SysID, uint64_t PrincID, TE_KEY_BUFFER_PTR, int32_t number) | The TEExportMultiKey function retrieves many keys for export. |
TE_RETCODE TEHmacSha384(TE_HANDLE h, const unsigned char *hiddenLink, uint32_t hiddenLinkLen, const unsigned char *data, uint32_t dataLen, unsigned char *mac, uint32_t *macLen) | The TEHmacSha384 function computes a keyed hash (MAC) of data under a key the caller names by its TTag. |
String encryption
| Member | Description |
|---|---|
TE_MAX_CSTRING_BATCH | The largest number of strings one call may carry. |
TE_RETCODE TEEncryptStringBatch(TE_HANDLE h, TE_CSTRING_BUFFER *Ttag, TE_CSTRING_BUFFER *buffers, uint32_t count) | Encrypts a batch of C strings under one T-tag. |
TE_RETCODE TEDecryptStringBatch(TE_HANDLE h, TE_CSTRING_BUFFER *Ttag, TE_CSTRING_BUFFER *buffers, uint32_t count) | Decrypts a batch of C strings under one T-tag. |
Matrix encryption
| Member | Description |
|---|---|
TE_HANDLE TE_MATRIX_HANDLE | A pointer to an unsigned 32-bit integer representing the matrix handle. |
TE_MATRIX_HANDLE TEMatrixCreate() | The TEMatrixCreate function creates a matrix handle. |
void TEMatrixSetEncode(TE_MATRIX_HANDLE mh, uint32_t SetEnc) | The TEMatrixSetEncode function sets the encode method for when the get-method is called. |
uint32_t TEMatrixGetEncode(TE_MATRIX_HANDLE mh) | The TEMatrixGetEncode function gets the encode method for the TE_MATRIX_HANDLE. |
void TEMatrixSetDecode(TE_MATRIX_HANDLE mh, uint32_t decode) | The TEMatrixSetDecode function sets the decode method for when the set-method is called. |
uint32_t TEMatrixGetDecode(TE_MATRIX_HANDLE mh) | The TEMatrixGetDecode function sets the decode method for when the set-method is called. |
TE_RETCODE TEMatrixSetElement(TE_MATRIX_HANDLE mh, uint32_t row, uint32_t col, const unsigned char *dbuff, uint32_t dsiz) | The TEMatrixSetElement function adds or changes elements. |
TE_RETCODE TEMatrixGetElement(TE_MATRIX_HANDLE mh, uint32_t row, uint32_t col, unsigned char *dbuff, uint32_t dsiz, uint32_t *rdsiz) | The TEMatrixGetElement function returns an element. |
TE_RETCODE TEMatrixSetHiddenLink(TE_MATRIX_HANDLE mh, uint32_t row, const unsigned char *Ttagbuff, uint32_t TtagL) | The TEMatrixSetHiddenLink function sets the TTag for a matrix. |
TE_RETCODE TEMatrixGetHiddenLink(TE_MATRIX_HANDLE mh, uint32_t row, unsigned char *Ttagbuff, uint32_t Ttagsiz, uint32_t *TtagL) | The TEMatrixGetHiddenLink function gets the TTag for a matrix. |
TE_RETCODE TEMatrixEncrypt(TE_HANDLE h, TE_MATRIX_HANDLE mh) | The TEMatrixEncrypt function encrypts a matrix. |
TE_RETCODE TEMatrixDecrypt(TE_HANDLE h, TE_MATRIX_HANDLE mh) | The TEMatrixDecrypt function decrypts a matrix. |
TE_RETCODE TEMatrixRelease(TE_MATRIX_HANDLE mh) | The TEMatrixRelease function releases a matrix. |
Administration
| Member | Description |
|---|---|
TE_RETCODE TEGetSystemId(TE_HANDLE h, uint32_t *SysID) | The TEGetSystemId function retrieves the System ID of an existing open connection to the Key Services. |
Hashing
| Member | Description |
|---|---|
TE_RETCODE Hash(const char *szData, const unsigned long nDataSize, char *szHashed, unsigned long *nHashedSize, const char *szSalt, const unsigned long nSaltSize) | The Hash function hashes data. |
Function Documentation
TE_RETCODE TEEnvInit()
The TEEnvInit function initializes the Pi-Soft client environment.
Remark: Required before connection
Returns: If the function succeeds, it will have a return value of zero. If the function fails, it will have a non-zero return value. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE TEEnvClose()
The TEEnvClose function closes the Pi-Soft client environment.
Remark: After running, token and handle are cleared. Use to properly shut down the agent.
Returns: If the function succeeds, it will have a return value of zero. If the function fails, it will have a non-zero return value. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE TEEnableFipsMode()
The TEEnableFipsMode function 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.
Remark: Call it before any connection is opened. The provider module and its configuration are loaded from the ossl-modules directory installed beside te_agent_c (fips.so and fipsmodule.cnf; fips.dll on Windows); no environment variable is read. The call is fail-closed: when FIPS mode cannot be honoured it returns TE_FIPS_MODE_UNAVAILABLE, GetLastTEError describes the cause (a missing module directory, a missing configuration, a module whose integrity check or self-test fails), 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.
Returns: TE_SUCCESS (zero) when FIPS mode is in force; TE_FIPS_MODE_UNAVAILABLE otherwise.
TE_HANDLE OpenConnectionWithToken(const int32_t type, const char *svrName, int32_t svrPort, const char *token, const int32_t tokenl)
The OpenConnectionWithToken function connects an existing session to the Key Services.
Parameters
| Parameter | Description |
|---|---|
type | A 32-bit integer representing the connection type ie. TE_SSL_CONNECTION |
svrName | A string representing the Key Services server name or IP ie. sampleserver or 192.168.10.1 |
svrPort | A 32-bit integer representing Key Services port ie. 8888 |
token | A string representing the existing session token |
tokenl | A 32-bit integer representing the length of the token |
Remark: Requires a session token previously obtained from GetToken on an authenticated connection; it re-uses that session rather than authenticating again.
See also: TE_SSL_CONNECTION TE_HANDLE
Returns: If the function succeeds, it will have a non-zero return value that represents the connection. If the function fails, it will have a return value of zero. Detailed error information may be obtained by calling the GetLastTEError function.
TE_HANDLE OpenConnectionWithLDAPUser(const int32_t type, const char *svrName, int32_t svrPort, const char *userName, const char *password)
The OpenConnectionWithLDAPUser function connects a LDAP User to the Key Services.
Parameters
| Parameter | Description |
|---|---|
type | A 32-bit integer representing the connection type ie. TE_SSL_CONNECTION |
svrName | A string representing the Key Services server name or IP ie. sampleserver or 192.168.10.1 |
svrPort | A 32-bit integer representing Key Services port ie. 8888 |
userName | A string representing the LDAP user's id |
password | A string representing the LDAP user's password |
Remark: This requires LDAP authentication to be setup in the Key Services
See also: TE_SSL_CONNECTION TE_HANDLE
Returns: If the function succeeds, it will have a non-zero return value that represents the connection. If the function fails, it will have a return value of zero. Detailed error information may be obtained by calling the GetLastTEError function.
TE_HANDLE OpenConnectionWithNativeUser(const int32_t type, const char *svrName, int32_t svrPort, const char *userName, int32_t nlength, const char *password, int32_t plength)
The OpenConnectionWithNativeUser function connects a Native User to the Key Services.
Parameters
| Parameter | Description |
|---|---|
type | A 32-bit integer representing the connection type ie. TE_SSL_CONNECTION |
svrName | A string representing the Key Services server name or IP ie. sampleserver or 192.168.10.1 |
svrPort | A 32-bit integer representing Key Services port ie. 8888 |
userName | A string representing the Native user's id |
nlength | A 32-bit integer representing the length of the user's id |
password | A string representing the Native user's password |
plength | A 32-bit integer representing the length of the user's password |
Remark: No additional authentication needs to be setup in the Key Services
See also: TE_SSL_CONNECTION TE_HANDLE
Returns: If the function succeeds, it will have a non-zero return value that represents the connection. If the function fails, it will have a return value of zero. Detailed error information may be obtained by calling the GetLastTEError function.
TE_HANDLE OpenConnectionWithPrivateKeyAndCertificateChainFiles(const char *svrName, int32_t svrPort, const char *pkfile, const char *certfile, const char *password, int32_t plength)
The OpenConnectionWithPrivateKeyAndCertificateChainFiles function connects a certificate User to the Key Services.
Parameters
| Parameter | Description |
|---|---|
svrName | A string representing the Key Services server name or IP ie. sampleserver or 192.168.10.1 |
svrPort | A 32-bit integer representing Key Services port ie. 8888 |
pkfile | A string representing the location of the PKCS 8 - private key file |
certfile | A string representing the location of the PKCS 7 - certificate chain file |
password | A string representing the Native user's password |
plength | A 32-bit integer representing the length of the user's password |
Remark: No additional authentication needs to be setup in the Key Services. Can only be authenticated on TLS port
See also: TE_SSL_CONNECTION TE_HANDLE
Returns: If the function succeeds, it will have a non-zero return value that represents the connection. If the function fails, it will have a return value of zero. Detailed error information may be obtained by calling the GetLastTEError function.
TE_HANDLE OpenConnectionWithPKCS12File(const char *svrName, int32_t svrPort, const char *pkcs12file, const char *password, int32_t plength)
The OpenConnectionWithPKCS12File function connects a certificate User to the Key Services.
Parameters
| Parameter | Description |
|---|---|
svrName | A string representing the Key Services server name or IP ie. sampleserver or 192.168.10.1 |
svrPort | A 32-bit integer representing Key Services port ie. 8888 |
pkcs12file | A string representing the location of the user's PKCS 12 file |
password | A string representing the Native user's password |
plength | A 32-bit integer representing the length of the user's password |
Remark: Certificate User needs to be added to the Key Services. Can only be authenticated on TLS port.
See also: TE_SSL_CONNECTION TE_HANDLE
Returns: If the function succeeds, it will have a non-zero return value that represents the connection. If the function fails, it will have a return value of zero. Detailed error information may be obtained by calling the GetLastTEError function.
TE_HANDLE OpenConnectionWithPrivateKeyAndCertificateChainFilesAnchored(const char *svrName, int32_t svrPort, const char *pkfile, const char *certfile, const char *password, int32_t plength, const char *anchorfile)
The OpenConnectionWithPrivateKeyAndCertificateChainFilesAnchored function is OpenConnectionWithPrivateKeyAndCertificateChainFiles naming the certificate the connection trusts the Key Services by.
Parameters
| Parameter | Description |
|---|---|
svrName | A string representing the Key Services server name or IP ie. sampleserver or 192.168.10.1 |
svrPort | A 32-bit integer representing Key Services port ie. 8888 |
pkfile | A string representing the location of the PKCS 8 - private key file |
certfile | A string representing the location of the PKCS 7 - certificate chain file |
password | A string representing the Native user's password |
plength | A 32-bit integer representing the length of the user's password |
anchorfile | A string representing the location of a file holding one or more PEM X.509 certificates, or one DER certificate; NULL for none |
Remark: The connection verifies the Key Services' certificate chain against the certificates of the caller's own chain plus the anchor, and refuses it otherwise; the refusal names the reason ("the key server's certificate did not verify: ..."). Name an anchor when the chain does not carry the Key Services' CA – a certificate issued by the Key Services carries it. An anchor that is not self-signed pins that certificate.
See also: TE_SSL_CONNECTION TE_HANDLE
Returns: If the function succeeds, it will have a non-zero return value that represents the connection. If the function fails, it will have a return value of zero. Detailed error information may be obtained by calling the GetLastTEError function.
TE_HANDLE OpenConnectionWithPKCS12FileAnchored(const char *svrName, int32_t svrPort, const char *pkcs12file, const char *password, int32_t plength, const char *anchorfile)
The OpenConnectionWithPKCS12FileAnchored function is OpenConnectionWithPKCS12File naming the certificate the connection trusts the Key Services by.
Parameters
| Parameter | Description |
|---|---|
svrName | A string representing the Key Services server name or IP ie. sampleserver or 192.168.10.1 |
svrPort | A 32-bit integer representing Key Services port ie. 8888 |
pkcs12file | A string representing the location of the user's PKCS 12 file |
password | A string representing the Native user's password |
plength | A 32-bit integer representing the length of the user's password |
anchorfile | A string representing the location of a file holding one or more PEM X.509 certificates, or one DER certificate; NULL for none |
Remark: The connection verifies the Key Services' certificate chain against the certificates of the PKCS 12 file's chain plus the anchor, and refuses it otherwise; the refusal names the reason ("the key server's certificate did not verify: ..."). Name an anchor when the chain does not carry the Key Services' CA. An anchor that is not self-signed pins that certificate.
See also: TE_SSL_CONNECTION TE_HANDLE
Returns: If the function succeeds, it will have a non-zero return value that represents the connection. If the function fails, it will have a return value of zero. Detailed error information may be obtained by calling the GetLastTEError function.
TE_HANDLE OpenConnectionWithKerberos(const char *svrName, int32_t svrPort, const char *servicePrincipal, const char *ccache, const char *anchorfile)
The OpenConnectionWithKerberos function opens a TLS connection to the Key Services and authenticates the caller's Kerberos credentials through GSS-API, bound to that connection, by the Key Services' AM10 module.
Parameters
| Parameter | Description |
|---|---|
svrName | A string representing the Key Services server name or IP ie. sampleserver or 192.168.10.1 |
svrPort | A 32-bit integer representing Key Services port ie. 8888 |
servicePrincipal | A string naming the Key Services' acceptor principal, e.g. te/ks.example.test@EXAMPLE.TEST |
ccache | A string naming the Kerberos credential cache to initiate from, e.g. FILE:/run/user/1000/krb5cc; NULL or empty for the library's default |
anchorfile | A string representing the location of a file holding one or more PEM X.509 certificates, or one DER certificate – the certificate the connection trusts the Key Services by |
Remark: The connection verifies the Key Services' certificate chain against the anchor before any Kerberos token is sent, and refuses it otherwise; the refusal names the reason ("the key server's certificate did not verify: ..."). The anchor is REQUIRED – a Kerberos exchange does not authenticate the TLS endpoint – and a NULL or empty anchorfile is refused by name. The exchange carries the connection's RFC 9266 channel binding (tls-exporter) with mutual authentication; the Key Services resolve the Kerberos principal through their directory to an enrolled LDAP principal. The initiator's Kerberos profile must declare client_aware_channel_bindings = true, or the Key Services refuse the exchange as unbound.
See also: TE_SSL_CONNECTION TE_HANDLE
Returns: If the function succeeds, it will have a non-zero return value that represents the connection. If the function fails, it will have a return value of zero. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE CloseConnection(TE_HANDLE h)
The CloseConnection function closes the TLS connection to the Key Services.
Parameters
| Parameter | Description |
|---|---|
h | A pointer to an unsigned 32-bit integer representing the handle. |
Remark: Once closed, TE_HANDLE can no longer be used
See also: TE_HANDLE
Returns: If the function succeeds, it will have a return value of zero. If the function fails, it will have a non-zero return value. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE GetToken(TE_HANDLE h, char *tokenbuf, int32_t *tokenbufl)
The GetToken function retrieves a token from an existing open connection to the Key Services.
Parameters
| Parameter | Description |
|---|---|
h | A pointer to an unsigned 32-bit integer representing the handle. |
tokenbuf | A string representing the token buffer |
tokenbufl | A 32-bit integer representing the token buffer length (in/out) |
Remark: The token can then be used for further authentication requests while still valid
See also: OpenConnectionWithToken
Returns: If the function succeeds, it will have a return value of zero. If the function fails, it will have a non-zero return value. Detailed error information may be obtained by calling the GetLastTEError function.
uint32_t GetLastTEError(char *szErr, uint32_t *nLength)
The GetLastTEError retrieves the last Error String and Error Code.
Parameters
| Parameter | Description |
|---|---|
szErr | A string representing the Error verbage ie. char szErr[1024] |
nLength | A 32-bit unsigned integer representing the Error length ie. uint32_t nLength = 1024 |
Remark: The Principal ID can then be used in other functions
See also:
Returns: The error code.
TE_RETCODE CurrentLogonPrincipalId(TE_HANDLE h, uint64_t *PrincID)
The CurrentLogonPrincipalId function retrieves a Principal ID of an existing open connection to the Key Services.
Parameters
| Parameter | Description |
|---|---|
h | A pointer to an unsigned 32-bit integer representing the handle. |
PrincID | A 64-bit unsigned integer representing the Principl ID |
Remark: The Principal ID can then be used in other functions
See also: TE_HANDLE
Returns: If the function succeeds, it will have a return value of zero. If the function fails, it will have a non-zero return value. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE TESetCipherAlgorithm(TE_HANDLE h, char *algorithm)
The TESetCipherAlgorithm function sets the cryptographic cipher for encryption.
Parameters
| Parameter | Description |
|---|---|
h | A pointer to an unsigned 32-bit integer representing the handle. |
algorithm | A string representing the algorithm: AES-256-CBC, AES-192-CBC or AES-128-CBC |
Remark: The System ID can then be used in other functions
See also: TE_HANDLE AES CBC
Returns: A 0 for success
TE_RETCODE TECreateKey(TE_HANDLE h, char *algorithm, char *acl, unsigned char *Ttagbuff, int32_t Ttagbuffsiz, int32_t *TtagL)
The TECreateKey function allows the developer to create a key.
all functions defined below are for internal use only, no export through dynamic libraries
Parameters
| Parameter | Description |
|---|---|
h | A pointer to an unsigned 32-bit integer representing the handle. |
algorithm | A string representing the algorithm. ie. AES-256-CBC, AES-192-CBC, AES-128-CBC |
acl | A string representing the acl template name |
Ttagbuff | A 32-bit unsigned string representing the TTag buffer |
Ttagbuffsiz | A 32-bit integer representing the TTag buffer size |
TtagL | A 32-bit unsigned integer representing the TTag length |
Remark: The System ID can then be used in other functions
See also: TE_HANDLE TESetCipherAlgorithm
Returns: If the function succeeds, it will have a return value of zero. If the function fails, it will have a non-zero return value. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE TEExportKey(TE_HANDLE h, uint32_t SysID, uint64_t PrincID, TE_KEY_BUFFER_PTR)
The TEExportKey function retrieves a key for export.
Parameters
| Parameter | Description |
|---|---|
h | A pointer to an unsigned 32-bit integer representing the handle. |
SysID | A 32-bit unsigned integer representing the System ID |
PrincID | A 64-bit unsigned integer representing the Principl ID |
Remark: The System ID can then be used in other functions
See also: TE_HANDLE TEGetSystemId
Returns: If the function succeeds, it will have a return value of zero. If the function fails, it will have a non-zero return value. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE TEExportMultiKeys(TE_HANDLE h, uint32_t SysID, uint64_t PrincID, TE_KEY_BUFFER_PTR, int32_t number)
The TEExportMultiKey function retrieves many keys for export.
Parameters
| Parameter | Description |
|---|---|
h | A pointer to an unsigned 32-bit integer representing the handle. |
SysID | A 32-bit unsigned integer representing the System ID |
PrincID | A 64-bit unsigned integer representing the Principl ID |
number | A 32-bit integer number of key data |
Remark: The System ID can then be used in other functions
See also: TE_HANDLE TEGetSystemId
Returns: If the function succeeds, it will have a return value of zero. If the function fails, it will have a non-zero return value. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE TEHmacSha384(TE_HANDLE h, const unsigned char *hiddenLink, uint32_t hiddenLinkLen, const unsigned char *data, uint32_t dataLen, unsigned char *mac, uint32_t *macLen)
The TEHmacSha384 function computes a keyed hash (MAC) of data under a key the caller names by its TTag.
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 first authorizes the caller on the key's ACL, exactly as it does before a decrypt, and the caller needs a role granting the HMAC Data operation. 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), and the MAC is the same either way.
Parameters
| Parameter | Description |
|---|---|
h | A pointer to an unsigned 32-bit integer representing the handle. |
hiddenLink | The TTag of an existing key. An empty TTag is refused locally with TE_INVALID_DATA and nothing is sent. |
hiddenLinkLen | The length of the TTag, in bytes. |
data | The message; may be NULL when dataLen is 0 (the MAC of the empty message). |
dataLen | The length of the message, in bytes. |
mac | Output: the MAC, TE_HMAC_SHA384_LEN bytes. |
macLen | In: the capacity of mac. Out: TE_HMAC_SHA384_LEN. A capacity below TE_HMAC_SHA384_LEN is refused with TE_INSUFFICIENT_BUFFER_SIZE and macLen set to 48. |
See also: TE_HANDLE TEExportKey
Returns: Zero on success. A key server refusal returns its code under TE_SERVER_ERROR_MASK: no such key (the TTag names no key), the key's ACL refuses the caller, or no role grants the caller the operation – three different codes. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE TEEncryptStringBatch(TE_HANDLE h, TE_CSTRING_BUFFER *Ttag, TE_CSTRING_BUFFER *buffers, uint32_t count)
Encrypts a batch of C strings under one T-tag.
Parameters
| Parameter | Description |
|---|---|
h | A pointer to an unsigned 32-bit integer representing the handle. |
Ttag | The TTag descriptor. An input_len of zero asks the key server for a new T-tag, which is written back into data within capacity. |
buffers | An array of count descriptors. |
count | The number of descriptors, at most TE_MAX_CSTRING_BATCH. |
Remark: Each descriptor is both input and output: the plaintext is read from data / input_len and the base64 ciphertext is written back over it, so capacity must be large enough for the ciphertext plus its NUL.
See also: TE_HANDLE TE_CSTRING_BUFFER TEDecryptStringBatch
Returns: Zero on success. On TE_INSUFFICIENT_BUFFER_SIZE every descriptor's output_len holds the capacity it required and no caller buffer has been modified. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE TEDecryptStringBatch(TE_HANDLE h, TE_CSTRING_BUFFER *Ttag, TE_CSTRING_BUFFER *buffers, uint32_t count)
Decrypts a batch of C strings under one T-tag.
Parameters
| Parameter | Description |
|---|---|
h | A pointer to an unsigned 32-bit integer representing the handle. |
Ttag | The TTag descriptor. Read only: data and input_len are consumed and nothing is written back. |
buffers | An array of count descriptors. |
count | The number of descriptors, at most TE_MAX_CSTRING_BATCH. |
Remark: Each descriptor is both input and output: the base64 ciphertext is read from data / input_len and the plaintext is written back over it within capacity. The whole batch is decrypted into private storage and every capacity is validated before the first byte is committed, so a batch that cannot fit leaves ALL of the caller's buffers exactly as they were.
See also: TE_HANDLE TE_CSTRING_BUFFER TEEncryptStringBatch
Returns: Zero on success. On TE_INSUFFICIENT_BUFFER_SIZE every descriptor's output_len holds the capacity it required and no caller buffer has been modified. Detailed error information may be obtained by calling the GetLastTEError function.
TE_MATRIX_HANDLE TEMatrixCreate()
The TEMatrixCreate function creates a matrix handle.
Remark: Use with other Matrix functions
See also: TE_MATRIX_HANDLE
Returns: If the function succeeds, it will have a non-zero return value that represents the matrix. If the function fails, it will have a return value of zero. Detailed error information may be obtained by calling the GetLastTEError function.
void TEMatrixSetEncode(TE_MATRIX_HANDLE mh, uint32_t SetEnc)
The TEMatrixSetEncode function sets the encode method for when the get-method is called.
Parameters
| Parameter | Description |
|---|---|
mh | A pointer to an unsigned 32-bit integer representing the matrix handle. |
SetEnc | Encode mode. 1: data and the TTag are base-64 encoded when read from the matrix. 0: read from the matrix without encoding. |
Remark: Use with Matrix functions. 1: base64-encode data. 0: do nothing
See also: TE_MATRIX_HANDLE TEMatrixGetEncode
uint32_t TEMatrixGetEncode(TE_MATRIX_HANDLE mh)
The TEMatrixGetEncode function gets the encode method for the TE_MATRIX_HANDLE.
Parameters
| Parameter | Description |
|---|---|
mh | A pointer to an unsigned 32-bit integer representing the matrix handle. |
Remark: Use with Matrix functions.
See also: TE_MATRIX_HANDLE TEMatrixGetEncode
Returns: The encode mode. 1 means that data and TTag will be base-64 encoded when they are got from the matrix. 0 means that data and TTag will be got from the matrix without encoding.
void TEMatrixSetDecode(TE_MATRIX_HANDLE mh, uint32_t decode)
The TEMatrixSetDecode function sets the decode method for when the set-method is called.
Parameters
| Parameter | Description |
|---|---|
mh | A pointer to an unsigned 32-bit integer representing the matrix handle. |
decode | Decode mode. 1: data and the TTag are base-64 decoded when set into the matrix. 0: set into the matrix without decoding. |
Remark: Use with Matrix functions. 1: base64-encode data. 0: do nothing
See also: TE_MATRIX_HANDLE TEMatrixGetDecode
uint32_t TEMatrixGetDecode(TE_MATRIX_HANDLE mh)
The TEMatrixGetDecode function sets the decode method for when the set-method is called.
Parameters
| Parameter | Description |
|---|---|
mh | A pointer to an unsigned 32-bit integer representing the matrix handle. |
Remark: Use with Matrix functions. 1: base64-encoded data. 0: do nothing
See also: TE_MATRIX_HANDLE TEMatrixGetDecode
Returns: The decode mode. 1 means that data and TTag will be base-64 decoded when they are set to the matrix. 0 means that data and TTag will be set to the matrix without decoding.
TE_RETCODE TEMatrixSetElement(TE_MATRIX_HANDLE mh, uint32_t row, uint32_t col, const unsigned char *dbuff, uint32_t dsiz)
The TEMatrixSetElement function adds or changes elements.
Parameters
| Parameter | Description |
|---|---|
mh | A pointer to an unsigned 32-bit integer representing the matrix handle. |
row | A 32-bit unsigned integer representing the row. |
col | A 32-bit unsigned integer representing the column. |
dbuff | A unsigned string representing the data buffer. |
dsiz | A 32-bit unsigned integer representing the data size. |
Remark: Use with Matrix functions
See also: TE_MATRIX_HANDLE TEMatrixCreate
Returns: If the function succeeds, it will have a return value of zero. If the function fails, it will have a non-zero return value. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE TEMatrixGetElement(TE_MATRIX_HANDLE mh, uint32_t row, uint32_t col, unsigned char *dbuff, uint32_t dsiz, uint32_t *rdsiz)
The TEMatrixGetElement function returns an element.
Parameters
| Parameter | Description |
|---|---|
mh | A pointer to an unsigned 32-bit integer representing the matrix handle. |
row | A 32-bit unsigned integer representing the row |
col | A 32-bit unsigned integer representing the column |
dbuff | A unsigned string representing the data buffer |
dsiz | A 32-bit unsigned integer representing the data size |
rdsiz | A 32-bit unsigned integer representing the returned data size |
Remark: Use with Matrix functions
See also: TE_MATRIX_HANDLE TEMatrixCreate
Returns: If the function succeeds, it will have a return value of zero. If the function fails, it will have a non-zero return value. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE TEMatrixSetHiddenLink(TE_MATRIX_HANDLE mh, uint32_t row, const unsigned char *Ttagbuff, uint32_t TtagL)
The TEMatrixSetHiddenLink function sets the TTag for a matrix.
Parameters
| Parameter | Description |
|---|---|
mh | A pointer to an unsigned 32-bit integer representing the matrix handle. |
row | A 32-bit unsigned integer representing the row. |
Ttagbuff | A 32-bit unsigned string representing the TTag buffer. |
TtagL | A 32-bit unsigned integer representing the TTag length. |
Remark: Use with Matrix functions
See also: TE_MATRIX_HANDLE TEMatrixCreate
Returns: If the function succeeds, it will have a return value of zero. If the function fails, it will have a non-zero return value. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE TEMatrixGetHiddenLink(TE_MATRIX_HANDLE mh, uint32_t row, unsigned char *Ttagbuff, uint32_t Ttagsiz, uint32_t *TtagL)
The TEMatrixGetHiddenLink function gets the TTag for a matrix.
Parameters
| Parameter | Description |
|---|---|
mh | A pointer to an unsigned 32-bit integer representing the matrix handle. |
row | A 32-bit unsigned integer representing the row. |
Ttagbuff | A 32-bit unsigned string representing the TTag buffer. |
Ttagsiz | A 32-bit unsigned integer representing the TTag buffer size. |
TtagL | A 32-bit unsigned integer representing the TTag length. |
Remark: Use with Matrix functions
See also: TE_MATRIX_HANDLE TEMatrixCreate
Returns: If the function succeeds, it will have a return value of zero. If the function fails, it will have a non-zero return value. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE TEMatrixEncrypt(TE_HANDLE h, TE_MATRIX_HANDLE mh)
The TEMatrixEncrypt function encrypts a matrix.
Parameters
| Parameter | Description |
|---|---|
h | A pointer to an unsigned 32-bit integer representing the handle. |
mh | A pointer to an unsigned 32-bit integer representing the matrix handle. |
Remark: Use with Matrix functions.
See also: TE_MATRIX_HANDLE TE_HANDLE TEMatrixCreate.
Returns: If the function succeeds, it will have a return value of zero. If the function fails, it will have a non-zero return value. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE TEMatrixDecrypt(TE_HANDLE h, TE_MATRIX_HANDLE mh)
The TEMatrixDecrypt function decrypts a matrix.
Parameters
| Parameter | Description |
|---|---|
h | A pointer to an unsigned 32-bit integer representing the handle. |
mh | A pointer to an unsigned 32-bit integer representing the matrix handle. |
Remark: Use with Matrix functions.
See also: TE_MATRIX_HANDLE TE_HANDLE TEMatrixCreate.
Returns: If the function succeeds, it will have a return value of zero. If the function fails, it will have a non-zero return value. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE TEMatrixRelease(TE_MATRIX_HANDLE mh)
The TEMatrixRelease function releases a matrix.
Parameters
| Parameter | Description |
|---|---|
mh | A 32-bit unsigned integer representing the matrix handle. |
Remark: Use with Matrix functions.
See also: TE_MATRIX_HANDLE TEMatrixCreate.
Returns: If the function succeeds, it will have a return value of zero. If the function fails, it will have a non-zero return value. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE TEGetSystemId(TE_HANDLE h, uint32_t *SysID)
The TEGetSystemId function retrieves the System ID of an existing open connection to the Key Services.
Parameters
| Parameter | Description |
|---|---|
h | A pointer to an unsigned 32-bit integer representing the handle. |
SysID | A 32-bit unsigned integer representing the System ID |
Remark: The System ID can then be used in other functions
See also: TE_HANDLE
Returns: If the function succeeds, it will have a return value of zero. If the function fails, it will have a non-zero return value. Detailed error information may be obtained by calling the GetLastTEError function.
TE_RETCODE Hash(const char *szData, const unsigned long nDataSize, char *szHashed, unsigned long *nHashedSize, const char *szSalt, const unsigned long nSaltSize)
The Hash function hashes data.
Parameters
| Parameter | Description |
|---|---|
szData | A string of data. |
nDataSize | A unsigned long length of the data. |
szHashed | A string hash value buffer. |
nHashedSize | A unsigned long size of hash value buffer, output length of hash value. |
szSalt | A string of the salt used for hashing. |
nSaltSize | A unsigned long length of the salt. |
Remark: No connection needed. Uses SHA-256 (performHash v2); output is Base64 encoded (44 characters — size the buffer accordingly). v1 (SHA -1) outputs do not match v2 outputs and there is no compatibility mode. Note: Hash provides integrity/searchability, not strong pseudonymization of low-entropy data; for that, use a keyed construction (keyed API is a parked roadmap item).
See also: TE_MATRIX_HANDLE TEMatrixCreate.
Returns: If the function succeeds, it will have a return value of zero. If the function fails, it will have a non-zero return value. Detailed error information may be obtained by calling the GetLastTEError function.