4. SafeQuard Specification¶

4.1. Existing Functions¶

4.1.1. pQCee_SafeQuard_enc¶

Function	pQCee_SafeQuard_enc
Description	Encrypts the toEncStr data using the SharedSecret obtained from encapsulating the PKStr. Ciphertext obtained from encapsulation is used as IV for AES ctr encryption.
Parameters	- toEncStr - PKStr
Output	- returnStr
toEncStr
Type	String
Encoding	Standard base64
Description	The message string to be encrypted
PKStr
Type	String
Encoding	Standard base64
Description	The ML-KEM-768 encapsulation key (decodes to 1184 bytes)
returnStr
Type	String
Encoding	Standard base64
Description	Decodes to the AES-256-CTR encrypted message prepended with ML-KEM-768 ciphertext, where the first 12 bytes of the ML-KEM-768 ciphertext is used as IV for AES-256-CTR (IV-12Bytes \|\| Ciphertext-1076Bytes , Encrypted_Str) ciphertext and encrypted msg seperated with comma (,)

4.1.2. pQCee_SafeQuard_dec¶

Function	pQCee_SafeQuard_dec
Description	Decrypts the encrypted toDecStr data using the SharedSecret obtained from decapsulation using the ML-KEM-768 SKStr and Ciphertext
Parameters	- toDecStr - ciphertextStr - SKStr
Output	- returnStr
toDecStr
Type	String
Encoding	Standard base64
Description	Decodes to the AES-256-CTR encrypted message with the SKStr and ML-KEM-768 ciphertext, where the first 12 bytes of the ML-KEM-768 ciphertext is used as IV for AES-256-CTR
SKStr
Type	String
Encoding	Standard base64
Description	The ML-KEM-768 decapsulation key (decodes to 2400 bytes)
ciphertextStr
Type	String
Encoding	Standard base64
Description	The ML-KEM-768 ciphertext (decodes to 1184 bytes) where the first 12 bytes of the ML-KEM-768 ciphertext is used as IV for AES-256-CTR (IV-12Bytes \|\| Ciphertext-1076Bytes)
returnStr
Type	String
Encoding	Standard base64
Description	The decrypted message

4.1.3. pQCee_SafeQuard_macenc¶

Function	pQCee_SafeQuard_macenc
Description	Encrypts the toEncStr data (using AES-CTR) and generated SHA-256 hash (using AES-ECB) using the SharedSecret obtained from encapsulation as the key. Ciphertext obtained from encapsulation is used as IV for AES ctr encryption.
Parameters	- toEncStr - PKStr
Output	- returnStr
toEncStr
Type	String
Encoding	Standard base64
Description	The message string to be encrypted
PKStr
Type	String
Encoding	Standard base64
Description	The ML-KEM-768 encapsulation key (decodes to 1184 bytes)
returnStr
Type	String
Encoding	Standard base64
Description	Decodes to the AES-256-CTR encrypted message + AES-256-ECB encrypted_hash (Hash is double encrypted, AES-256-ECB then AES-256-CTR) prepended with ML-KEM-768 ciphertext, where the first 12 bytes of the ML-KEM-768 ciphertext is used as IV for AES-256-CTR (IV-12Bytes \|\| Ciphertext-1076Bytes , Encrypted_Str \|\| Encrypted_Hash-32Bytes) ciphertext and encrypted msg seperated with a comma (,)

4.1.4. pQCee_SafeQuard_macdec¶

Function	pQCee_SafeQuard_macdec
Description	Decrypts the encrypted toDecStr data using the SharedSecret obtained from decapsulation using the ML-KEM-768 SKStr and Ciphertext. Calculate the hash from the decrypted data, and encrypts the hash using AES-ECB and compares with the provided encrypted hash.
Parameters	- toDecStr - ciphertextStr - SKStr
Output	- returnStr
toDecStr
Type	String
Encoding	Standard base64
Description	Decodes to the AES-256-CTR encrypted message + AES-256-ECB encrypted_hash (Hash is double encrypted, AES-256-ECB then AES-256-CTR), (Encrypted_Str \|\| Encrypted_Hash-32Bytes)
ciphertextStr
Type	String
Encoding	Standard base64
Description	The ML-KEM-768 ciphertext (decodes to 1184 bytes) where the first 12 bytes of the ML-KEM-768 ciphertext is used as IV for AES-256-CTR (IV-12Bytes \|\| Ciphertext-1076Bytes)
SKStr
Type	String
Encoding	Standard base64
Description	The ML-KEM-768 decapsulation key (decodes to 2400 bytes)
returnStr
Type	String
Encoding	Standard base64
Description	The decrypted message

4.1.5. pQCee_SafeQuard_MLKEMkeygen¶

Function	pQCee_SafeQuard_MLKEMkeygen
Description	Generates a MLKEM-768 key pair and returns both the secret and public keys as a standard base64 string seperated with a comma, with the secret key followed by the public key
Parameters	none
Output	- returnStr
returnStr
Type	String
Encoding	Standard base64
Description	The MLKEM-768 secret and public key seperated by a comma. (SKStr-2400Bytes, PKStr-1184Bytes)

4.1.6. pQCee_SafeQuard_AESInit¶

Function	pQCee_SafeQuard_AESInit
Description	Encapsulate the encapkey (public_key) to obtain the SharedSecret (automatically stored in frontend memory) and Ciphertext (to be return) and loaded to the pQCee TEE Backend. (used in conjunction with pQCee_SafeQuard_AESUpdate)
Parameters	- PKStr (encapkey)
Output	- returnStr (Ciphertext)
PKStr
Type	String
Encoding	Standard base64
Description	The ML-KEM-768 encapsulation key (decodes to 1184 bytes)
returnStr
Type	String
Encoding	Standard base64
Description	The ML-KEM-768 ciphertext (decodes to 1088 bytes)

4.1.7. pQCee_SafeQuard_AESInitBE¶

Function	pQCee_SafeQuard_AESInitBE
Description	Decapsulate with the decapkey (SKStr) and ciphertext to obtain the SharedSecret that is automatically stored in backend memory (used in conjunction with pQCee_SafeQuard_AESUpdate)
Parameters	- SKStr (decapkey) - ciphertextStr
Output	none
SKStr
Type	String
Encoding	Standard base64
Description	The ML-KEM-768 encapsulation key (decodes to 1184 bytes)
ciphertextStr
Type	String
Encoding	Standard base64
Description	The ML-KEM-768 ciphertext (decodes to 1184 bytes) where the first 12 bytes of the ML-KEM-768 ciphertext is used as IV for AES-256-CTR (IV-12Bytes \|\| Ciphertext-1076Bytes)

4.1.8. pQCee_SafeQuard_AESUpdate¶

Function	pQCee_SafeQuard_AESUpdate
Description	(En\|De)crypts the toEncStr/toDecStr data using the SharedSecret stored in frontend/backend memory. (stored by calling pQCee_SafeQuard_AESInit/pQCee_SafeQuard_AESInitBE)
Parameters	- IVStr - toEncStr/toDecStr
Output	- returnStr
IVStr
Type	String
Encoding	Standard base64
Description	Decodes to the IV to be used by AES-256-CTR (16 bytes, 12 + 4(ctr))
toEncStr/toDecStr
Type	String
Encoding	Standard base64
Description	Decodes to the AES-256-CTR message
returnStr
Type	String
Encoding	Standard base64
Description	The encrypted/decrypted message

4.2. Flow diagram¶

4.2.1. Without TEE¶

The following diagram demonstrates work flow for safeQuard-demo running the safeQuard module.

        sequenceDiagram
     participant safeQuard
     participant Backend
     participant Frontend

     rect rgb(0, 255, 0)
         safeQuard -> Frontend: Start of Backend interaction
     end

     Backend ->> Frontend: serve_page
     Note over Frontend: Data
     Backend ->> safeQuard: pQCee_SafeQuard_<br>MLKEMkeygen()
     safeQuard ->> Frontend: response
     Note over Frontend: encapkey
     safeQuard ->> Backend: response
     Note over Backend: decapkey
     Frontend ->> safeQuard: pQCee_SafeQuard_enc(<br>Data, encapkey)
     safeQuard ->> Frontend: response
     Note over Frontend: CT, E_SS(Data)
     Frontend ->> Backend: submit
     Note over Backend: CT, E_SS(Data)
     Backend ->> safeQuard: pQCee_SafeQuard_<br>dec(E_SS(Data),<br>CT, decapkey)
     safeQuard ->> Backend: response
     Note over Backend: Data

     rect rgb(0, 255, 0)
         safeQuard -> Frontend: End of Backend interaction
     end

     rect rgb(0, 255, 0)
         safeQuard -> Frontend: Start of Frontend Decryption
     end

     Note over Backend: data
     Frontend ->> safeQuard: pQCee_SafeQuard_<br>MLKEMkeygen()
     safeQuard ->> Backend: response
     Note over Backend: encapkey2
     safeQuard ->> Frontend: response
     Note over Frontend: decapkey2
     Backend ->> safeQuard: pQCee_SafeQuard_<br>AESInit(encapkey2)
     Note over safeQuard: SS2 (Shared secret <br>stored in safeQuard)
     Backend ->> safeQuard: pQCee_SafeQuard_<br>AESUpdate(data)
     safeQuard ->> Backend: response
     Note over Backend: CT2, E_SS2(data)
     Backend ->> Frontend: Send(CT2, <br>E_SS2(data))
     Note over Frontend: CT2, E_SS(data)
     Frontend ->> safeQuard: pQCee_SafeQuard_<br>AESInitBE(decapkey2, CT2)
     Note over safeQuard: SS2 (Shared secret <br>stored in safeQuard)
     Frontend ->> safeQuard: pQCee_SafeQuard_<br>AESUpdate(E_SS(data))
     safeQuard ->> Frontend: Frontend
     Note over Frontend: data

     rect rgb(0, 255, 0)
         safeQuard -> Frontend: End of Frontend Decryption
     end

4.2.2. With TEE¶

The following diagram demonstrates the use of the pQCee TEE with a browser (safeQuard) running the safeQuard module.

        sequenceDiagram
     participant safeQuard
     participant Frontend
     participant Backend
     participant pQCee TEE

     rect rgb(0, 255, 0)
         safeQuard -> pQCee TEE: Start of AES Key Setup
     end

     Backend ->> Frontend: serve_page()
     Backend ->> pQCee TEE: mlkem_keygen()

     pQCee TEE ->> Frontend: response
     Note over Frontend: encapkey
     pQCee TEE ->> Backend: response
     Note over Backend: E_EK(decapkey)

     rect rgb(0, 255, 0)
         safeQuard -> pQCee TEE: End of AES Key Setup
     end

     rect rgb(0, 255, 0)
         safeQuard -> pQCee TEE: Start of Backend interaction
     end

     Backend ->> Frontend: serve_page()
     Note over Frontend: Data
     Backend ->> pQCee TEE: mlkem_keygen()
     pQCee TEE ->> Frontend: response
     Note over Frontend: encapkey2
     pQCee TEE ->> Backend: response
     Note over Backend: E_EK(decapkey2)
     Frontend ->> safeQuard: pQCee_SafeQuard_enc(<br>Data, encapkey2)
     safeQuard ->> Frontend: response
     Note over Frontend: E_SS2(Data), CT2
     Frontend ->> Backend: submit
     Note over Backend: E_SS2(Data), CT2
     Backend ->> pQCee TEE: mlkem_decrypt(<br>E_SS2(Data),<br>E_EK(decapkey2),<br>CT2)
     pQCee TEE ->> Backend: response
     Note over Backend: Data

     rect rgb(0, 255, 0)
         safeQuard -> pQCee TEE: End of Backend interaction
     end


     rect rgb(0, 255, 0)
         safeQuard -> pQCee TEE: Start of Frontend Decryption
     end

     Note over Backend: data
     Frontend ->> safeQuard: pQCee_SafeQuard_<br>AESInit(encapkey)
     Note over safeQuard: SS (Shared secret <br>stored in safeQuard)
     safeQuard ->> Backend: response
     Note over Backend: CT (Ciphertext)

     Backend ->> pQCee TEE: call_backend_encrypt(<br>data, <br>E_EK(decapkey),<br>CT)

     pQCee TEE ->> Frontend: response
     Note over Frontend: E_SS(data)
     Frontend ->> safeQuard: pQCee_SafeQuard_<br>AESUpdate(E_SS(data))
     safeQuard ->> Frontend: response
     Note over Frontend: data

     rect rgb(0, 255, 0)
         safeQuard -> pQCee TEE: End of Frontend Decryption
     end