tech.pisoft.teagent.TEKey

The TEKey class provides operations for creating, exporting and importing keys.

Since: 6.2.0

© Pi Soft, 2018-2026 · Tricryption Engine 8.1

Inheritance

• Inherits tech.pisoft.teagent.IConnection

Static Public Attributes

Type	Name	Description
int	KEY_FORMAT_NATIVE	An integer representing Native format.
int	KEY_FORMAT_RAW	An integer representing RAW format.
int	KEY_FORMAT_WRAPPED	An integer representing WRAPPED format: a key wrapped to the key server's RSA trust certificate, by rsa-oaep-sha256 or rsa-aes-kwp-sha256.
final int	RESULT_EXPIRED	Per-key result of expireKey: the key is now expired.
final int	RESULT_ALREADY_EXPIRED	Per-key result of expireKey: the key was already expired; nothing changed.
final int	RESULT_REMOVED	Per-key result of removeKey: the key, its access control list and every cached copy are deleted.
final int	RESULT_IMPORTED	Per-key result of importKey: the key is imported and the caller is its owner.
final int	RESULT_DUPLICATE	Per-key result of importKey: a key with that hidden link exists (expired or not); it was not overwritten.
final int	CODE_BAD_HIDDEN_LINK	The key server's refusal of a malformed (empty or too short) hidden link.
final int	CODE_NO_SUCH_KEY	The key server's refusal of a hidden link that names no key (never created, or removed).
final int	CODE_KEY_EXPIRED	The key server's refusal of any use of an expired key, on every key server of the deployment.

Static Public Member Functions

Member	Description
byte[] rawKeyBlob(String cipher, byte[] key, byte[] iv)	The RAW (3) key blob: the key server's export form – the cipher's NID (4 bytes, big-endian), the key, then the IV or none (the key server mints it).
byte[] wrappedKeyBlob(String method, String cipher, byte[] wrapped, byte[] iv)	The WRAPPED (4) key blob: version 1, the method, the cipher's NID (big-endian), the IV length and IV, then the wrapped key material, passed through unread.

Public Member Functions

Member	Description
TEKey()	The TEKey constructor is the default constructor.
void exportKey(String trustedServerName, Vector< TEKey.KeyPair > keys)	The exportKey Method is for exporting encryption keys in a vector of KeyPair objects for given trusted key server.
int[] importKey(Vector< TEKey.KeyPair > keys, int type)	The importKey Method is for importing encryption keys.
String createKey(String aclTemplateName)	The createKey method creates a new key with given ACL template name.
int[] expireKey(Collection< String > hls)	Expire keys.
int[] removeKey(Collection< String > hls)	Remove keys: each key's access control list, its stored key and every cached copy are deleted, on every key server of the deployment.

Member Function Documentation

byte[] rawKeyBlob(String cipher, byte[] key, byte[] iv)

The RAW (3) key blob: the key server's export form – the cipher's NID (4 bytes, big-endian), the key, then the IV or none (the key server mints it).

Parameters

Parameter	Description
cipher	AES-128-CBC, AES-192-CBC or AES-256-CBC
key	the key bytes, the cipher's key length. KEY MATERIAL: the blob IS the key.
iv	the cipher's IV length, or null

Returns: the blob for importKey(keys, KEY_FORMAT_RAW)

byte[] wrappedKeyBlob(String method, String cipher, byte[] wrapped, byte[] iv)

The WRAPPED (4) key blob: version 1, the method, the cipher's NID (big-endian), the IV length and IV, then the wrapped key material, passed through unread.

Parameters

Parameter	Description
method	"rsa-oaep-sha256" (RSA-OAEP, SHA-256, MGF1-SHA-256, of the key bytes) or "rsa-aes-kwp-sha256" (RSA-OAEP-SHA256 of a one-time AES-256 key, then that key's RFC 5649 wrap of the key bytes), both to the key server's trust certificate
cipher	AES-128-CBC, AES-192-CBC or AES-256-CBC
wrapped	the wrapped key material
iv	the cipher's IV length, or null for the key server to mint

Returns: the blob for importKey(keys, KEY_FORMAT_WRAPPED)

TEKey()

The TEKey constructor is the default constructor.

void exportKey(String trustedServerName, Vector< TEKey.KeyPair > keys)

The exportKey Method is for exporting encryption keys in a vector of KeyPair objects for given trusted key server.

Parameters

Parameter	Description
trustedServerName	A string representing the trusted server's friendly name.
keys	Vector of KeyPair objects. Input with TTag and output with encrypted key blobs. Try: Vector<TEKey.KeyPair> keys = new Vector<TEKey.KeyPair>()

Exceptions

Exception	Description
TEAgentException	if the request cannot be completed on the connection, or the Key Service returns an error for it (delivered as a TEServerException).

int[] importKey(Vector< TEKey.KeyPair > keys, int type)

The importKey Method is for importing encryption keys.

Parameters

Parameter	Description
keys	Vector of KeyPair objects. Input with TTag and encrypted key blobs. Try: Vector<TEKey.KeyPair> keys = new Vector<TEKey.KeyPair>()
type	KEY_FORMAT_NATIVE (0) – key blobs exported by a key server this one has an established trust with, needing the "Import Key" operation (the Exchanger role) – or KEY_FORMAT_RAW (3), raw keys (rawKeyBlob) under hidden links this key server mints and writes back into each KeyPair whose link is empty – or KEY_FORMAT_WRAPPED (4), keys wrapped to this key server's RSA trust certificate (wrappedKeyBlob), the same links. A non-empty link is the caller's identifier, kept as given; a refused key's link comes back empty. Any other type is refused with IllegalArgumentException.

Exceptions

Exception	Description
TEAgentException	if the request cannot be completed on the connection, or the Key Service returns an error for it (delivered as a TEServerException) – a request naming ONE pair that is refused is answered as an error.

Returns: one result per pair, in order: RESULT_IMPORTED (the caller owns the key), RESULT_DUPLICATE (a key with that hidden link exists, expired or not, and was not overwritten), or the key server's error code for that pair's refusal. Each pair is applied independently. An empty array for a null vector.

String createKey(String aclTemplateName)

The createKey method creates a new key with given ACL template name.

Parameters

Parameter	Description
aclTemplateName	A string representing the ACL template name.

Exceptions

Exception	Description
TEAgentException	if the request cannot be completed on the connection, or the Key Service returns an error for it (delivered as a TEServerException).

Returns: Base64 encoded string of TTag

int[] expireKey(Collection< String > hls)

Expire keys.

An expired key keeps its record and its access control list (readable, its expiration flag set), and every later use of it – decrypt, encrypt under its hidden link, export, an access-control update – is refused with CODE_KEY_EXPIRED (0x0406), on every key server of the deployment. An expiry is never undone; to delete a key use removeKey. Needs the "Expire Key" operation (the Encryptor role) and the OWNER right on each key.

Parameters

Parameter	Description
hls	collection of Hidden Links, canonical base64

Exceptions

Exception	Description
TEAgentException	if the request cannot be completed on the connection, or the Key Service refuses it – a request naming ONE key that is refused is answered as an error.

Returns: one result per hidden link, in iteration order: RESULT_EXPIRED, RESULT_ALREADY_EXPIRED, or the key server's error code for that key's refusal. Each key is applied independently; one refused key neither stops nor undoes the others.

int[] removeKey(Collection< String > hls)

Remove keys: each key's access control list, 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.

Parameters

Parameter	Description
hls	collection of Hidden Links, canonical base64

Exceptions

Exception	Description
TEAgentException	as expireKey

Returns: one result per hidden link, in iteration order: RESULT_REMOVED or the key server's error code for that key's refusal.