PISOFT::TEKey
#include <tekey.h>
The TEKey class provides operations for creating, exporting and importing keys.
© Pi Soft, 2018-2026 · Tricryption Engine 8.1
Inheritance
- Inherits PISOFT::TEAgent
Public Types
anonymous enum
| Value | Description |
|---|---|
NATIVE | Key blob format: the key wrapped to the recipient's certificate, the only format exportKey and importKey speak. The value is the wire's and is pinned. |
anonymous enum
The per-key results EXPIRE_KEY and IMPORT_KEY answer, one per hidden link (expire) or per pair (import), in request order. Any other value is the key server's error code for that key's refusal (for example 0x0404 ERR_NO_SUCH_KEY, 0x0300 ERR_AUTHORIZATION_FAILED, 0x0403 ERR_BAD_HIDDEN_LINK). RESULT_UNKNOWN means the key server answered no result for that key (a key server older than the per-key reply).
| Value | Description |
|---|---|
RESULT_EXPIRED | expire: the key is now expired |
RESULT_ALREADY_EXPIRED | expire: the key was already expired; nothing changed |
RESULT_REMOVED | removeKey: the key, its ACL and its cache entry are gone |
RESULT_IMPORTED | import: the key is imported and the importer owns it |
RESULT_DUPLICATE | import: a key with that hidden link exists; nothing was overwritten |
RESULT_UNKNOWN |
anonymous enum
The key server's refusal codes a key-lifecycle caller most often reads, as a per-key result or as TEException::getServerErrorCode() of a refused use.
| Value | Description |
|---|---|
CODE_BAD_HIDDEN_LINK | the hidden link is empty or too short to name a key |
CODE_NO_SUCH_KEY | no key under that hidden link (never created, or removed) |
CODE_KEY_EXPIRED | the key is expired: every use of it is refused, on every key server |
Public Member Functions
| Member | Description |
|---|---|
void createKey(_TESTD string &strHiddenLink, const _TESTD string &strACLTemplateName) | The createKey method creates a new key on the server and creates an ACL based on the name of the template. If the name of the template is not provided then default ACL is created. |
void createKey4File(const _TESTD string &path, _TESTD string &ttag) | The createKey4File method creates a new key on the server and creates ACL based on the name of a file path. If the name of the file path is not provided then default ACL is created. |
void getKey(void *keyData, unsigned int keyDataMaxLength, unsigned int &keyDataLength, _TESTD string &hiddenLink) | The getKey method retrieves a key. |
void exportKey(unsigned int certSystemId, te_oid certPrincipalId, KeyPair keyArray[], unsigned int numOfPairs) | The exportKey method exports key and uses the Key Service export blob specification. The user provides certificate id of the recipient, TTag and gets the export blob back. |
void exportKey(_TESTD string &trustedServerName, KeyPair keyArray[], unsigned int numOfPairs) | The exportKey method exports a key and uses the Key Service export blob specification. The user provides certificate id of the recipient, TTag and gets the export blob back. |
void importKey(KeyPair keyArray[], unsigned int numOfPairs) | The importKey method imports key exported by the Key Service using the TE format. |
void importKey(KeyPair keyArray[], unsigned int numOfPairs, uint32_t results[]) | The importKey method imports keys exported by the Key Service using the TE format, and returns one result per pair. |
uint64_t createKeyHandle(_TESTD string &strHiddenLink, const _TESTD string &strACLTemplateName) | The createKeyHandle method creates a new key on the server and creates an ACL based on the name of the template. If the name of the template is not provided then default ACL is created. |
uint64_t getKeyHandle(_TESTD string &strHiddenLink) | The getKeyHandle method gets a key handle from the Key Service. |
void expireKey(_TESTD string *hlArray[], unsigned int numOfLinks) | The expireKey method expires encryption key(s). |
void expireKey(_TESTD string *hlArray[], unsigned int numOfLinks, uint32_t results[]) | The expireKey method expires encryption key(s) and returns one result per key, in request order. |
void removeKey(_TESTD string *hlArray[], unsigned int numOfLinks) | The removeKey method deletes encryption key(s) from this key server. |
void removeKey(_TESTD string *hlArray[], unsigned int numOfLinks, uint32_t results[]) | The removeKey method deletes encryption key(s) and returns one result per key, in request order. |
Member Function Documentation
void createKey(_TESTD string &strHiddenLink, const _TESTD string &strACLTemplateName)
The createKey method creates a new key on the server and creates an ACL based on the name of the template. If the name of the template is not provided then default ACL is created.
Parameters
| Parameter | Description |
|---|---|
strHiddenLink | Output parameter. TTag (Binary Data). |
strACLTemplateName | Input Parameter. Name of the template to use for creating ACL for this Key. |
void createKey4File(const _TESTD string &path, _TESTD string &ttag)
The createKey4File method creates a new key on the server and creates ACL based on the name of a file path. If the name of the file path is not provided then default ACL is created.
Parameters
| Parameter | Description |
|---|---|
path | Input Parameter. Full path of a file used looking up for templated directory |
ttag | Output parameter. TTag (Binary Data). |
void getKey(void *keyData, unsigned int keyDataMaxLength, unsigned int &keyDataLength, _TESTD string &hiddenLink)
The getKey method retrieves a key.
When the TTag is empty, a key is generated and the TTag is provided. If the caller provides a TTag, it is used to retrieve the keyData. THIS FUNCTION HAS BEEN DEPRECATED. USE CREATE KEY INSTEAD.
DeprecatedUse createKey instead.
Parameters
| Parameter | Description |
|---|---|
keyData | Output parameter for key data. |
keyDataMaxLength | Max number bytes to write to keyData. |
keyDataLength | Output parameter for actual key data length. |
hiddenLink | Output parameter for TTag. |
void exportKey(unsigned int certSystemId, te_oid certPrincipalId, KeyPair keyArray[], unsigned int numOfPairs)
The exportKey method exports key and uses the Key Service export blob specification. The user provides certificate id of the recipient, TTag and gets the export blob back.
Parameters
| Parameter | Description |
|---|---|
certSystemId | : Certificate User (recipient) system Id. |
certPrincipalId | : Certificate User (recipient) principal Id. |
keyArray | : Contains TTag and empty blob(export key blob) pairs. |
numOfPairs | : Input param specifying number of elements in keyArray. |
void exportKey(_TESTD string &trustedServerName, KeyPair keyArray[], unsigned int numOfPairs)
The exportKey method exports a key and uses the Key Service export blob specification. The user provides certificate id of the recipient, TTag and gets the export blob back.
Parameters
| Parameter | Description |
|---|---|
trustedServerName | : Name of the recipient server. |
keyArray | : Contains TTag and empty blob(export key blob) pairs. |
numOfPairs | : Input param specifying number of elements in keyArray. |
void importKey(KeyPair keyArray[], unsigned int numOfPairs)
The importKey method imports key exported by the Key Service using the TE format.
Parameters
| Parameter | Description |
|---|---|
keyArray | : Contains TTag and exported key blob pairs. |
numOfPairs | : Input param specifying number of elements in keyArray. |
void importKey(KeyPair keyArray[], unsigned int numOfPairs, uint32_t results[])
The importKey method imports keys exported by the Key Service using the TE format, and returns one result per pair.
Each pair is imported independently: a duplicate (RESULT_DUPLICATE) or a refused pair neither stops nor undoes the others. A request naming ONE pair that is refused throws, as the overload above does; the overload above also throws when any pair of a batch is refused, after every other pair was applied.
Parameters
| Parameter | Description |
|---|---|
keyArray | : Contains TTag and exported key blob pairs. |
numOfPairs | : Input param specifying number of elements in keyArray. |
results | : Output, numOfPairs entries: RESULT_IMPORTED, RESULT_DUPLICATE or an error code. |
uint64_t createKeyHandle(_TESTD string &strHiddenLink, const _TESTD string &strACLTemplateName)
The createKeyHandle method creates a new key on the server and creates an ACL based on the name of the template. If the name of the template is not provided then default ACL is created.
Parameters
| Parameter | Description |
|---|---|
strHiddenLink | Output parameter. TTag (Binary Data). |
strACLTemplateName | Input Parameter. Name of the template to use for creating ACL for this Key. |
Returns: KeyHandle for local operations
uint64_t getKeyHandle(_TESTD string &strHiddenLink)
The getKeyHandle method gets a key handle from the Key Service.
Parameters
| Parameter | Description |
|---|---|
strHiddenLink | Input parameter. TTag (Binary Data). |
Returns: KeyHandle for local operations
void expireKey(_TESTD string *hlArray[], unsigned int numOfLinks)
The expireKey method expires encryption key(s).
An expired key keeps its record and its ACL (readable with getACL, its expiration flag set), and every later use of it – decrypt, encrypt under its TTag, export, an ACL update – is refused with ERR_KEY_EXPIRED (0x0406), on every key server of the deployment. An expiry is never undone; to delete a key use removeKey. Needs the Encryptor role's "Expire Key" and the OWNER right on each key. Throws when any key is refused, after every other key was applied.
Parameters
| Parameter | Description |
|---|---|
hlArray | : An array of TTag. |
numOfLinks | : Input param specifying number of elements in hlArray. |
void expireKey(_TESTD string *hlArray[], unsigned int numOfLinks, uint32_t results[])
The expireKey method expires encryption key(s) and returns one result per key, in request order.
Each key is applied independently: one refused key neither stops nor undoes the others. A request naming ONE key that is refused throws with the refusal's code.
Parameters
| Parameter | Description |
|---|---|
hlArray | : An array of TTag. |
numOfLinks | : Input param specifying number of elements in hlArray. |
results | : Output, numOfLinks entries: RESULT_EXPIRED, RESULT_ALREADY_EXPIRED or an error code (0x0404 ERR_NO_SUCH_KEY, 0x0300, 0x0302, 0x0403). |
void removeKey(_TESTD string *hlArray[], unsigned int numOfLinks)
The removeKey method deletes encryption key(s) from this key server.
Each key's ACL, its stored key and every cached copy are deleted, on every key server of the deployment. Irreversible on this key server, and local to it: a copy exported earlier (exportKey) can be imported again (importKey). An expired key may still be removed by its owner. Same rights as expireKey. Throws when any key is refused, after every other key was applied.
Parameters
| Parameter | Description |
|---|---|
hlArray | : An array of TTag. |
numOfLinks | : Input param specifying number of elements in hlArray. |
void removeKey(_TESTD string *hlArray[], unsigned int numOfLinks, uint32_t results[])
The removeKey method deletes encryption key(s) and returns one result per key, in request order.
Each key is applied independently. A request naming ONE key that is refused throws with the refusal's code.
Parameters
| Parameter | Description |
|---|---|
hlArray | : An array of TTag. |
numOfLinks | : Input param specifying number of elements in hlArray. |
results | : Output, numOfLinks entries: RESULT_REMOVED or an error code. |