sgx_tseal.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257
  1. /*
  2. * Copyright (C) 2011-2016 Intel Corporation. All rights reserved.
  3. *
  4. * Redistribution and use in source and binary forms, with or without
  5. * modification, are permitted provided that the following conditions
  6. * are met:
  7. *
  8. * * Redistributions of source code must retain the above copyright
  9. * notice, this list of conditions and the following disclaimer.
  10. * * Redistributions in binary form must reproduce the above copyright
  11. * notice, this list of conditions and the following disclaimer in
  12. * the documentation and/or other materials provided with the
  13. * distribution.
  14. * * Neither the name of Intel Corporation nor the names of its
  15. * contributors may be used to endorse or promote products derived
  16. * from this software without specific prior written permission.
  17. *
  18. * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19. * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20. * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21. * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22. * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23. * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24. * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25. * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26. * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27. * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28. * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29. *
  30. */
  31. #ifndef _SGX_TSEAL_H_
  32. #define _SGX_TSEAL_H_
  33. #include <stddef.h>
  34. #include <stdint.h>
  35. #include "sgx_key.h"
  36. #include "sgx_error.h"
  37. #include "sgx_defs.h"
  38. #include "sgx_attributes.h"
  39. #include "sgx_tcrypto.h"
  40. #define SGX_SEAL_TAG_SIZE SGX_AESGCM_MAC_SIZE
  41. #define SGX_SEAL_IV_SIZE 12
  42. typedef struct _aes_gcm_data_t
  43. {
  44. uint32_t payload_size; /* 0: Size of the payload which includes both the encrypted data and the optional additional MAC text */
  45. uint8_t reserved[12]; /* 4: Reserved bits */
  46. uint8_t payload_tag[SGX_SEAL_TAG_SIZE]; /* 16: AES-GMAC of the plain text, payload, and the sizes */
  47. uint8_t payload[]; /* 32: The payload data which includes the encrypted data followed by the optional additional MAC text */
  48. } sgx_aes_gcm_data_t;
  49. typedef struct _sealed_data_t
  50. {
  51. sgx_key_request_t key_request; /* 00: The key request used to obtain the sealing key */
  52. uint32_t plain_text_offset; /* 64: Offset within aes_data.playload to the start of the optional additional MAC text */
  53. uint8_t reserved[12]; /* 68: Reserved bits */
  54. sgx_aes_gcm_data_t aes_data; /* 80: Data structure holding the AES/GCM related data */
  55. } sgx_sealed_data_t;
  56. #ifdef __cplusplus
  57. extern "C" {
  58. #endif
  59. /* sgx_calc_sealed_data_size
  60. * Purpose: This function is used to determine how much memory to allocate for sgx_sealed_data_t structure.
  61. *
  62. * Paramters:
  63. * add_mac_txt_size - [IN] Length of the optional additional data stream in bytes
  64. * txt_encrypt_size - [IN] Length of the data stream to be encrypted in bytes
  65. *
  66. * Return Value:
  67. * uint32_t - The minimum number of bytes that need to be allocated for the sgx_sealed_data_t structure
  68. * If the function fails, the return value is UINT32_MAX
  69. */
  70. uint32_t sgx_calc_sealed_data_size(const uint32_t add_mac_txt_size, const uint32_t txt_encrypt_size);
  71. /* sgx_get_add_mac_txt_len
  72. * Purpose: This function is used to determine how much memory to allocate for the additional_MAC_text buffer
  73. *
  74. * Parameter:
  75. * p_sealed_data - [IN] Pointer to the sgx_sealed_data_t structure which was populated by the sgx_seal_data function
  76. *
  77. * Return Value:
  78. * uint32_t - The number of bytes in the optional additional MAC buffer
  79. */
  80. uint32_t sgx_get_add_mac_txt_len(const sgx_sealed_data_t* p_sealed_data);
  81. /* sgx_get_encrypt_txt_len
  82. *
  83. * Parameter:
  84. * p_sealed_data - [IN] Pointer to the sgx_sealed_data_t structure which was populated by the sgx_seal_data function
  85. *
  86. * Return Value:
  87. * uint32_t - The number of bytes in the encrypted data buffer
  88. * If the function fails, the return value is UINT32_MAX
  89. */
  90. uint32_t sgx_get_encrypt_txt_len(const sgx_sealed_data_t* p_sealed_data);
  91. /* sgx_seal_data
  92. * Purpose: This algorithm is used to AES-GCM encrypt the input data. Specifically,
  93. * two input data sets can be provided, one is the text to encrypt (p_text2encrypt)
  94. * the second being optional additional text that should not be encrypted but will
  95. * be part of the GCM MAC calculation.
  96. * The sgx_sealed_data_t structure should be allocated prior to the API call and
  97. * should include buffer storage for the MAC text and encrypted text.
  98. * The sgx_sealed_data_t structure contains the data required to unseal the data on
  99. * the same system it was sealed.
  100. *
  101. * Parameters:
  102. * additional_MACtext_length - [IN] length of the plaintext data stream in bytes
  103. * The additional data is optional and thus the length
  104. * can be zero if no data is provided
  105. * p_additional_MACtext - [IN] pointer to the plaintext data stream to be GCM protected
  106. * The additional data is optional. You may pass a NULL pointer
  107. * but additional_MACtext_length must be zero in that case
  108. * text2encrypt_length - [IN] length of the data stream to encrypt in bytes
  109. * p_text2encrypt - [IN] pointer to data stream to encrypt
  110. * sealed_data_size - [IN] Size of the sealed data buffer passed in
  111. * p_sealed_data - [OUT] pointer to the sealed data structure containing protected data
  112. *
  113. * Return Value:
  114. * sgx_status_t - SGX Error code
  115. */
  116. sgx_status_t SGXAPI sgx_seal_data(const uint32_t additional_MACtext_length,
  117. const uint8_t *p_additional_MACtext,
  118. const uint32_t text2encrypt_length,
  119. const uint8_t *p_text2encrypt,
  120. const uint32_t sealed_data_size,
  121. sgx_sealed_data_t *p_sealed_data);
  122. /* sgx_seal_data_ex
  123. * Purpose: Expert version of sgx_seal_data which is used if the key_policy/attribute_mask/misc_mask
  124. * need to be modified from the default values.
  125. *
  126. * Parameters:
  127. * key_policy - [IN] Specifies the measurement to use in key derivation
  128. * attribute_mask - [IN] Identifies which platform/enclave attributes to use in key derivation
  129. * misc_mask - [IN] The mask for MISC_SELECT
  130. * additional_MACtext_length - [IN] length of the plaintext data stream in bytes
  131. * The additional data is optional and thus the length
  132. * can be zero if no data is provided
  133. * p_additional_MACtext - [IN] pointer to the plaintext data stream to be GCM protected
  134. * The additional data is optional. You may pass a NULL pointer
  135. * but additional_MACtext_length must be zero in that case
  136. * text2encrypt_length - [IN] length of the data stream to encrypt in bytes
  137. * p_text2encrypt - [IN] pointer to data stream to encrypt
  138. * sealed_data_size - [IN] Size of the sealed data buffer passed in
  139. * p_sealed_data - [OUT] pointer to the sealed data structure containing protected data
  140. *
  141. * Return Value:
  142. * sgx_status_t - SGX Error code
  143. */
  144. sgx_status_t SGXAPI sgx_seal_data_ex(const uint16_t key_policy,
  145. const sgx_attributes_t attribute_mask,
  146. const sgx_misc_select_t misc_mask,
  147. const uint32_t additional_MACtext_length,
  148. const uint8_t *p_additional_MACtext,
  149. const uint32_t text2encrypt_length,
  150. const uint8_t *p_text2encrypt,
  151. const uint32_t sealed_data_size,
  152. sgx_sealed_data_t *p_sealed_data);
  153. /* sgx_unseal_data
  154. * Purpose: Unseal the sealed data structure passed in and populate the MAC text and decrypted text
  155. * buffers with the appropriate data from the sealed data structure.
  156. *
  157. * Parameters:
  158. * p_sealed_data - [IN] pointer to the sealed data structure containing protected data
  159. * p_additional_MACtext - [OUT] pointer to the plaintext data stream which was GCM protected
  160. * The additiona data is optional. You may pass a NULL pointer but
  161. * p_additional_MACtext_length must be zero in that case
  162. * p_additional_MACtext_length - [IN/OUT] pointer to length of the plaintext data stream in bytes
  163. * If there is not additional data, this parameter should be zero.
  164. * p_decrypted_text - [OUT] pointer to decrypted data stream
  165. * p_decrypted_text_length - [IN/OUT] pointer to length of the decrypted data stream to encrypt in bytes
  166. *
  167. * Return Value:
  168. * sgx_status_t - SGX Error code
  169. */
  170. sgx_status_t SGXAPI sgx_unseal_data(const sgx_sealed_data_t *p_sealed_data,
  171. uint8_t *p_additional_MACtext,
  172. uint32_t *p_additional_MACtext_length,
  173. uint8_t *p_decrypted_text,
  174. uint32_t *p_decrypted_text_length);
  175. /* sgx_mac_aadata
  176. * Purpose: Use AES-GCM algorithm to generate a sealed data structure with integrity protection.
  177. * Specifically, the input data set is ONLY the plaintext data stream, or
  178. * additional authenticated data(AAD), no encrypt data.
  179. * The sgx_sealed_data_t structure should be allocated prior to the API call and
  180. * should include buffer storage for the plaintext data.
  181. * The sgx_sealed_data_t structure contains the data required to unseal the data on
  182. * the same system it was sealed.
  183. *
  184. * Parameters:
  185. * additional_MACtext_length - [IN] length of the plaintext data stream in bytes
  186. * p_additional_MACtext - [IN] pointer to the plaintext data stream to be GCM protected
  187. * sealed_data_size - [IN] Size of the sealed data buffer passed in
  188. * p_sealed_data - [OUT] pointer to the sealed data structure containing protected data
  189. *
  190. * Return Value:
  191. * sgx_status_t - SGX Error code
  192. */
  193. sgx_status_t sgx_mac_aadata(const uint32_t additional_MACtext_length,
  194. const uint8_t *p_additional_MACtext,
  195. const uint32_t sealed_data_size,
  196. sgx_sealed_data_t *p_sealed_data);
  197. /* sgx_mac_aadata_ex
  198. * Purpose: Expert version of sgx_mac_aadata which is used if the key_policy/attribute_mask/misc_mask
  199. * need to be modified from the default values.
  200. *
  201. * Parameters:
  202. * key_policy - [IN] Specifies the measurement to use in key derivation
  203. * attribute_mask - [IN] Identifies which platform/enclave attributes to use in key derivation
  204. * misc_mask - [IN] The mask for MISC_SELECT
  205. * additional_MACtext_length - [IN] length of the plaintext data stream in bytes
  206. * p_additional_MACtext - [IN] pointer to the plaintext data stream to be GCM protected
  207. * sealed_data_size - [IN] Size of the sealed data buffer passed in
  208. * p_sealed_data - [OUT] pointer to the sealed data structure containing protected data
  209. *
  210. * Return Value:
  211. * sgx_status_t - SGX Error code
  212. */
  213. sgx_status_t sgx_mac_aadata_ex(const uint16_t key_policy,
  214. const sgx_attributes_t attribute_mask,
  215. const sgx_misc_select_t misc_mask,
  216. const uint32_t additional_MACtext_length,
  217. const uint8_t *p_additional_MACtext,
  218. const uint32_t sealed_data_size,
  219. sgx_sealed_data_t *p_sealed_data);
  220. /* sgx_unmac_aadata
  221. * Purpose: Unseal the sealed data structure passed in and populate the plaintext data stream
  222. * with the appropriate data from the sealed data structure.
  223. *
  224. * Parameters:
  225. * p_sealed_data - [IN] pointer to the sealed data structure containing protected data
  226. * p_additional_MACtext - [OUT] pointer to the plaintext data stream which was GCM protected
  227. * p_additional_MACtext_length - [IN/OUT] pointer to length of the plaintext data stream in bytes
  228. *
  229. * Return Value:
  230. * sgx_status_t - SGX Error code
  231. */
  232. sgx_status_t sgx_unmac_aadata(const sgx_sealed_data_t *p_sealed_data,
  233. uint8_t *p_additional_MACtext,
  234. uint32_t *p_additional_MACtext_length);
  235. #ifdef __cplusplus
  236. }
  237. #endif
  238. #endif