C API
#include "teagent_c.h"
The teagent_c.h header file contains the ERUCES 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_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 ERUCES services. |
TE_SSL_CONNECTION | A secure (TLS) connection to the ERUCES services. |
TE_RETCODE TEEnvInit() | The TEEnvInit function initializes the ERUCES client environment. |
TE_RETCODE TEEnvClose() | The TEEnvClose function closes the ERUCES client environment. |
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_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. |
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. |
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. |
String encryption
| Member | Description |
|---|---|
TE_RETCODE EncryptCStrings(TE_HANDLE h, char *Ttagbuff, uint32_t Ttagbuffsiz, uint32_t buffnum,...) | The EncryptCStrings function encrypt c-style strings (null terminated char arrays). |
TE_RETCODE DecryptCStrings(TE_HANDLE h, char *Ttagbuff, uint32_t buffnum,...) | The DecryptCStrings function decrypts c-style strings (null terminated char arrays). |
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 ERUCES 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 ERUCES 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_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_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. ie. AES-256-CBC, AES-192-CBC, AES-128-CBC or BF-CBC |
Remark: The System ID can then be used in other functions
See also: TE_HANDLE AES Blowfish 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_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 EncryptCStrings(TE_HANDLE h, char *Ttagbuff, uint32_t Ttagbuffsiz, uint32_t buffnum,...)
The EncryptCStrings function encrypt c-style strings (null terminated char arrays).
Parameters
| Parameter | Description |
|---|---|
h | A pointer to an unsigned 32-bit integer representing the handle. |
Ttagbuff | A string representing the TTag buffer |
Ttagbuffsiz | A 32-bit integer representing the TTag buffer size |
buffnum | A 32-bit unsigned integer representing the number of (data buffer, data buffer size) pairs that follow |
Remark: The System ID can then be used in other functions
See also: TE_HANDLE DecryptCStrings
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 DecryptCStrings(TE_HANDLE h, char *Ttagbuff, uint32_t buffnum,...)
The DecryptCStrings function decrypts c-style strings (null terminated char arrays).
Parameters
| Parameter | Description |
|---|---|
h | A pointer to an unsigned 32-bit integer representing the handle. |
Ttagbuff | A string representing the TTag buffer |
buffnum | A 32-bit unsigned integer representing the number of (data buffer, data buffer size) pairs that follow |
Remark: The System ID can then be used in other functions
See also: TE_HANDLE EncryptCStrings
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.