SafeQuard Specification
====================================

.. _SafeQuard API Reference:

Exisiting Functions
^^^^^^^^^^^^^^^^^^^

pQCee_SafeQuard_enc
~~~~~~~~~~~~~~~~~~~

+----------------------+------------------------------------------------------------------------------------------------+
| Function             | pQCee_SafeQuard_enc                                                                            |
+----------------------+------------------------------------------------------------------------------------------------+
| Description          | Encrypts the toEncStr data using the SharedSecret obtained from encapsulation the PKStr.       |
|                      | Ciphertext obtained from encapsulation is used as nonce for AES ctr encryption.                |
+----------------------+------------------------------------------------------------------------------------------------+
|| Parameters          || - toEncStr                                                                                    |
||                     || - PKStr                                                                                       |
+----------------------+------------------------------------------------------------------------------------------------+
|| Output              || - returnStr                                                                                   |
+----------------------+------------------------------------------------------------------------------------------------+
| .. centered:: toEncStr                                                                                                |
+----------------------+------------------------------------------------------------------------------------------------+
| Type                 | String                                                                                         |
+----------------------+------------------------------------------------------------------------------------------------+
| Encoding             | Hexadecimal                                                                                    |
+----------------------+------------------------------------------------------------------------------------------------+
| Description          | The message string to be encrypted                                                             |
+----------------------+------------------------------------------------------------------------------------------------+
| .. centered:: PKStr                                                                                                   |
+----------------------+------------------------------------------------------------------------------------------------+
| Type                 | String                                                                                         |
+----------------------+------------------------------------------------------------------------------------------------+
| Encoding             | Hexadecimal                                                                                    |
+----------------------+------------------------------------------------------------------------------------------------+
| Description          | The ML-KEM-768 encapsulation key (decodes to 1184 bytes)                                       |
+----------------------+------------------------------------------------------------------------------------------------+
| .. centered:: returnStr                                                                                               |
+----------------------+------------------------------------------------------------------------------------------------+
| Type                 | String                                                                                         |
+----------------------+------------------------------------------------------------------------------------------------+
| Encoding             | Hexadecimal                                                                                    |
+----------------------+------------------------------------------------------------------------------------------------+
| Description          | Decodes to the AES-256-CTR encrypted message prepended with ciphertext, (first 12 bytes as IV) |
+----------------------+------------------------------------------------------------------------------------------------+

pQCee_SafeQuard_dec
~~~~~~~~~~~~~~~~~~~

+----------------------+------------------------------------------------------------------------------------------------+
| Function             | pQCee_SafeQuard_dec                                                                            |
+----------------------+------------------------------------------------------------------------------------------------+
| Description          | Decrypts the encrypted toDecStr data using the SharedSecret obtained from decapsulation        |
|                      | using the SKStr and Ciphertext (found in toDecStr)                                             |
+----------------------+------------------------------------------------------------------------------------------------+
|| Parameters          || - toDecStr                                                                                    |
||                     || - SKStr                                                                                       |
+----------------------+------------------------------------------------------------------------------------------------+
|| Output              || - returnStr                                                                                   |
+----------------------+------------------------------------------------------------------------------------------------+
| .. centered:: toDecStr                                                                                                |
+----------------------+------------------------------------------------------------------------------------------------+
| Type                 | String                                                                                         |
+----------------------+------------------------------------------------------------------------------------------------+
| Encoding             | Hexadecimal                                                                                    |
+----------------------+------------------------------------------------------------------------------------------------+
| Description          | Decodes to the AES-256-CTR encrypted message prepended with ciphertext, (first 12 bytes as IV) |
+----------------------+------------------------------------------------------------------------------------------------+
| .. centered:: SKStr                                                                                                   |
+----------------------+------------------------------------------------------------------------------------------------+
| Type                 | String                                                                                         |
+----------------------+------------------------------------------------------------------------------------------------+
| Encoding             | Hexadecimal                                                                                    |
+----------------------+------------------------------------------------------------------------------------------------+
| Description          | The ML-KEM-768 decapsulation key (decodes to 2400 bytes)                                       |
+----------------------+------------------------------------------------------------------------------------------------+
| .. centered:: returnStr                                                                                               |
+----------------------+------------------------------------------------------------------------------------------------+
| Type                 | String                                                                                         |
+----------------------+------------------------------------------------------------------------------------------------+
| Encoding             | Hexadecimal                                                                                    |
+----------------------+------------------------------------------------------------------------------------------------+
| Description          | The the decrypted message                                                                      |
+----------------------+------------------------------------------------------------------------------------------------+

pQCee_SafeQuard_AESInit
~~~~~~~~~~~~~~~~~~~~~~~

+----------------------+------------------------------------------------------------------------------------------------+
| Function             | pQCee_SafeQuard_AESInit                                                                        |
+----------------------+------------------------------------------------------------------------------------------------+
| Description          | Encapsulate the encapkey (public_key) to obtain the SharedSecret (to store in frontend memory) |
|                      | and Ciphertext (to be return) and loaded to the pQCee TEE Backend                              |
+----------------------+------------------------------------------------------------------------------------------------+
|| Parameters          || - PKStr (encapkey)                                                                            |
+----------------------+------------------------------------------------------------------------------------------------+
|| Output              || - returnStr (Ciphertext)                                                                      |
+----------------------+------------------------------------------------------------------------------------------------+
| .. centered:: PKStr                                                                                                   |
+----------------------+------------------------------------------------------------------------------------------------+
| Type                 | String                                                                                         |
+----------------------+------------------------------------------------------------------------------------------------+
| Encoding             | Hexadecimal                                                                                    |
+----------------------+------------------------------------------------------------------------------------------------+
| Description          | The ML-KEM-768 encapsulation key (decodes to 1184 bytes)                                       |
+----------------------+------------------------------------------------------------------------------------------------+
| .. centered:: returnStr                                                                                               |
+----------------------+------------------------------------------------------------------------------------------------+
| Type                 | String                                                                                         |
+----------------------+------------------------------------------------------------------------------------------------+
| Encoding             | Hexadecimal                                                                                    |
+----------------------+------------------------------------------------------------------------------------------------+
| Description          | The ML-KEM-768 ciphertext (decodes to 1088 bytes)                                              |
+----------------------+------------------------------------------------------------------------------------------------+

pQCee_SafeQuard_AESUpdate
~~~~~~~~~~~~~~~~~~~~~~~~~

+----------------------+------------------------------------------------------------------------------------------------+
| Function             | pQCee_SafeQuard_AESUpdate                                                                      |
+----------------------+------------------------------------------------------------------------------------------------+
| Description          | (En|De)crypts the toEncStr/toDecStr data using the SharedSecret store in frontend memory       |
+----------------------+------------------------------------------------------------------------------------------------+
|| Parameters          || - toEncStr/toDecStr                                                                           |
+----------------------+------------------------------------------------------------------------------------------------+
|| Output              || - returnStr                                                                                   |
+----------------------+------------------------------------------------------------------------------------------------+
| .. centered:: toEncStr/toDecStr                                                                                       |
+----------------------+------------------------------------------------------------------------------------------------+
| Type                 | String                                                                                         |
+----------------------+------------------------------------------------------------------------------------------------+
| Encoding             | Hexadecimal                                                                                    |
+----------------------+------------------------------------------------------------------------------------------------+
| Description          | Decodes to the AES-256-CTR message prepended with IV (16 bytes, 12 + 4(ctr))                   |
+----------------------+------------------------------------------------------------------------------------------------+
| .. centered:: returnStr                                                                                               |
+----------------------+------------------------------------------------------------------------------------------------+
| Type                 | String                                                                                         |
+----------------------+------------------------------------------------------------------------------------------------+
| Encoding             | Hexadecimal                                                                                    |
+----------------------+------------------------------------------------------------------------------------------------+
| Description          | The the encrypted/decrypted message                                                            |
+----------------------+------------------------------------------------------------------------------------------------+