SafeQuard Specification ==================================== .. _SafeQuard API Reference: Existing Functions ^^^^^^^^^^^^^^^^^^^ 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 | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: toEncStr | +----------------------+------------------------------------------------------------------------------------------------+ | Type | String | +----------------------+------------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +----------------------+------------------------------------------------------------------------------------------------+ | Description | The message string to be encrypted | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: PKStr | +----------------------+------------------------------------------------------------------------------------------------+ | Type | String | +----------------------+------------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +----------------------+------------------------------------------------------------------------------------------------+ | Description | The ML-KEM-768 encapsulation key (decodes to 1184 bytes) | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: 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 (,) | +----------------------+------------------------------------------------------------------------------------------------+ 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 | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: 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 | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: SKStr | +----------------------+------------------------------------------------------------------------------------------------+ | Type | String | +----------------------+------------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +----------------------+------------------------------------------------------------------------------------------------+ | Description | The ML-KEM-768 decapsulation key (decodes to 2400 bytes) | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: ciphertextStr | +----------------------+------------------------------------------------------------------------------------------------+ | Type | String | +----------------------+------------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +----------------------+------------------------------------------------------------------------------------------------+ | Description | The ML-KEM-768 ciphertext (decodes to 1088 bytes) where the first 12 bytes of the ML-KEM-768 | | | ciphertext is used as IV for AES-256-CTR (IV-12Bytes || Ciphertext-1076Bytes) | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: returnStr | +----------------------+------------------------------------------------------------------------------------------------+ | Type | String | +----------------------+------------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +----------------------+------------------------------------------------------------------------------------------------+ | Description | The decrypted message | +----------------------+------------------------------------------------------------------------------------------------+ 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 | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: toEncStr | +----------------------+------------------------------------------------------------------------------------------------+ | Type | String | +----------------------+------------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +----------------------+------------------------------------------------------------------------------------------------+ | Description | The message string to be encrypted | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: PKStr | +----------------------+------------------------------------------------------------------------------------------------+ | Type | String | +----------------------+------------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +----------------------+------------------------------------------------------------------------------------------------+ | Description | The ML-KEM-768 encapsulation key (decodes to 1184 bytes) | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: 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 (,) | +----------------------+------------------------------------------------------------------------------------------------+ 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 | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: 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) | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: ciphertextStr | +----------------------+------------------------------------------------------------------------------------------------+ | Type | String | +----------------------+------------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +----------------------+------------------------------------------------------------------------------------------------+ | Description | The ML-KEM-768 ciphertext (decodes to 1088 bytes) where the first 12 bytes of the ML-KEM-768 | | | ciphertext is used as IV for AES-256-CTR (IV-12Bytes || Ciphertext-1076Bytes) | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: SKStr | +----------------------+------------------------------------------------------------------------------------------------+ | Type | String | +----------------------+------------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +----------------------+------------------------------------------------------------------------------------------------+ | Description | The ML-KEM-768 decapsulation key (decodes to 2400 bytes) | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: returnStr | +----------------------+------------------------------------------------------------------------------------------------+ | Type | String | +----------------------+------------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +----------------------+------------------------------------------------------------------------------------------------+ | Description | The decrypted message | +----------------------+------------------------------------------------------------------------------------------------+ 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 | +-------------------------+----------------------------------------------------------------------------------------------+ | .. centered:: returnStr | | +-------------------------+----------------------------------------------------------------------------------------------+ | Type | String | +-------------------------+----------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +-------------------------+----------------------------------------------------------------------------------------------+ | Description | The MLKEM-768 secret and public key seperated by a comma. (SKStr-2400Bytes, PKStr-1184Bytes) | +-------------------------+----------------------------------------------------------------------------------------------+ 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) | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: PKStr | +----------------------+------------------------------------------------------------------------------------------------+ | Type | String | +----------------------+------------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +----------------------+------------------------------------------------------------------------------------------------+ | Description | The ML-KEM-768 encapsulation key (decodes to 1184 bytes) | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: returnStr | +----------------------+------------------------------------------------------------------------------------------------+ | Type | String | +----------------------+------------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +----------------------+------------------------------------------------------------------------------------------------+ | Description | The ML-KEM-768 ciphertext (decodes to 1088 bytes) | +----------------------+------------------------------------------------------------------------------------------------+ 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 | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: SKStr | +----------------------+------------------------------------------------------------------------------------------------+ | Type | String | +----------------------+------------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +----------------------+------------------------------------------------------------------------------------------------+ | Description | The ML-KEM-768 encapsulation key (decodes to 1184 bytes) | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: ciphertextStr | +----------------------+------------------------------------------------------------------------------------------------+ | Type | String | +----------------------+------------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +----------------------+------------------------------------------------------------------------------------------------+ | Description | The ML-KEM-768 ciphertext (decodes to 1088 bytes) where the first 12 bytes of the ML-KEM-768 | | | ciphertext is used as IV for AES-256-CTR (IV-12Bytes || Ciphertext-1076Bytes) | +----------------------+------------------------------------------------------------------------------------------------+ 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 | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: IVStr | +----------------------+------------------------------------------------------------------------------------------------+ | Type | String | +----------------------+------------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +----------------------+------------------------------------------------------------------------------------------------+ | Description | Decodes to the IV to be used by AES-256-CTR (16 bytes, 12 + 4(ctr)) | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: toEncStr/toDecStr | +----------------------+------------------------------------------------------------------------------------------------+ | Type | String | +----------------------+------------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +----------------------+------------------------------------------------------------------------------------------------+ | Description | Decodes to the AES-256-CTR message | +----------------------+------------------------------------------------------------------------------------------------+ | .. centered:: returnStr | +----------------------+------------------------------------------------------------------------------------------------+ | Type | String | +----------------------+------------------------------------------------------------------------------------------------+ | Encoding | Standard base64 | +----------------------+------------------------------------------------------------------------------------------------+ | Description | The encrypted/decrypted message | +----------------------+------------------------------------------------------------------------------------------------+ .. _SafeQuard Sequence Diagram: Flow diagram ^^^^^^^^^^^^ Without TEE ~~~~~~~~~~~ The following diagram demonstrates work flow for safeQuard-demo running the safeQuard module. .. mermaid:: 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_
MLKEMkeygen() safeQuard ->> Frontend: response Note over Frontend: encapkey safeQuard ->> Backend: response Note over Backend: decapkey Frontend ->> safeQuard: pQCee_SafeQuard_enc(
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_
dec(E_SS(Data),
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_
MLKEMkeygen() safeQuard ->> Backend: response Note over Backend: encapkey2 safeQuard ->> Frontend: response Note over Frontend: decapkey2 Backend ->> safeQuard: pQCee_SafeQuard_
AESInit(encapkey2) Note over safeQuard: SS2 (Shared secret
stored in safeQuard) Backend ->> safeQuard: pQCee_SafeQuard_
AESUpdate(data) safeQuard ->> Backend: response Note over Backend: CT2, E_SS2(data) Backend ->> Frontend: Send(CT2,
E_SS2(data)) Note over Frontend: CT2, E_SS(data) Frontend ->> safeQuard: pQCee_SafeQuard_
AESInitBE(decapkey2, CT2) Note over safeQuard: SS2 (Shared secret
stored in safeQuard) Frontend ->> safeQuard: pQCee_SafeQuard_
AESUpdate(E_SS(data)) safeQuard ->> Frontend: Frontend Note over Frontend: data rect rgb(0, 255, 0) safeQuard -> Frontend: End of Frontend Decryption end With TEE ~~~~~~~~ The following diagram demonstrates the use of the pQCee TEE with a browser (safeQuard) running the safeQuard module. .. mermaid:: 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(
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(
E_SS2(Data),
E_EK(decapkey2),
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_
AESInit(encapkey) Note over safeQuard: SS (Shared secret
stored in safeQuard) safeQuard ->> Backend: response Note over Backend: CT (Ciphertext) Backend ->> pQCee TEE: call_backend_encrypt(
data,
E_EK(decapkey),
CT) pQCee TEE ->> Frontend: response Note over Frontend: E_SS(data) Frontend ->> safeQuard: pQCee_SafeQuard_
AESUpdate(E_SS(data)) safeQuard ->> Frontend: response Note over Frontend: data rect rgb(0, 255, 0) safeQuard -> pQCee TEE: End of Frontend Decryption end